Contacts 디바이스 API 가이드 프로그램은 모바일 스마트 디바이스의 Contacts 관련 기능을 JavaScript 기반으로 제어 및 확인할 수 있도록 지원한다.
또한, 연락처 조회 기능과 연락처 정보를 서버로 백업하기 기능, 백업된 연락처 정보로 복구하기 기능 구현 시 참고 및 활용될 수 있도록 한다.
본 가이드 프로그램 에서는 Contacts 기능을 가이드 할 수 있도록 연락처 조회 기능, 연락처 정보 백업 기능,
백업된 연락처로 복구 기능 를 제공하고 있다.
구분 | 내용 |
---|---|
Local 디바이스 개발 환경 | Xcode 4.4.1, PhoneGap 1.9.0 |
서버 사이드 개발 환경 | 전자정부표준프레임워크 개발환경2.5 |
Mash up Open API 연계 | N/A |
테스트 디바이스 | iPhone4 |
테스트 플랫폼 | iOS 5.1 |
추가 라이브러리 적용 | N/A |
document.addEventListener('DOMContentLoaded', function () { setTimeout(loaded, 200); }, false);
setTimeout(function() { myScroll = new iScroll(thisPage, { checkDOMChanges: true, onBeforeScrollStart:function(e) { } }); }, 500);
Xcode 4.5부터 iOS 6, iPhone 5를 지원하는데, 해당 디바이스와 OS를 지원을 할 경우 PhoneGap 1.9.0의 라이브러리는 Xcode 4.4.1에서 컴파일되어 배포되는 라이브러리라 프로젝트 옵션을 조정할 필요가 있다.
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); } }
폰갭에서 특정 외부 도메인이나 외부 도메인의 하위 도메인을 사용해야할 경우,
Resource/Cordova.plist에서 <key>ExternalHosts</key> 항목에 외부 도메인 주소를 추가 설정해야 외부 도메인에 접속할 수 있다.
N/A
Contacts 디바이스API 가이드 프로그램은 크게 Contacts 연락처 조회, 연락처 정보 백업, 백업된 연락처로 복구
기능으로 구성되어 있다.
유형 | 대상소스 | 비고 |
---|---|---|
CSS | www/css/egovframwork/mbl/hyb/ContactsAPI.css | ContactsAPI 가이드 프로그램 주요 Cascading Style Sheets |
IMAGE | www/images/egovframwork/mbl/hyb/ | ContactsAPI 가이드 프로그램 주요 Image 폴더 |
JS | www/js/egovframwork/mbl/hyb/ContactsAPI.js | ContactsAPI 가이드 프로그램 주요 JavaScript |
HTML | www/ContactsAPI.html | ContactsAPI 메인 페이지 |
HTML | www/license.html | ContactsAPI 라이센스 페이지 |
HTML | www/overview.html | ContactsAPI 기능설명 페이지 |
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
Properties | 객체구조 | 비고 |
---|---|---|
ID | (DOMString) | 글로벌 고유 식별자. |
displayName | (DOMString) | 최종 사용자에게 표시하기에 적합이 연락처의 이름. |
name | (ContactName) | 명 이름의 모든 구성 요소를 포함하는 개체입니다. |
nickname | (DOMString) | 연락을하여 해결할 수있는 캐주얼 이름. |
phoneNumbers | (ContactField []) | 모든 연락처의 전화 번호의 배열입니다. |
(ContactField []) | 모든 연락처의 이메일 주소의 배열입니다. | |
addresses | (ContactAddress []) | 연락처의 주소를 모든 배열입니다. |
ims | (ContactField []) | 모든 연락처의 IM 주소의 배열입니다. |
organizations | (ContactOrganization []) | 연락처의 조직 전체의 배열입니다. |
birthday | Date | 연락처의 생일. (일) |
note | (DOMString) | 연락처에 대한 참고 사항. |
photo | (ContactField []) | 연락처의 사진의 배열입니다. |
categories | (ContactField []) | 사용자 정의 범주의 모든 연락처의 배열입니다. |
urls | (ContactField []) | 연락처에 관련된 웹 페이지의 배열입니다. |
- ContactName
Properties | 객체구조 | 비고 |
---|---|---|
formatted | (DOMString) | 연락처의 전체 이름 |
familyName | (DOMString) | |
givenName | (DOMString) | |
middleName | (DOMString) | |
honorificPrefix | (DOMString) | 연락처 접두사 |
honorificSuffix | (DOMString) | 연락처 접미사 |
- ContactField
Properties | 객체구조 | 비고 |
---|---|---|
type | (DOMString) | 필드의 종류를 구분할수 있는 문자열 |
value | (DOMString) | 필드의 값 |
pref | (Boolean) | 선호 가치 표시 |
- ContactAddress
Properties | 객체구조 | 비고 |
---|---|---|
pref | (boolean) | ContactAddress 객체의 대표 값 여부 |
type | (DOMString) | 필드 유형을 정의한다 |
formatted | (DOMString) | 출력을 위한 전체 주소 |
streetAddress | (DOMString) | 동 / 읍 / 면 / 가 와 같은 전체 주소 |
locality | (DOMString) | ’시’ / ‘도’ 표기 |
region | (DOMString) | ’주’ / ‘지방’ 표기 |
postalCode | (DOMString) | 우편번호 |
country | (DOMString) | 국번 |
- ContactOrganization
Properties | 객체구조 | 비고 |
---|---|---|
pref | (Boolean) | ContactOrganization 객체의 대표 값 여부 |
type | (DOMString) | 필드 유형을 정의한다(예: ‘work’ 은 직장.) |
name | (DOMString) | 소속의 이름을 정의한다 |
department | (DOMString) | 소속 부서를 정의한다 |
title | (DOMString) | 소속 내의 직함을 정의한다 |
- ContactFindOption
Properties | 객체구조 | 비고 |
---|---|---|
filter | (DOMString) | 검색어 또는 검색조건을 정의한다. (Default: ””) |
multiple | (Boolean) | 검색 결과으로 다수의 연락처를 가져올 것인지의 여부 |
- ContactError
Properties | 객체구조 | 비고 |
---|---|---|
ContactError.UNKNOWN_ERROR | (DOMString) | 알수 없는 에러 |
ContactError.INVALID_ARGUMENT_ERROR | (DOMString) | 잘못된 인자값 |
ContactError.TIMEOUT_ERROR | (DOMString) | 응답시간 지연 |
ContactError.PENDING_OPERATION_ERROR | (DOMString) | 잘못된 명령 |
ContactError.IO_ERROR | (DOMString) | 입출력 에러 |
ContactError.NOT_SUPPORTED_ERROR | (DOMString) | 지원하지 않음 |
ContactError.PERMISSION_DENIED_ERROR | (DOMString) | 권한 에러 |
유형 | 대상소스 | 비고 |
---|---|---|
Controller | egovframework.hyb.ios.ctt.web.EgovContactsiOSAPIController.java | 연락처 정보 관리를 위한 클래스 |
Service | egovframework.hyb.ios.ctt.service.EgovContactsiOSAPIService.java | 연락처 정보 관리를 위한 서비스 인터페이스 |
VO | egovframework.hyb.ios.ctt.service.ContactsiOSAPIDefaultVO.java | 연락처 관리를 위한 VO 클래스 |
VO | egovframework.hyb.ios.ctt.service.ContactsiOSAPIVO.java | 연락처 관리를 위한 VO 클래스 |
DAO | egovframework.hyb.ios.ctt.service.impl.ContactsiOSAPIDAO.java | 연락처 관리를 위한 데이터처리 클래스 |
DAO | egovframework.hyb.ios.ctt.service.impl.EgovContactsiOSAPIServiceImpl.java | 요청 서비스 처리를 위한 클래스 |
Query XML | resources/egovframework/sqlmap/hyb/ios/ctt/EgovContactsiOSAPIGuide_SQL_mysql.xml | 연락처 관리를 위한 Query 파일 |
테이블명 | 테이블명(영문) | 비고 |
---|---|---|
연락처 | Contacts | 연락처 백업 정보 |
No. | 컬럼 | 컬럼명 | 타입 | 길이 | Null | KEY |
---|---|---|---|---|---|---|
1 | ID | 일련번호 | VARCHAR | 20 | NotNull | pk |
2 | UUID | UUID | VARCHAR | 50 | NotNull | pk |
3 | NAME | 이름 | VARCHAR | 60 | Null | |
4 | TELNO | 전화번호 | VARCHAR | 20 | Null | |
5 | EMAILS | 이메일 | VARCHAR | 50 | Null | |
6 | USEYN | 활성화여부 | CHAR | 1 | Null |
Contacts 디바이스 API 가이드 프로그램에서 제공하는 모바일 디바이스의 Contacts 관련 기능을 활용하기 위하여 필요한 항목 및 그 환경 설정은 다음과 같다.
<dict> <key>Contacts</key> <string>CDVContacts</string> </dict>
<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>
기능 | _URL_ | Controller | method | 화면(HTML) |
---|---|---|---|---|
연락처 목록 조회 | fn_egov_contactListSuccess | ContactsAPI.html#contactList | ||
연락처 상세 조회 | fn_egov_move_localContactDetail | ContactsAPI.html#contactDetail | ||
연락처 삭제 | fn_egov_contactLocalDelete | ContactsAPI.html#contactDetail |
리스트:연락처의 상세 조회를 호출한다.
+ 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); } }
기능 | _URL_ | Controller | method | 화면(HTML) |
---|---|---|---|---|
백업된 연락처 총 갯수 조회 | /ctt/selectBackupCountiOS.do | EgovContactsiOSAPIController | selectContactsCount | ContactsAPI.html#contactBackup |
연락처 백업 요청 | /ctt/addContactsiOSInfo.do | EgovContactsiOSAPIController | addContactsInfoXml | ContactsAPI.html#contactBackup |
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); } }
기능 | _URL_ | Controller | method | 화면(HTML) |
---|---|---|---|---|
백업된 연락처 총 갯수 조회 | /ctt/selectBackupCountiOS.do | EgovContactsiOSAPIController | selectContactsCount | ContactsAPI.html#contactBackup |
백업된 연락처로 복구 | /ctt/contactsiOSInfoList.do | EgovContactsiOSAPIController | selectContactsInfoListXml | ContactsAPI.html#contactRecovery |
복구한 연락처 서버로 동기화 | /ctt/updateContactsiOS.do | EgovContactsiOSAPIController | updateContactsiOS | ContactsAPI.html#contactRecovery |
디바이스 어플리케이션에서 발생한 오류 내용 확인 및 디버깅을 위해서는 폰갭 프레임워크에서 제공하는 console.log를 이용할 수 있다. console.log 함수는 자바스크립트 구문에서 사용할 수 있는 디버그 코드로 이클립스 및 Xcode에서 확인 할 수 있다.
function fn_egov_network_check(doCheck) { console.log('DeviceAPIGuide fn_egov_network_check'); var networkState = navigator.network.connection.type; ... }
로그 메시지 | 값 | 비고 |
---|---|---|
DeviceAPIGuide fn_egov_network_check | 네트워크 상태 체크 | |
DeviceAPIGuide fn_egov_contactListSuccess | 디바이스내 연락처 목록 조회 성공 | |
DeviceAPIGuide fn_egov_fail + errorCode | 에러코드 사유로 인해 Contacts Device API 실패 | |
DeviceAPIGuide fn_egov_removeSuccess | 연락처 삭제 성공 | |
DeviceAPIGuide fn_egov_sendto_server Response Completed | 서버에 요청한 내용이 성공적으로 처리 된 경우 | |
DeviceAPIGuide fn_egov_sendto_server Response Failed | 서버 내부 처리 오류 | |
DeviceAPIGuide fn_egov_sendto_server Request Failed | 통신 오류 | |
DeviceAPIGuide fn_egov_contactBackupCountSuccess | 백업된 연락처 갯수 조회 성공 | |
DeviceAPIGuide fn_egov_contactRecoveryCountSuccess | 연락처 복구 하기전 조회 성공 |
Contacts 디바이스 API 가이드 다운로드 : Click