A contact picker for the web

What is the Contact Picker API?



Access to the user’s contacts on a mobile device has been a feature of iOS/Android apps since
(almost) the dawn of time. It’s one of the most common feature requests
I hear from web developers, and is often the key reason they build an iOS/Android
app.

Available in Chrome 80 on Android, the Contact Picker API is an
on-demand API that allows users to select entries from their contact list and
share limited details of the selected entries with a website. It allows users to
share only what they want, when they want, and makes it easier for users to
reach and connect with their friends and family.

For example, a web-based email client could use the Contact Picker API to
select the recipient(s) of an email. A voice-over-IP app could look up
which phone number to call. Or a social network could help a user discover
which friends have already joined.

Caution:
The Chrome team has put a lot of thought into the design and implementation
of the Contact Picker API to ensure that the browser will only share exactly
what people choose. See the Security and Privacy
section below.

Current status

Step Status
1. Create explainer Complete
2. Create initial draft of specification Complete
3. Gather feedback & iterate on design Complete
4. Origin trial Complete
5. Launch Chrome 80
Available on Android only.

Using the Contact Picker API

The Contact Picker API requires a method call with an options parameter that
specifies the types of contact information you want. A second method tells you
what information the underlying system will provide.

Check out the Contact Picker API demo
and view the
source.

Feature detection

To check if the Contact Picker API is supported, use:

const supported = ('contacts' in navigator && 'ContactsManager' in window);

In addition, on Android, the Contact Picker requires Android M or later.

Opening the Contact Picker

The entry point to the Contact Picker API is navigator.contacts.select().
When called, it returns a promise and shows the contact picker, allowing the
user to select the contact(s) they want to share with the site. After
selecting what to share and clicking Done, the promise resolves with an
array of contacts selected by the user.

When calling select() you must provide an array of properties you’d like
returned as the first parameter (with the allowed values being any of
'name', 'email', 'tel', 'address', or 'icon'),
and optionally whether multiple contacts can be
selected as a second parameter.

const props = ['name', 'email', 'tel', 'address', 'icon'];
const opts = {multiple: true};

try {
const contacts = await navigator.contacts.select(props, opts);
handleResults(contacts);
} catch (ex) {
// Handle any errors here.
}

Caution:
Support for 'address' and 'icon' requires Chrome 84 or later.

The Contacts Picker API can only be called from a secure,
top-level browsing context, and like other powerful APIs, it requires a
user gesture.

Detecting available properties

To detect which properties are available, call navigator.contacts.getProperties().
It returns a promise that resolves with an array of strings indicating which
properties are available. For example: ['name', 'email', 'tel', 'address'].
You can pass these values to select().

Remember, properties are not always available, and new properties may be
added. In the future, other platforms and contact sources may restrict
which properties are be shared.

Handling the results

The Contact Picker API returns an array of contacts, and each contact includes
an array of the requested properties. If a contact doesn’t have data for the
requested property, or the user chooses to opt-out of sharing a particular
property, the API returns an empty array. (I describe how the user chooses properties
in the User control section.)

For example, if a site requests name, email, and tel, and a user
selects a single contact that has data in the name field, provides two
phone numbers, but does not have an email address, the response returned will be:

[{
"email": [],
"name": ["Queen O'Hearts"],
"tel": ["+1-206-555-1000", "+1-206-555-1111"]
}]

Caution:
Labels and other semantic information on contact fields are dropped.

Security and permissions

The Chrome team designed and implemented the Contact Picker API using the core
principles defined in
Controlling Access to Powerful Web Platform Features,
including user control, transparency, and ergonomics. I’ll explain each.

User control

Access to the users’ contacts is via the picker, and it can only be called with
a user gesture, on a secure, top-level browsing context.
This ensures that a site can’t show the picker on page load, or randomly show
the picker without any context.

Screen shot, users can choose which properties to share.
Users can choose not to share some properties. In this screenshot, the
user has unchecked the ‘Phone numbers’ button. Even though the site
asked for phone numbers, they will not be shared with the site.

There’s no option to bulk-select all contacts so that users are encouraged
to select only the contacts that they need to share for that particular
website. Users can also control which properties are shared with the site
by toggling the property button at the top of the picker.

Transparency

To clarify which contact details are being shared, the picker always
shows the contact’s name and icon, plus any properties that the site has
requested. For example, if a site requests name, email, and tel,
all three properties will be shown in the picker. Alternatively,
if a site only requests tel, the picker will show only the name, and
telephone numbers.

Screen shot of picker for site requesting all properties.
Picker, site requesting name, email, and
tel, one contact selected.
Screen shot of picker for site requesting only phone numbers.
Picker, site requesting only tel, one contact selected.
Screen shot of picker when a contact is long-pressed.
The result of a long press on a contact.

A long press on a contact will show all of the information that will be
shared if the contact is selected. (See the Cheshire Cat contact image.)

No permission persistence

Access to contacts is on-demand, and not persisted. Each time a site wants
access, it must call navigator.contacts.select() with a user gesture,
and the user must individually choose the contact(s) they want to share
with the site.

Feedback

The Chrome team wants to hear about your experiences with the Contact Picker
API.

Problem with the implementation?

Did you find a bug with Chrome’s implementation? Or is the implementation
different from the spec?

  • File a bug at https://new.crbug.com. Be sure to include as much
    detail as you can, provide simple instructions for reproducing the bug, and
    set Components to Blink>Contacts. Glitch works great
    for sharing quick and easy problem reproductions.

Planning to use the API?

Are you planning to use the Contact Picker API? Your public support helps the
Chrome team to prioritize features, and shows other browser vendors how
critical it is to support them.

Helpful links

Thanks

Big shout out and thanks to Finnur Thorarinsson and Rayan Kanso who are
implementing the feature and Peter Beverloo whose
code I shamelessly
stole and refactored for the demo.

PS: The names in my contact picker are characters from Alice in Wonderland.

What is the Contact Picker API?




Access to the user’s contacts on a mobile device has been a feature of iOS/Android apps since
(almost) the dawn of time. It’s one of the most common feature requests
I hear from web developers, and is often the key reason they build an iOS/Android
app.

Available in Chrome 80 on Android, the Contact Picker API is an
on-demand API that allows users to select entries from their contact list and
share limited details of the selected entries with a website. It allows users to
share only what they want, when they want, and makes it easier for users to
reach and connect with their friends and family.

For example, a web-based email client could use the Contact Picker API to
select the recipient(s) of an email. A voice-over-IP app could look up
which phone number to call. Or a social network could help a user discover
which friends have already joined.

Caution:
The Chrome team has put a lot of thought into the design and implementation
of the Contact Picker API to ensure that the browser will only share exactly
what people choose. See the Security and Privacy
section below.

Current status

Step Status
1. Create explainer Complete
2. Create initial draft of specification Complete
3. Gather feedback & iterate on design Complete
4. Origin trial Complete
5. Launch Chrome 80
Available on Android only.

Using the Contact Picker API

The Contact Picker API requires a method call with an options parameter that
specifies the types of contact information you want. A second method tells you
what information the underlying system will provide.

Check out the Contact Picker API demo
and view the
source.

Feature detection

To check if the Contact Picker API is supported, use:

const supported = ('contacts' in navigator && 'ContactsManager' in window);

In addition, on Android, the Contact Picker requires Android M or later.

Opening the Contact Picker

The entry point to the Contact Picker API is navigator.contacts.select().
When called, it returns a promise and shows the contact picker, allowing the
user to select the contact(s) they want to share with the site. After
selecting what to share and clicking Done, the promise resolves with an
array of contacts selected by the user.

When calling select() you must provide an array of properties you’d like
returned as the first parameter (with the allowed values being any of
'name', 'email', 'tel', 'address', or 'icon'),
and optionally whether multiple contacts can be
selected as a second parameter.

const props = ['name', 'email', 'tel', 'address', 'icon'];
const opts = {multiple: true};

try {
const contacts = await navigator.contacts.select(props, opts);
handleResults(contacts);
} catch (ex) {
// Handle any errors here.
}

Caution:
Support for 'address' and 'icon' requires Chrome 84 or later.

The Contacts Picker API can only be called from a secure,
top-level browsing context, and like other powerful APIs, it requires a
user gesture.

Detecting available properties

To detect which properties are available, call navigator.contacts.getProperties().
It returns a promise that resolves with an array of strings indicating which
properties are available. For example: ['name', 'email', 'tel', 'address'].
You can pass these values to select().

Remember, properties are not always available, and new properties may be
added. In the future, other platforms and contact sources may restrict
which properties are be shared.

Handling the results

The Contact Picker API returns an array of contacts, and each contact includes
an array of the requested properties. If a contact doesn’t have data for the
requested property, or the user chooses to opt-out of sharing a particular
property, the API returns an empty array. (I describe how the user chooses properties
in the User control section.)

For example, if a site requests name, email, and tel, and a user
selects a single contact that has data in the name field, provides two
phone numbers, but does not have an email address, the response returned will be:

[{
"email": [],
"name": ["Queen O'Hearts"],
"tel": ["+1-206-555-1000", "+1-206-555-1111"]
}]

Caution:
Labels and other semantic information on contact fields are dropped.

Security and permissions

The Chrome team designed and implemented the Contact Picker API using the core
principles defined in
Controlling Access to Powerful Web Platform Features,
including user control, transparency, and ergonomics. I’ll explain each.

User control

Access to the users’ contacts is via the picker, and it can only be called with
a user gesture, on a secure, top-level browsing context.
This ensures that a site can’t show the picker on page load, or randomly show
the picker without any context.

Screen shot, users can choose which properties to share.
Users can choose not to share some properties. In this screenshot, the
user has unchecked the ‘Phone numbers’ button. Even though the site
asked for phone numbers, they will not be shared with the site.

There’s no option to bulk-select all contacts so that users are encouraged
to select only the contacts that they need to share for that particular
website. Users can also control which properties are shared with the site
by toggling the property button at the top of the picker.

Transparency

To clarify which contact details are being shared, the picker always
shows the contact’s name and icon, plus any properties that the site has
requested. For example, if a site requests name, email, and tel,
all three properties will be shown in the picker. Alternatively,
if a site only requests tel, the picker will show only the name, and
telephone numbers.

Screen shot of picker for site requesting all properties.
Picker, site requesting name, email, and
tel, one contact selected.
Screen shot of picker for site requesting only phone numbers.
Picker, site requesting only tel, one contact selected.
Screen shot of picker when a contact is long-pressed.
The result of a long press on a contact.

A long press on a contact will show all of the information that will be
shared if the contact is selected. (See the Cheshire Cat contact image.)

No permission persistence

Access to contacts is on-demand, and not persisted. Each time a site wants
access, it must call navigator.contacts.select() with a user gesture,
and the user must individually choose the contact(s) they want to share
with the site.

Feedback

The Chrome team wants to hear about your experiences with the Contact Picker
API.

Problem with the implementation?

Did you find a bug with Chrome’s implementation? Or is the implementation
different from the spec?

  • File a bug at https://new.crbug.com. Be sure to include as much
    detail as you can, provide simple instructions for reproducing the bug, and
    set Components to Blink>Contacts. Glitch works great
    for sharing quick and easy problem reproductions.

Planning to use the API?

Are you planning to use the Contact Picker API? Your public support helps the
Chrome team to prioritize features, and shows other browser vendors how
critical it is to support them.

Helpful links

Thanks

Big shout out and thanks to Finnur Thorarinsson and Rayan Kanso who are
implementing the feature and Peter Beverloo whose
code I shamelessly
stole and refactored for the demo.

PS: The names in my contact picker are characters from Alice in Wonderland.


Print Share Comment Cite Upload Translate
APA
Pete LePage | Sciencx (2024-03-29T09:54:24+00:00) » A contact picker for the web. Retrieved from https://www.scien.cx/2019/08/07/a-contact-picker-for-the-web/.
MLA
" » A contact picker for the web." Pete LePage | Sciencx - Wednesday August 7, 2019, https://www.scien.cx/2019/08/07/a-contact-picker-for-the-web/
HARVARD
Pete LePage | Sciencx Wednesday August 7, 2019 » A contact picker for the web., viewed 2024-03-29T09:54:24+00:00,<https://www.scien.cx/2019/08/07/a-contact-picker-for-the-web/>
VANCOUVER
Pete LePage | Sciencx - » A contact picker for the web. [Internet]. [Accessed 2024-03-29T09:54:24+00:00]. Available from: https://www.scien.cx/2019/08/07/a-contact-picker-for-the-web/
CHICAGO
" » A contact picker for the web." Pete LePage | Sciencx - Accessed 2024-03-29T09:54:24+00:00. https://www.scien.cx/2019/08/07/a-contact-picker-for-the-web/
IEEE
" » A contact picker for the web." Pete LePage | Sciencx [Online]. Available: https://www.scien.cx/2019/08/07/a-contact-picker-for-the-web/. [Accessed: 2024-03-29T09:54:24+00:00]
rf:citation
» A contact picker for the web | Pete LePage | Sciencx | https://www.scien.cx/2019/08/07/a-contact-picker-for-the-web/ | 2024-03-29T09:54:24+00:00
https://github.com/addpipe/simple-recorderjs-demo