Native Contacts

The Native Contacts plugin allows users to sync their contacts with your application, enabling form completion and data enrichment based on lookup fields such as email or phone number. This functionality is widely used in CRM systems, field service applications, social networking platforms, and eCommerce shipping solutions.

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

Prerequisites

Ensure the premium module is integrated into your application before using the following Median JavaScript Bridge commands.

Permission Management

The application will automatically request permissions when attempting to access contacts. To check if permission has already been granted, use the following JavaScript Bridge method:

↔️Median JavaScript Bridge

JavaScript

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

// Return value
{
  "status": STRING
}

Permission Status Values

Given the differences between both iOS and Android you can expect slightly different permission values based on the operating system.

iOS

• 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

Android

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

Retrieving Contacts

Get All Contacts Stored on Device

To retrieve all contacts stored on the 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

To allow users to select specific contacts using a 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
});

For more information about using promises with the Median JavaScript Bridge, refer to Median JavaScript Bridge Documentation.

Contacts Return Value

If the user grants permission, the callback function (or the returned promise) will receive an object structured 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

Data Formats

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

Phone Numbers

{
  "label": "STRING",
  "phoneNumber": "STRING"
}

Email Addresses

{
  "label": "STRING",
  "emailAddress": "STRING"
}

Postal Addresses

{
  "label": "STRING",
  "street": "STRING",
  "city": "STRING",
  "state": "STRING", // iOS only
  "region": "STRING", // Android only
  "postalCode": "STRING",
  "country": "STRING",
  "isoCountryCode": "STRING", // iOS only
  "subAdministrativeArea": "STRING", // iOS only
  "subLocality": "STRING" // iOS only
}