Contact Picker API

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);
});

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. 
});

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});
  }
});

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. Physical address

A physical address consists of:

4.2. User contact

A user contact consists of:

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.3. Contacts source

The contacts source is a service that provides the user’s contact information to the user agent.

A contacts source consists of:

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;
};

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. ContactAddress

[Exposed=Window]
interface ContactAddress {
  [Default] object toJSON();
  readonly attribute DOMString city;
  readonly attribute DOMString country;
  readonly attribute DOMString dependentLocality;
  readonly attribute DOMString organization;
  readonly attribute DOMString phone;
  readonly attribute DOMString postalCode;
  readonly attribute DOMString recipient;
  readonly attribute DOMString region;
  readonly attribute DOMString sortingCode;
  readonly attribute FrozenArray<DOMString> addressLine;
};

The ContactAddress interface represents a physical address.

5.4. ContactsManager

dictionary ContactInfo {
    sequence<ContactAddress> address;
    sequence<DOMString> email;
    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 = {});
};