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 within your web environment the Native Contacts plugin enables you to seamlessly retrieve all contacts from the device in bulk or to prompt the user to select specific contacts via a native UI.

👍

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.

Permission Management

The app will automatically prompt users for permissions as necessary after making a request for getting contacts. To separately check if permission have been granted use the below JavaScript Bridge method.

↔️Median JavaScript Bridge

JavaScript

// Provide a callback else returns a promise
median.contacts.getPermissionStatus({'callback': callback});

// Return value
{
  "status": STRING
}

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

Get all contacts stored on device

↔️Median JavaScript Bridge

JavaScript

// Pass a callback function else returns a promise
median.contacts.getAll({'callback': contacts_callback});

Prompt user to select contacts via native UI screen

↔️Median JavaScript Bridge

JavaScript

// Pass a callback function else returns a promise
median.contacts.pickContact({
  'callback': contacts_callback, 
  'multiple': BOOL // true to allow selection of multiple contacts, false to select only one
});

Learn more about using promises and the Median JavaScript Bridge.

Contacts return value

The app will prompt the user for permission automatically (see above). If granted, it will call the callback function or a return promise function with an object as follows:

{ 
  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

*note is available when using the pickContact() method. To access note when using the getAll() method a special permission for the com.apple.developer.contacts.notes entitlement is required from Apple.

Android:

• birthday
• givenName
• familyName
• companyName
• companyTitle
• note
• phoneNumbers
• emailAddresses
• postalAddresses

Formats:

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