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:

JavaScript

// 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:

JavaScript

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