====== Contacts 디바이스 API 가이드 프로그램 ======
===== 개요 =====
Contacts 디바이스 API 가이드 프로그램은 모바일 스마트 디바이스의 Contacts 관련 기능을 JavaScript 기반으로 제어 및 확인할 수 있도록 지원한다. \\
또한, 연락처 조회 기능과 연락처 정보를 서버로 백업하기 기능, 백업된 연락처 정보로 복구하기 기능 구현 시 참고 및 활용될 수 있도록 한다. \\
==== 특징 ====
본 가이드 프로그램 에서는 Contacts 기능을 가이드 할 수 있도록 **연락처 조회 기능**, **연락처 정보 백업 기능**, \\
**백업된 연락처로 복구 기능** 를 제공하고 있다. \\
==== 기능 흐름도 ====
{{:egovframework:hyb:guide:ios:연락처기능흐름도.png?740|}}
==== 기능 시퀀스 ====
{{:egovframework:hyb:guide:add:Contacts시퀀스다이어그램.png|}}
==== 전제 조건 ====
^ 구분 ^ 내용 ^
| Local 디바이스 개발 환경 |Xcode 6.3.2, PhoneGap 4.3.0|
| 서버 사이드 개발 환경 |전자정부표준프레임워크 개발환경 3.5|
| Mash up Open API 연계 |N/A|
| 테스트 디바이스 |iPhone4, iPhone6 |
| 테스트 플랫폼 |iOS 7.1.2, iOS 8.3 |
| 추가 라이브러리 적용 |N/A|
==== 제약 사항 ====
=== 지원 디바이스 및 플랫폼 ===
== iPhone 의 경우 장치의 연산속도에 따른 문제가 발생할 수 있다. ==
* 문제 : 폰갭 오류시.
* 해결방안 : 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는 새로 부여된다.
* 해결 방안 : 복원된 새로운 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에서 항목에 외부 도메인 주소를 추가 설정해야 외부 도메인에 접속할 수 있다.
=== 라이선스 ===
N/A
===== 설명 =====
Contacts 디바이스API 가이드 프로그램은 크게 Contacts **연락처 조회**, **연락처 정보 백업**, **백업된 연락처로 복구** \\
기능으로 구성되어 있다.
==== 관련 클래스다이어그램 ====
{{:egovframework:hyb:guide:ios:diagramcontacts.jpg?1024|}}
==== Device Application ====
=== 관련 소스 ===
^유형^대상소스^비고^
| 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 기능설명 페이지|
=== 활용 API ===
== contacts.create ==
* 연락처 객체를 생성한다.
var myContact = navigator.contacts.create({"displayName": "Test User"});
== contacts.find ==
* 연락처를 검색 한다.\\
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 [])**|모든 연락처의 전화 번호의 배열입니다.|
|email|**(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)|권한 에러|
==== Server Application ====
=== 관련 소스 ===
^유형^대상소스^비고^
|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| |
=== ERD ===
{{:egovframework:hyb:guide:ios:erd.jpg|}}
===== 환경 설정 =====
Contacts 디바이스 API 가이드 프로그램에서 제공하는 모바일 디바이스의 Contacts 관련 기능을 활용하기 위하여 필요한 항목 및 그 환경 설정은 다음과 같다.
==== Device Application ====
=== config.xml ===
==== Server Aplication ====
=== resource/egovframework/sqlmap/sql-map-config_[DB명].xml ===
===== 관련 기능 =====
Contacts 디바이스API 가이드 프로그램은 크게 Contacts **연락처 조회**, **연락처 정보 백업**, **백업된 연락처로 복구** 기능으로 구성되어 있다.
==== 연락처 조회 ====
=== 비즈니스 규칙 ===
== 1. 네트워크를 체크하여 Wi-Fi가 아닐 경우에는 사용자 승인여부에 따라 동작한다. ==
=== 관련 코드 ===
== 연락처를 조회 한다 ==
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
== 연락처 삭제 ==
function fn_egov_contactLocalDelete()
{
var index = $("#detailIndex").val();
contactsList[index].remove(fn_egov_removeSuccess,fn_egov_fail);
}
=== 관련 화면 및 수행매뉴얼 ===
^기능^_URL_^Controller^method^화면(HTML)^
|연락처 목록 조회| | |fn_egov_contactListSuccess|ContactsAPI.html#contactList|
|연락처 상세 조회| | |fn_egov_move_localContactDetail|ContactsAPI.html#contactDetail|
|연락처 삭제| | |fn_egov_contactLocalDelete|ContactsAPI.html#contactDetail|
{{:egovframework:hyb:guide:iOS:연락처목록조회.png?320|}} {{:egovframework:hyb:guide:iOS:연락처상세조회.png?320|}}\\
리스트:연락처의 상세 조회를 호출한다. \\
+ 10개더보기:연락처 목록 10개를 더 보여준다. \\
삭제:연락처를 삭제 한다
==== 연락처 정보 백업 ====
=== 비즈니스 규칙 ===
== 1. 네트워크를 체크하여 Wi-Fi가 아닐 경우에는 사용자 승인여부에 따라 동작한다. ==
== 2. 연락처 백업시 이전에 백업된 연락처와 같은 ID 는 업데이트 없는 ID 는 새로 추가한다. ==
=== 관련 코드 ===
== 서버에 백업된 연락처 총 갯수 요청 ==
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
=== 관련 화면 및 수행매뉴얼 ===
^기능^_URL_^Controller^method^화면(HTML)^
|백업된 연락처 총 갯수 조회|/ctt/selectBackupCountiOS.do|EgovContactsiOSAPIController|selectContactsCount|ContactsAPI.html#contactBackup|
|연락처 백업 요청|/ctt/addContactsiOSInfo.do|EgovContactsiOSAPIController|addContactsInfoXml|ContactsAPI.html#contactBackup|
{{:egovframework:hyb:guide:iOS:연락처백업.png?320|}} \\
연락처백업:디바이스의 연락처를 서버로 백업한다.
==== 백업된 연락처로 복구하기 ====
=== 비즈니스 규칙 ===
== 1. 네트워크를 체크하여 Wi-Fi가 아닐 경우에는 사용자 승인여부에 따라 동작한다. ==
== 2. 연락처 복구시 디바이스의 연락처와 백업된 연락처가 겹치는 경우 디바이스의 연락처를 삭제하고 백업된 연락처로 복구 한다. ==
=== 관련 코드 ===
== 서버에 백업된 연락처 총 갯수 요청 ==
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|
{{:egovframework:hyb:guide:iOS:연락처복구.png?320|}}\\
연락처복원:서버에 백업된 연락처로 복구한다.
===== 컴파일 디버깅 배포 =====
==== 컴파일 ====
=== Device Application ===
- [[ |ContactsAPI 설치하러 가기]]\\
- ContactsAPI 프로젝트의 설치 상태를 확인하고 빌드를 클릭한다\\ {{:egovframework:hyb:guide:ios:contacts빌드.png?700|}} \\
* 빌드가 성공하고 나면 다음과 같은 화면이 실행된다.\\ {{:egovframework:hyb:guide:ios:contacts실행.png?320|}} \\
=== Server Application ===
- [[ |Web Server 설치하러 가기]]\\
- 프로젝트 우클릭>Run as>Maven install 을 클릭하여 빌드를 한다.\\ {{:egovframework:hyb:guide:ios:웹서버빌드.png?700|}} \\
- 빌드 성공 (콘솔 정보 확인)\\ {{:egovframework:hyb:guide:ios:웹서버빌드성공.png?700|}} \\
- 프로젝트 우클릭>Run as>Run on Server 를 클릭하여 실행시킨다.\\ {{:egovframework:hyb:guide:ios:웹서버실행.png?700|}} \\
- 프로젝트가 성공적으로 실행되었는지 확인한다. \\ {{:egovframework:hyb:guide:ios:웹서버실행성공.png?700|}} \\
==== 디버깅 ====
디바이스 어플리케이션에서 발생한 오류 내용 확인 및 디버깅을 위해서는 폰갭 프레임워크에서 제공하는 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 콘솔 창
{{:egovframework:hyb:guide:ios:contactsdebugxcode.png?700|}}\\
* Organizer 로그 창
{{:egovframework:hyb:guide:ios:contactsdebugorganizer.png?700|}}\\
^로그 메시지^값^비고^
|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 가이드 다운로드 : [[http://www.egovframe.go.kr/cop/bbs/selectBoardArticle.do?bbsId=BBSMSTR_000000000161&nttId=681&menu=3&submenu=7|Click]]
===== 참고 자료 =====
* UX/UI 라이브러리 : jQuery Mobile[[http://jquerymobile.com/demos/1.4.5/|Click]] \\
* Phonegap 4.3.0 : [[http://docs.phonegap.com/en/4.0.0/|Click]] \\