Contacts 디바이스 API 가이드 프로그램

Contacts 디바이스 API 가이드 프로그램은 모바일 스마트 디바이스의 Contacts 관련 기능을 JavaScript 기반으로 제어 및 확인할 수 있도록 지원한다.
또한, 연락처 조회 기능과 연락처 정보를 서버로 백업하기 기능, 백업된 연락처 정보로 복구하기 기능 구현 시 참고 및 활용될 수 있도록 한다.

본 가이드 프로그램 에서는 Contacts 기능을 가이드 할 수 있도록 연락처 조회 기능, 연락처 정보 백업 기능,
백업된 연락처로 복구 기능 를 제공하고 있다.

• 문제 : 폰갭 오류시.
• 해결방안 : setTimeout() 함수로 phonegap 로딩 순서를 지연시킨다.
  

    document.addEventListener('DOMContentLoaded', function () { setTimeout(loaded, 200); }, false);

• 문제 : iScroll5 컨텐츠 내용 높이 계산 오류.
• 해결방안 : setTimeout() 함수로 컨텐츠에 css 적용이 완료되고 iscroll 생성이 되도록 한다.

setTimeout(function()
           {
               myScroll = new iScroll(thisPage, 
                                      { 
                                          checkDOMChanges: true,
                                          onBeforeScrollStart:function(e)
                                          {
                                          }
                                      });
           },
           500);

• 문제 : 폰갭 라이브러리를 사용해서 연락처를 복원할때 복원된 ID는 새로 부여된다.
• 해결 방안 : 복원된 새로운 ID를 서버로 동기화 하여 해결.

function fn_egov_contactIdUpdate() 
{
    if(fn_egov_network_check(false))        // 통신 이벤트 발생시 3G 사용자 승인여부 판단
    {
        var params = {contactsList : {contactsList : JSON.stringify(recoveryParam)}};
        
        $.mobile.showPageLoadingMsg('a');
        // 디바이스의 성능에 따라 PrograssDialog Show 가 완전이 로딩이 된후 다음 코드를 수행하도록 setTimeout 을 사용하여 지연시킨다.
        setTimeout(function()
                   {
                       fn_egov_sendto_server("/ctt/updateContactsiOS.do",params);
                   }, 
                   500);
    }
}

폰갭에서 특정 외부 도메인이나 외부 도메인의 하위 도메인을 사용해야할 경우,
[Project_Name]/Supproting Files/config.xml에서 <access origin=“ExternalHosts”/> 항목에 외부 도메인 주소를 추가 설정해야 외부 도메인에 접속할 수 있다.

N/A

Contacts 디바이스API 가이드 프로그램은 크게 Contacts 연락처 조회, 연락처 정보 백업, 백업된 연락처로 복구
기능으로 구성되어 있다.

• 연락처 객체를 생성한다.

var myContact = navigator.contacts.create({"displayName": "Test User"});

• 연락처를 검색 한다.
  

navigator.contacts.find(contactFields, contactSuccess, contactError, contactFindOptions);

var options = new ContactFindOptions();
options.filter="Bob"; 
var fields = ["displayName", "name"];
navigator.contacts.find(fields, onSuccess, onError, options);

• 연락처를 저장 한다.

// create a new contact object
var contact = navigator.contacts.create();
contact.displayName = "Plumber";    // not support iOS
contact.nickname = "Plumber";       //specify both to support all devices

// populate some fields
var name = new ContactName();
name.givenName = "Jane";
name.familyName = "Doe";
contact.name = name;

// save to device
contact.save(onSuccess,onError);

• 연락처를 복사 한다.

var clone = contact.clone();
clone.name.givenName = "John";
console.log("Original contact name = " + contact.name.givenName);
console.log("Cloned contact name = " + clone.name.givenName);

• 연락처를 제거 한다.

function onSuccess() {
    alert("Removal Success");
};

function onError(contactError) {
    alert("Error = " + contactError.code);
};

// remove the contact from the device
contact.remove(onSuccess,onError);

- contactFields

- ContactName

- ContactField

- ContactAddress

- ContactOrganization

- ContactFindOption

- ContactError

Contacts 디바이스 API 가이드 프로그램에서 제공하는 모바일 디바이스의 Contacts 관련 기능을 활용하기 위하여 필요한 항목 및 그 환경 설정은 다음과 같다.

    <feature name="Contacts">
        <param name="ios-package" value="CDVContacts"/>
    </feature>

<sqlMap resource="egovframework/sqlmap/hyb/ios/ctt/EgovContactsiOSAPIGuide_SQL_[DB명].xml"/>

Contacts 디바이스API 가이드 프로그램은 크게 Contacts 연락처 조회, 연락처 정보 백업, 백업된 연락처로 복구 기능으로 구성되어 있다.

function fn_egov_move_localContactList()
{
    // 최초 실행시 사용자 승인 여부 체크
    if(check3G)
    {
        if(fn_egov_network_check(true))        // 최초 앱 실행시 3G 사용자 승인여부 판단
        {
            check3G = false;
        }
        return;
    }
    
    $.mobile.showPageLoadingMsg('a');
    var obj = new ContactFindOptions();
    obj.filter = "";
    obj.multiple = true;
    var fields = ["*"];
    navigator.contacts.find(fields, fn_egov_contactListSuccess, fn_egov_fail, obj);
}

function fn_egov_contactListSuccess(contacts) 
{
    console.log("DeviceAPIGuide fn_egov_contactListSuccess");
    
    var theList = $('#listView');
    theList.html("");
    contactsList = contacts;	
    nPageCount = 0;
    fn_egov_showList(true);
	
    $.mobile.hidePageLoadingMsg('a');
    ProcessName = "contactList";
    $.mobile.changePage("#contactList", "slide", false, false);
	
    theList.listview("refresh");
	
    setTimeout(loadiScrollList, 1000);
}

function fn_egov_move_localContactDetail(index)
{
    var displayName = "";
    var phoneNumber = "";
    var email = "";
    var ContactName = "";
    
    if(contactsList[index].name.formatted != null) 
    {
        ContactName = contactsList[index].name.formatted;
    }
	
    if(contactsList[index].phoneNumbers != null) 
    {
    	for(var j=0; j<contactsList[index].phoneNumbers.length; j++) 
        {
    	    if(contactsList[index].phoneNumbers[j].type == "mobile")
            {
    		phoneNumber = contactsList[index].phoneNumbers[j].value;
    		break;
    	    }
        }
    }
    if(contactsList[index].emails != null)
    {
        for(var j=0; j<contactsList[index].emails.length; j++) 
        {
            email = contactsList[index].emails[j].value;
            break;
        }
    }
    
    document.getElementById('detailIndex').value = index;
    document.getElementById('detailName').value = ContactName;
    document.getElementById('detailPhone').value = phoneNumber;
    document.getElementById('detailEmail').value = email;
    ProcessName = "contactDetail";
    $.mobile.changePage("#contactDetail", "slide", false, false);
}

function fn_egov_contactLocalDelete() {

var index = $("#detailIndex").val();
contactsList[index].remove(fn_egov_removeSuccess,fn_egov_fail);

} </code>

리스트:연락처의 상세 조회를 호출한다.
+ 10개더보기:연락처 목록 10개를 더 보여준다.
삭제:연락처를 삭제 한다

function fn_egov_contactBackupCountSuccess(contacts) 
{	
    console.log("DeviceAPIGuide fn_egov_contactBackupCountSuccess");
    contactsList = contacts;
    
    var params = {uuid :  device.uuid};
	
    $.mobile.showPageLoadingMsg('a');
    // 디바이스의 성능에 따라 PrograssDialog Show 가 완전이 로딩이 된후 다음 코드를 수행하도록 setTimeout 을 사용하여 지연시킨다.
    setTimeout(function()
               {
                   fn_egov_sendto_server("/ctt/selectBackupCountiOS.do",params);
               }, 
               500);
}

function fn_egov_contactBackup() 
{
    if(contactsList.length == 0) 
    {
        return;
    }
    
    if(fn_egov_network_check(false))        // 통신 이벤트 발생시 3G 사용자 승인여부 판단
    {
        $.mobile.showPageLoadingMsg('a');
        ProcessName = "contactBackup";   
        var param = [];	
        for(var index = 0; index < contactsList.length ; index++) 
        {
            var displayName = '';
            var phoneNumber = '';
            var email = '';
            
            if(contactsList[index].name.formatted != null) 
            {
                displayName = contactsList[index].name.formatted;
            }
            
            if(contactsList[index].phoneNumbers != null) 
            {
                for(var j=0; j<contactsList[index].phoneNumbers.length; j++) 
                {
                    if(contactsList[index].phoneNumbers[j].type == "mobile")
                    {
                        phoneNumber = contactsList[index].phoneNumbers[j].value;
                        break;
                    }
                }
            }
            if(contactsList[index].emails != null) 
            {
                for(var j=0; j<contactsList[index].emails.length; j++) 
                {
                    email = contactsList[index].emails[j].value;
                    break;
                }
            }
            
            param.push({uuid:device.uuid, id:contactsList[index].id, name:encodeURIComponent(displayName), telNo:phoneNumber, useYn:'Y', emails:email});
        }
        
        var params = {contactsList : {contactsList : JSON.stringify(param)}};
        // var params = {contactsList : {contactsList : param}};
        // 디바이스의 성능에 따라 PrograssDialog Show 가 완전이 로딩이 된후 다음 코드를 수행하도록 setTimeout 을 사용하여 지연시킨다.
        setTimeout(function()
                   {
                       fn_egov_sendto_server("/ctt/addContactsiOSInfo.do",params);
                   }, 
                   500);
    }
}

연락처백업:디바이스의 연락처를 서버로 백업한다.

function fn_egov_contactBackupCountSuccess(contacts) 
{	
    console.log("DeviceAPIGuide fn_egov_contactBackupCountSuccess");
    contactsList = contacts;
    
    var params = {uuid :  device.uuid};
	
    $.mobile.showPageLoadingMsg('a');
    // 디바이스의 성능에 따라 PrograssDialog Show 가 완전이 로딩이 된후 다음 코드를 수행하도록 setTimeout 을 사용하여 지연시킨다.
    setTimeout(function()
               {
                   fn_egov_sendto_server("/ctt/selectBackupCountiOS.do",params);
               }, 
               500);
}

function contactRecoveryCallBack(ContactData)
{
    var id = ContactData["id"];
    var name = ContactData["name"];
    var telNo = ContactData["telNo"];
    var email = ContactData["emails"];
    
    var options = new ContactFindOptions();
    options.filter=String(id); 
    var fields = ["id"];
    navigator.contacts.find(fields, 
                            function(contacts)
                            {					    						          
                                if(contacts.length != 0) 
                                {
                                    contacts[0].remove(function(contact){},fn_egov_fail);
                                }
                            
                                var contactname = new ContactName();
                                contactname.middleName = name;
                            
                                var myContact = navigator.contacts.create({"name":contactname});
                            
                                var phoneNumbers = [2];
                                phoneNumbers[0] = new ContactField('work', telNo, false);
                                phoneNumbers[1] = new ContactField('mobile', telNo, false); 
                                phoneNumbers[2] = new ContactField('home', telNo, false); 
                                myContact.phoneNumbers = phoneNumbers;
                            
                                var emails = [2];
                                emails[0] = new ContactField('work', email, false);
                                emails[1] = new ContactField('home', email, false);
                                myContact.emails = emails;
                            
                                myContact.save(function(contact)
                                               {					            		
                                                   recoveryParam.push({uuid:device.uuid, contactId:id, newId:contact.id});
                                                   if(listCount === recoveryParam.length)
                                                   {
                                                       $.mobile.hidePageLoadingMsg('a');
                                                       confirm(String(listCount) + '개의 연락처가 복원되었습니다. 저장된 연락처 정보를 서버와 동기화 합니다.');
                                                       $.mobile.showPageLoadingMsg('a');
                                                       fn_egov_contactIdUpdate();	
                                                   }
                                               },fn_egov_fail);					            					            	
                            
			    }, function(contactError){}, options);
}

function fn_egov_contactIdUpdate() 
{
    if(fn_egov_network_check(false))        // 통신 이벤트 발생시 3G 사용자 승인여부 판단
    {
        var params = {contactsList : {contactsList : JSON.stringify(recoveryParam)}};
        
        $.mobile.showPageLoadingMsg('a');
        // 디바이스의 성능에 따라 PrograssDialog Show 가 완전이 로딩이 된후 다음 코드를 수행하도록 setTimeout 을 사용하여 지연시킨다.
        setTimeout(function()
                   {
                       fn_egov_sendto_server("/ctt/updateContactsiOS.do",params);
                   }, 
                   500);
    }
}

연락처복원:서버에 백업된 연락처로 복구한다.

1. ContactsAPI 설치하러 가기
   
2. ContactsAPI 프로젝트의 설치 상태를 확인하고 빌드를 클릭한다
   
   

• 빌드가 성공하고 나면 다음과 같은 화면이 실행된다.
  
  

1. Web Server 설치하러 가기
   
2. 프로젝트 우클릭>Run as>Maven install 을 클릭하여 빌드를 한다.
   
   
3. 빌드 성공 (콘솔 정보 확인)
   
   
4. 프로젝트 우클릭>Run as>Run on Server 를 클릭하여 실행시킨다.
   
   
5. 프로젝트가 성공적으로 실행되었는지 확인한다.
   
   

디바이스 어플리케이션에서 발생한 오류 내용 확인 및 디버깅을 위해서는 폰갭 프레임워크에서 제공하는 console.log를 이용할 수 있다. console.log 함수는 자바스크립트 구문에서 사용할 수 있는 디버그 코드로 이클립스 및 Xcode에서 확인 할 수 있다.

• 실제 콘솔 로그 예

function fn_egov_network_check(doCheck)
{
    console.log('DeviceAPIGuide fn_egov_network_check');
    var networkState = navigator.network.connection.type;
    ...
}

• xCode 콘솔 창

• Organizer 로그 창

Contacts 디바이스 API 가이드 다운로드 : Click

• UX/UI 라이브러리 : jQuery MobileClick
  
• Phonegap 4.3.0 : Click