• 디바이스의 연락처 데이터베이스에 접속하는 기능을 제공한다.

• Contacts API의 플랫폼별 제약사항은 다음과 같다.

• categories : 지원하지 않음. 항상 null 값을 리턴한다. (Android 2.x )

• pref : 지원하지 않음. 항상 false 값을 리턴한다. (Android 2.x )

• pref : 지원하지 않음. 항상 false 값을 리턴한다.

• formatted: 부분적으로 지원함.
• honorificPrefix, givenName, middleName, familyName and honorificSuffix 순으로 리턴 하지만, 저장되지 않는다.

• pref: 지원하지 않음. 항상 false 값을 리턴한다. (Android 2.x)

• displayName : 지원하지 않음. 항상 null 값을 리턴한다. ContactName 객체가 있을 경우에는 name 이나 nickname, “” 을 갖는다.
• birthday : 자바스크립트의 Date 객체를 사용해야 한다..
• photos : 호출한 사진은 단말기의 임시폴더에 저장되며, File URL을 리턴한다. 임시 폴더는 앱이 종료될 때 삭제된다.
• categories : 지원하지 않음. 항상 null 값을 리턴한다.

• pref : 지원하지 않음. 항상 false 값을 리턴한다.
• formatted : 현재 지원하지 않음.

• pref : 지원하지 않음. 항상 false 값을 리턴한다.

• formatted: 부분적으로 지원함. Composite Name을 리턴 하지만, 저장되지 않는다.

• pref: 지원하지 않음. 항상 false 값을 리턴한다.
• type: 지원하지 않음. 항상 null 값을 리턴한다.
• name: 부분적으로 지원함. Organization에 대입한 배열중, 첫 번째 ContactOrganization만 유효하다.
• department: 부분적으로 지원함. Organization에 대입한 배열중, 첫 번째 ContactOrganization만 유효하다.
• title: 부분적으로 지원함. Organization에 대입한 배열중, 첫 번째 ContactOrganization만 유효하다.

• 개인정보에 대한 민감성 및 안정성 문제로 더이상 업데이트 하지 않음 ( https://cordova.apache.org/news/2017/11/27/Deprecation-of-cordova-contacts-plugin.html )
• W3C 연락처 API 표준안 ( https://www.w3.org/TR/contacts-api/ )

• app/res/xml/config.xml

<plugin name="Contacts" value="org.apache.cordova.ContactManager" />

• app/AndroidManifest

<uses-permission android:name="android.permission.GET_ACCOUNTS" />
<uses-permission android:name="android.permission.READ_CONTACTS" />
<uses-permission android:name="android.permission.WRITE_CONTACTS" />

• App/Supporting Files/config.xml

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

• 새로운 Contact 객체를 생성한다.
• 생성과 동시에 디바이스에 저장되지 않는다. (Contact.save 를 통해 저장할 수 있다.)

var contact = navigator.contacts.create(properties);

• Quick Example

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

• 디바이스 내, 연락처 데이터베이스를 검색하여, 각각의 연락처 정보를 갖는 하나 이상의 Contact 객체를 받는다.

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

• contacts.find 함수 파라미터로 사용된다.
• Contact 객체의 필드로 검색 결과로 나타나는 내용들을 정의하는데 사용된다.

["name", "phoneNumbers", "emails"]

• contacts.find 함수 실행 성공 후에 수행되며 Contact 배열을 결과 값으로 가진다.
• 검색 조건으로 조회된 Contact 객체 배열

function(contacts) {
    // Do something
}

• contact 관련 함수 실행에 실패하였을 때 수행된다.

function(code) {
    // Do something
}

• contacts.find 함수의 선택적 옵션이다.
• 연락처 데이터베이스 검색 후에 나타나는 결과들의 내용을 정의한다.

{ 
    filter: "",
    multiple: true,
};

• 사용자의 개인 혹은 사무 용도의 연락처 정보를 가지는 객체이다.

function onSuccess(contact) {
    alert("Save Success");
};

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

// create a new contact object
var contact = navigator.contacts.create();
contact.displayName = "Plumber";
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);

* Contact 객체의 name 속성에 해당하는 관련 속성들의 객체.

• Contact 객체의 phone numbers, email address, urls 속성에서 사용하는 필드 객체.

• Contact 객체의 주소 속성에 대한 객체.

function onSuccess(contacts) {
    for (var i=0; i<contacts.length; i++) {
        for (var j=0; j<contacts[i].addresses.length; j++) {
            alert("Pref: " + contacts[i].addresses[j].pref + "\n" +
                    "Type: " + contacts[i].addresses[j].type + "\n" +
                    "Formatted: " + contacts[i].addresses[j].formatted + "\n" + 
                    "Street Address: "  + contacts[i].addresses[j].streetAddress + "\n" + 
                    "Locality: "  + contacts[i].addresses[j].locality + "\n" + 
                    "Region: "  + contacts[i].addresses[j].region + "\n" + 
                    "Postal Code: "  + contacts[i].addresses[j].postalCode + "\n" + 
                    "Country: "  + contacts[i].addresses[j].country);
        }
    }
};

function onError(contactError) {
    alert('onError!');
};

// find all contacts
var options = new ContactFindOptions();
options.filter=""; 
var filter = ["displayName","addresses"];
navigator.contacts.find(filter, onSuccess, onError, options);

• Contact 객체의 organization 속성에 관련된 객체.

function onSuccess(contacts) {
    for (var i=0; i<contacts.length; i++) {
        for (var j=0; j<contacts[i].organizations.length; j++) {
            alert("Pref: " + contacts[i].organizations[j].pref + "\n" +
                    "Type: " + contacts[i].organizations[j].type + "\n" +
                    "Name: " + contacts[i].organizations[j].name + "\n" + 
                    "Department: "  + contacts[i].organizations[j].department + "\n" + 
                    "Title: "  + contacts[i].organizations[j].title);
        }
    }
};

function onError(contactError) {
    alert('onError!');
};

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

• contacts.find 함수에서 사용되는 검색 조건을 정의하는 객체.

// success callback
function onSuccess(contacts) {
    for (var i=0; i<contacts.length; i++) {
        alert(contacts[i].displayName);
    }
};

// error callback
function onError(contactError) {
    alert('onError!');
};

// specify contact search criteria
var options = new ContactFindOptions();
options.filter="";          // empty search string returns all contacts
options.multiple=true;      // return multiple results
filter = ["displayName"];   // return contact.displayName field

// find contacts
navigator.contacts.find(filter, onSuccess, onError, options);

• 에러가 발생했을 경우, contactError 함수 호출 시, 전달받는 객체.

• Cordova : https://cordova.apache.org/docs/en/7.x/reference/cordova-plugin-contacts/index.html