Considerations and Limitations

Device Limitations

ContactsService doesn’t manage contact information itself. Instead, it makes available certain contact data of the underlying platform (Android or iOS) and hardware (phone or other mobile device). While the features provided by ContactsService are the same across both platforms, they’re subject to some platform-specific quirks and minor differences.

• The user interface for selecting contacts are subject to differences between platforms. For example, the Done button on iOS vs. a checkmark icon on Android, and differences in cancellation:
• ContactsService requires the use of the mobile device’s contacts. Your user must grant your app access to contacts. The exact user experience is governed by the platform. The request happens automatically on first use, and is managed by the device itself, but you should plan for it when designing the user experience of your app.

• In Android 11 or later, if the user taps “Deny” for permission to access the Contacts app more than once during the app’s lifetime of installation on a device, the user won’t see the system permissions dialog again. Tapping Deny multiple times implicitly chooses the “don’t ask again” option.

  In previous versions of Android, users would see the system permissions dialog each time the app requested permission unless the user had previously selected “don’t ask again”. This change in Android 11 discourages repeated requests for permissions that users have chosen to deny.

  If the user has denied permission to access the Contacts app and needs to change their permissions to allow access, they can do so in their device’s settings.

• If Mobile Device Management (MDM) is in use on a device, and MDM restricts access to contacts data, ContactsService can’t access it.
• If the user doesn't have any contacts in their device’s contact list, ContactsService won’t work.
• If the user has contacts associated with specific accounts on their device, those accounts must have contacts sync enabled in order for ContactsService to access them. In other words, ContactsService can only access contacts that are visible in your user’s device’s native contact list. See Use other contact accounts on iPhone (iOS) and Back up & sync device contacts (Android) for more information.

Development Considerations

Virtual devices might not have any contact data when they’re created. To test ContactsService on a virtual device, you’ll first need to create some contact records in the virtual device’s Contacts app. Alternatively, you can import contact data in the standard .vcf format, or sign into a real Google or iCloud account that has contact data associated with it. 

You can certainly develop the user experience for your component on a desktop or laptop development system. But be sure to test contact access functionality on the physical devices on which you plan to deploy your Lightning app.

ContactsService Considerations

Be aware of the following considerations when using ContactsService in your Lightning app.

• ContactsService is built on top of mobile operating system and device features. ContactsService’s capabilities therefore depend on Android or iOS features, which are subject to change beyond our control. When mobile operating system features change, the behavior of ContactsService can change without notice.
• A Lightning component that uses ContactsService can have a custom user interface in the component itself. However, the contacts selection user interface can’t be customized.