Native Contacts
Access and manage user contacts from their mobile devices
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
// 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 permissiondenied
– user has explicitly denied permissionrestricted
– access has been administratively prohibitednotDetermined
– user has not yet been asked for permission
Android
granted
– user has granted permissiondenied
– 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
// 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
// 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
}
Updated 13 days ago