1. Introduction
Contact pickers are frequently seen in various desktop and native mobile applications for a variety of use cases. This specification defines an API to bring contact pickers to the web, which will enable new use cases for web apps, such as:
-
Bootstrapping a user’s social graph for social networks.
-
Selecting the recipients of a message within an e-mail application.
The contact picker model was chosen to give full control to users over the shared data, allowing users to choose exactly which contacts to provide to the website. The contact picker model gives websites one-off access to a user’s contacts, meaning developers have to request access to the user’s contacts every time they need it. This differs from some native contact APIs, but is necessary for ensuring users' contacts are not accessed without their knowledge and explicit consent.
1.1. Examples
selectRecipientsButton. addEventListener( 'click' , async() => { const contacts= await navigator. contacts. select([ 'name' , 'email' ], { multiple: true }); if ( ! contacts. length) { // No contacts were selected in the picker. return ; } // Use the names and e-mail addresses in |contacts| to populate the // recipients field in the website’s UI. populateRecipients( contacts); });
In the above example selectRecipientsButton
is a HTMLButtonElement
, and populateRecipients
is a developer-defined function.
selectRecipientButton. addEventListener( 'click' , async() => { // We are unsure if addresses are supported, or can be provided by the browser. if (( await navigator. contacts. getProperties()). includes( 'address' )) { const contacts= await navigator. contacts. select([ 'address' ]); if ( ! contacts. length) { // No contacts were selected in the picker. return ; } // length is 1 since we didn’t request multiple contacts. sendGiftToAddress( contacts[ 0 ]. address); } // Fallback to a form. });
In the above example selectRecipientButton
is a HTMLButtonElement
, and sendGiftToAddress
is a developer-defined function.
selectRecipientButton. addEventListener( 'click' , async() => { // We are unsure if icons are supported, or can be provided by the browser. if (( await navigator. contacts. getProperties()). includes( 'icon' )) { const contacts= await navigator. contacts. select([ 'name' , 'icon' ]); if ( ! contacts. length) { // No contacts were selected in the picker. return ; } if ( ! contacts[ 0 ]. name. length|| ! contacts[ 0 ]. icon. length) { // Info not found. Use fallback. return ; } // We only need one name and one image. const name= contacts[ 0 ]. name[ 0 ]; const imgBlob= contacts[ 0 ]. icon[ 0 ]; // Display image. const url= URL. createObjectURL( imgBlob); imgContainer. onload= () => URL. revokeObjectURL( url); imgContainer. src= url; // Alternatively use a Bitmap. const imgBitmap= await createImageBitmap( imgBlob); // Upload icon. const response= await fetch( '/contacticon' , { method: 'POST' , body: imgBlob}); } });
In the above example selectRecipientButton
is a HTMLButtonElement
, and imgContainer
is a HTMLImageElement
.
2. Privacy Considerations
Exposing contact information has a clear privacy impact, in terms of exposing PII of uninvolved parties. A picker model is enforced so that the user agent can offer a user experience that makes it clear what information is going to be shared with the website and when.
The following constraints are also enforced:
-
The API is only available in a top-level browsing context which must also be a secure context. These restrictions help ensure that the provided contact information reaches its intended recipient.
-
A user gesture is needed to initiate the API, to disallow programmatic requests to the user’s contacts.
3. Realms
All platform objects are created in the context object's relevant Realm unless otherwise specified.
4. Infrastructure
The contact picker task source is a task source.
4.1. User contact
A user contact consists of:
-
names, a list of
DOMString
s, each item representing a unique name corresponding to the user. -
emails, a list of
DOMString
s, each item representing a unique valid e-mail address of the user. -
numbers, a list of
DOMString
s, each item representing a unique phone number of the user. -
addresses, a list of
ContactAddress
es, each item representing a unique physical address of the user. -
icons, a list of
Blob
s, each item representing a unique image of the user.NOTE: An icon
Blob
'stype
is an image mime type.
A user contact contains data relating to a single user.
Note: The lists can be of different sizes, and entries with the same index don’t need to correspond to each other.
4.2. Contacts source
The contacts source is a service that provides the user’s contact information to the user agent.
A contacts source consists of:
-
available contacts, a list of user contacts.
-
supported properties, a list of available
ContactProperty
values.
Note: It is up to the user agent to choose the contacts source.
5. API Description
5.1. Extensions to Navigator
[Exposed =Window ]partial interface Navigator { [SecureContext ,SameObject ]readonly attribute ContactsManager contacts ; };
Navigator
has a contacts manager (a ContactsManager
), initially a new ContactsManager
.
The contacts
attribute’s getter must return the context object's contacts manager.
The browsing context has a contact picker is showing flag, initially unset.
5.2. ContactProperty
enum {
ContactProperty ,
"address" ,
"email" ,
"icon" ,
"name" };
"tel"
A ContactProperty
is considered to be available if its associated user contact field can be accessed by the user agent.
- "address"
-
Associated with user contact's addresses.
- "email"
-
Associated with user contact's emails.
- "icon"
-
Associated with user contact's icons.
- "name"
-
Associated with user contact's names.
- "tel"
-
Associated with user contact's numbers.
5.3. ContactsManager
interface :
ContactAddress PaymentAddress {};dictionary {
ContactInfo sequence <ContactAddress >;
address sequence <DOMString >;
sequence <Blob >;
icon sequence <DOMString >;
name sequence <DOMString >; };
tel dictionary {
ContactsSelectOptions boolean =
multiple false ; }; [Exposed =(Window ,SecureContext )]interface {
ContactsManager Promise <sequence <ContactProperty >>getProperties ();Promise <sequence <ContactInfo >>select (sequence <ContactProperty >,
properties optional ContactsSelectOptions ); };
options
5.3.1. getProperties()
getProperties()
method, when invoked, runs these steps:
-
Let promise be a new promise.
-
Run the following steps in parallel:
-
Resolve promise with contacts source's supported properties.
-
-
Return promise.
5.3.2. select()
select(properties, options)
method, when invoked, runs these steps:
-
Let relevantBrowsingContext be the context object's relevant settings object's responsible browsing context.
-
If relevantBrowsingContext is not a top-level browsing context, then return a promise rejected with an
InvalidStateError
DOMException
. -
If the algorithm is not triggered by user activation then return a promise rejected with a
SecurityError
DOMException
. -
If relevantBrowsingContext’s contact picker is showing flag is set then return a promise rejected with an
InvalidStateError
DOMException
. -
If properties is empty, then return a promise rejected with a
TypeError
. -
For each property of properties:
-
If contacts source's supported properties does not contain property, then return a promise rejected with a
TypeError
.
-
-
Set relevantBrowsingContext’s contact picker is showing flag.
-
Let promise be a new promise.
-
Run the following steps in parallel:
-
Let selectedContacts be be the result of launching a contact picker with options’
multiple
member and properties. If this fails, then:-
Return a promise rejected with an
InvalidStateError
DOMException
. -
Unset relevantBrowsingContext’s contact picker is showing flag.
-
Abort these steps.
-
-
Unset relevantBrowsingContext’s contact picker is showing flag.
-
Queue a contact picker task to run these steps:
-
Let contacts be an empty list.
-
For each selectedContact in selectedContacts:
-
Let contact be a new
ContactInfo
with:address
-
selectedContact’s addresses if properties contains "
address
", otherwise undefined. email
-
selectedContact’s emails if properties contains "
email
", otherwise undefined. icon
-
selectedContact’s icons if properties contains "
icon
", otherwise undefined. name
-
selectedContact’s names if properties contains "
name
", otherwise undefined. tel
-
selectedContact’s numbers if properties contains "
tel
", otherwise undefined.
-
Append contact to contacts.
-
-
Resolve promise with contacts.
-
-
-
Return promise.
6. Contact Picker
DOMString
s), the user agent MUST present a user
interface that follows these rules:
-
If presenting a user interface fails or accessing the contacts source's available contacts fails, then return failure.
-
The UI MUST prominently display the browsing context's origin.
-
The UI MUST make it clear which
properties
of the contacts are requested.NOTE: This information is derived from properties.
-
The UI SHOULD provide a way for users to opt out of sharing certain contact information.
NOTE: If the user opts out, the appropriate user contact fields should be modified before returning the selected contacts. It should be indistinguishable whether the returned user contacts have opted-out information or the information was not present to begin with.
-
The UI MUST make it clear which information will be shared.
-
The UI MUST provide a way to select individual contacts. If allowMultiple is false, only one contact should be pickable.
-
The UI MUST provide an option to cancel/return without sharing any contacts, in which case remove the UI and return an empty list.
-
The UI MUST provide an a way for users to indicate that they are done selecting, in which case remove the UI and return a list of the selected contacts as user contacts.