Contact Picker API

1. Introduction

Contact pickers are frequently seen in native mobile applications for a variety of use cases, and in various desktop applications such as e-mail clients and calendars.

This specification defines an API to bring contact pickers to the web. 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 also 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. Use cases

• Bootstrapping a user’s social graph for social networks.

• Selecting the recipients of a message within an e-mail application.

1.2. Example

selectRecipientsButton.addEventListener('click', async () => {
  const contacts = await navigator.contacts.select({
      properties: ['name', 'email'],
      multiple: true,
  });

  if (!contacts.length) {
    // Either no contacts were selected in the picker, or the picker could
    // not be launched. Exposure of the API implies expected availability.
    return;
  }

  // Use the names and e-mail addresses in |contacts| to populate the
  // recipients field in the website’s UI.
  populateRecipients(contacts);
});

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. API Description

3.1. Extensions to Navigator

[Exposed=(Window,SecureContext)]
partial interface Navigator {
    readonly attribute ContactsManager contacts;
};

3.2. ContactsManager

dictionary ContactInfo {
    sequence<USVString> name;
    sequence<USVString> email;
    sequence<USVString> tel;
};

enum ContactProperty { "email", "name", "tel" };

dictionary ContactsSelectOptions {
    required sequence<ContactProperty> properties;
    boolean multiple = false;
};

[Exposed=(Window,SecureContext)]
interface ContactsManager {
    Promise<sequence<ContactInfo>> select(ContactsSelectOptions options);
};