Overview

Allow your users to sync their contacts to your app. Or simplify form completion by enriching additional form fields based on a known lookup field such as email/phone number. Used in CRM and field service applications, for social networking and community platform apps, and for eCommerce shipping.

To implement functionality the Native Contacts plugin enables you to seamlessly retrieve all contacts from the device in bulk or to query contacts via lookup fields.

👍
Developer Demo
Display our demo page in your app to test during development https://median.dev/native-contacts/

Implementation Guide

Once the premium module has been added to your app, you may use the following Median JavaScript Bridge commands to access its functionality.

We have added Median JavaScript Bridge to allow retrieval of user contacts.

To use it, you will need to create a JavaScript function on your web page:

function contacts_callback(data) { 
    // process the data here. In this example, we are just logging it 
    alert(JSON.stringify(data)); 
}

↔️Median JavaScript Bridge

Then run this JavaScript function, passing in the name of your callback function:
// Callback method
median.contacts.getAll({'callback': contacts_callback});

// Promise method
median.contacts.getAll().then(function (data) {
// process the data here. In this example, we are just logging it 
   alert(JSON.stringify(data)); 
});

Learn more about using promises and the Median JavaScript Bridge.

The app will prompt the user for permission. If granted, it will call contacts_callback with this object as data:

{ 
    success: true, 
    contacts: [...] 
}

"contacts" will be an array of contact objects. Each object may have the following fields:

iOS:

birthday
namePrefix
givenName
middleName
familyName
previousFamilyName
nameSuffix
nickname
phoneticGivenName
phoneticMiddleName
phoneticFamilyName
organizationName
departmentName
jobTitle
note
phoneNumbers
emailAddresses
postalAddresses

Android:

birthday
givenName
familyName
companyName
companyTitle
note
phoneNumbers
emailAddresses
postalAddresses

phoneNumbers, emailAddresses, and postalAddresses are arrays of objects, described below. All other fields are strings.

Each phoneNumber is an object with fields:

label
phoneNumber

Each emailAddress is an object with fields:

label
emailAddress

Each postalAddress is an object with fields:

label
street
city
state - iOS only
region - Android only
postalCode
country
isoCountryCode - iOS only
subAdministrativeArea - iOS only
subLocality - iOS only

Checking Permissions

The app will automatically prompt users for permissions as necessary.

↔️Median JavaScript Bridge

To separately check if permission have been granted, add the following JavaScript code:
function callback(result){
     alert(JSON.stringify(result));
}

// Callback method
median.contacts.getPermissionStatus({'callback': callback}); // returns promise

// Promise method
median.contacts.getPermissionStatus().then(function (result) {
   alert(JSON.stringify(result)); 
});

The CALLBACK function will be run with an object like:
{"status": "granted"}

The possible statuses on iOS are:

granted – user has granted permission
denied – user has explicitly denied permission
restricted – access has been administratively prohibited
notDetermined – user has not yet been asked for permission

The possible statuses on Android are:

granted – user has granted permission
denied – user has not yet been asked, or has explicitly denied permission