This specification defines a System Level API which offers a simple interface to manage user's contacts stored in the system's address book. A typical use case of the Contacts API is the implementation of an application to manage said address book.
This document defines a System Level API to manage the user's contacts that are stored in the system's address book. Future versions of this specification are expected to align the contact data model with the Contacts API being defined by the Device APIs Working Group.

If you find any issue with this specification, please file a bug on Github.

Introduction

The Contacts API allows to manage (create, edit, remove, etc) user's contacts stored in the system's address book, and thus provides the functionality needed to implement an application to manage said address book.

An example of use is provided below:


            var contactName = new ContactName({
              givenNames: ['John'],
              familyNames: ['Doe']
              });
            var mobilePhone = new ContactTelField({ types: ['home'], preferred: true, value: '+34698765432' });
            var contact = new Contact({
              name: contactName,
              phoneNumbers: [mobilePhone]
              });
            navigator.contacts.save(contact).then(
               function(contact) { window.console.log('Contact  ' +
                      contact.name.givenNames[0] + ' ' +
                      contact.name.familyNames[0] + ' saved!'); },
               function(error) {   window.console.error('Error: ' + error); } )

      

This specification defines conformance criteria that apply to a single product: the user agent that implements the interfaces that it contains.

Implementations that use ECMAScript to implement the APIs defined in this specification MUST implement them in a manner consistent with the ECMAScript Bindings defined in the Web IDL specification [[!WEBIDL]], as this specification uses that specification and terminology.

Terminology

The EventHandler interface represents a callback used for event handlers as defined in [[!HTML5]].

The concepts queue a task and fire a simple event are defined in [[!HTML5]].

The terms event handler and event handler event types are defined in [[!HTML5]].

The Promise interface, the concepts of a resolver, a resolver's fulfill algorithm and a resolver's reject algorithm are defined in [[DOM4]].

Security and privacy considerations

This API must be only exposed to trusted content

Navigator Interface

readonly attribute ContactsManager contacts
The object that exposes the contacts management functionality.

ContactsManager Interface

The ContactsManager interface exposes the contacts management functionality.

Promise find ()
This method allows to search contacts within the address book that match the criteria indicated in the options parameter. It returns a Promise that will allow the caller to be notified about the result of the operation.
optional ContactFindOptions options
Set of criteria that a contact needs to match to be included in the outcomes of the find operation.
Promise clear ()
This method allows to remove all contacts in the address book. It returns a Promise that will allow the caller to be notified about the result of the operation.
Promise save ()
This method allows to save a contact in the address book, e.g. an existing contact after having been edited. So if a contact with the same identifier, i.e. id, already exists in the address book, it will be updated. It returns a Promise that will allow the caller to be notified about the result of the operation.
Contact contact
The Contact object that is requested to be saved in the address book.
Promise remove ()
This method allows to remove a contact from the address book. It returns a Promise that will allow the caller to be notified about the result of the operation.
DOMString contactId
The identifier of the Contact object that is requested to be removed from the address book.
attribute EventHandler oncontactschange
May be used to set an event handler to be called when contacts are added, deleted or changed in some way.

The find method when invoked MUST run the following steps:

  1. Let promise be a new Promise object and resolver its associated resolver.
  2. Return promise and continue the following steps asynchronously.
  3. Make a request to the system to retrieve the contacts in the address book matching the criteria indicated in the options parameter.
  4. If there is an error invoke resolver's reject algorithm with no argument and terminate these steps.
  5. When the request has been completed:
    1. Let contacts be a new array of Contact objects providing the results of the find operation.
    2. Invoke resolver's fulfill algorithm with contacts as the value argument.

The clear method when invoked MUST run the following steps:

  1. Let promise be a new Promise object and resolver its associated resolver.
  2. Return promise and continue the following steps asynchronously.
  3. Make a request to the system to clear all the contacts in the address book.
  4. If there is an error invoke resolver's reject algorithm with no argument and terminate these steps.
  5. When the request has been completed invoke resolver's fulfill algorithm with no argument and terminate these steps.

The save method when invoked MUST run the following steps:

  1. Let promise be a new Promise object and resolver its associated resolver.
  2. Return promise and continue the following steps asynchronously.
  3. Make a request to the system to save in the address book the Contact object passed as parameter.
  4. If there is an error invoke resolver's reject algorithm with no argument and terminate these steps.
  5. When the request has been completed:
    1. Let contact be the Contact object as returned by the system, and which therefore has its id and lastUpdated parameters set, whereas they could be null in the original Contact object passed as parameter, for instance if it is a brand new Contact object not yet stored in the address book.
    2. Invoke resolver's fulfill algorithm with contact as the value argument.

The remove method when invoked MUST run the following steps:

  1. Let promise be a new Promise object and resolver its associated resolver.
  2. Return promise and continue the following steps asynchronously.
  3. Make a request to the system to remove the Contact object identified by the contactId passed as parameter from the address book.
  4. If there is an error invoke resolver's reject algorithm with no argument and terminate these steps.
  5. When the request has been completed invoke resolver's fulfill algorithm with no argument and terminate these steps.

Upon a change in a contact or set thereof is performed (i.e. contact(s) added / modified / removed) the system MUST fire a simple event named contactschange that implements the ContactsChangeEvent interface at the ContactsManager object

Event handlers

The following are the event handlers (and their corresponding event handler event types) that MUST be supported as attributes by the ContactsManager object:

event handler event handler event type
oncontactschange contactschange

The event named contactschange MUST implement the ContactsChangeEvent interface.

ContactFindOptions Dictionary

The ContactFindOptions dictionary represents the criteria used to select the contacts to be returned by a find operation.

DOMString value
Represents the value used for the filtering (e.g. "Tom").
FilterOperator operator
Represents the filtering operator used for the filtering.
sequence<DOMString> fields
Represents the set of fields in which the search is performed (e.g. "givenName").
sequence<DOMString> sortBy
Represents the fields by which the results of the search are sorted (e.g. ["givenNames", "familyNames"]). The results are sorted by the first field, then by the following one, if present, and so on.
SortOrder sortOrder
Represents the order in which the results of the search are sorted.
unsigned long resultsLimit
Represents the maximum number of results that can be returned by the search operation.

Enumerations

There are 2 possible filter operations:

contains
With this operation, a contact will be returned if its filtered field contains the given value.
is
With this operation, a contact will be returned if its filtered field matches exactly the given value.

The returned contacts can be sorted in one of the following orders:

ascending
The contacts will be sorted in ascending order.
descending
The contacts will be sorted in descending order.

It is for further study whether the level of flexibility of the filters needs to be increased and/or additional mechanisms need to be put in place so that applications can keep a local copy of the address book and perform the filtering locally (e.g. startTrackingChanges() and getNewChanges() methods)

ContactField Interface

The ContactField interface represents a user's attribute and the types associated to it.

attribute DOMString[] types
Indicates the types of this contact field (e.g. "home", "work").
attribute boolean preferred
Indicates whether this is the preferred contact field.
attribute DOMString value
A string that contains the user's address.

ContactFieldInit Dictionary

sequence<DOMString> types
boolean preferred
DOMString value

ContactTelField Interface

The ContactTelField interface represents a telephone number as well as metadata associated to it, namely the types (e.g. "voice", "text") and the carrier providing service to the telephony subscription associated to that number.

attribute DOMString? carrier
Indicates the carrier providing service to the telephony subscription associated to that number

ContactTelFieldInit Dictionary

DOMString carrier

ContactAddress Interface

The ContactAddress interface represents a user's physical address and the types associated to it. This interface is based on vCard 4.0 ADR attribute.

attribute DOMString[] types
Indicates the types of this contact field (e.g. "home", "work").
attribute boolean preferred
Indicates whether this is the preferred contact field.
attribute DOMString streetAddress
A string that contains the name of the street. It maps to the third component in vCard's ADR attribute.
attribute DOMString locality
A string that contains the name of the locality. It maps to the forth component in vCard's ADR attribute.
attribute DOMString region
A string that contains the name of the region. It maps to the fifth component in vCard's ADR attribute.
attribute DOMString postalCode
A string that contains the postal code. It maps to the sixth component in vCard's ADR attribute.
attribute DOMString countryName
A string that contains the name of the country. It maps to the seventh component in vCard's ADR attribute.

ContactAddressInit Dictionary

sequence<DOMString> types
boolean preferred
DOMString streetAddress
DOMString locality
DOMString region
DOMString postalCode
DOMString countryName

The ContactGender enum

male
contact is a male.
female
contact is a female.
other
contact has another gender.
none
contact does not have a gender (not applicable).
unknown
contact's gender is unknown.

ContactName Interface

The ContactName interface represents a user's naming attributes.

attribute DOMString displayName
A string representing the contact's display name. It maps to vCard's FN attribute.
attribute DOMString[] honorificPrefixes
A string or set thereof representing the contact's honorific prefix(es). It maps to the forth component in vCard's N attribute.
attribute DOMString[] givenNames
A string or set thereof representing the contact's given name(s). It maps to the second component in vCard's N attribute.
attribute DOMString[] additionalNames
A string or set thereof representing any additional name of the contact. It maps to the third component in vCard's N attribute.
attribute DOMString[] familyNames
A string or set thereof representing the contact's family name(s). It maps to the first component in vCard's N attribute.
attribute DOMString[] honorificSuffixes
A string or set thereof representing the contact's honorific suffix(es). It maps to the fifth component in vCard's N attribute.
attribute DOMString[] nicknames
A string or set thereof representing the contact's nick name(s). It maps to vCard's NICKNAME attribute.

ContactNameInit Dictionary

DOMString displayName
sequence<DOMString> honorificPrefixes
sequence<DOMString> givenNames
sequence<DOMString> additionalNames
sequence<DOMString> familyNames
sequence<DOMString> honorificSuffixes
sequence<DOMString> nicknames

Contact Interface

The Contact interface represents a contact stored in the address book. As a principle the attributes are based on vCard 4.0 and reuse the literal used in that standard. Any naming deviation is mentioned in the description of the corresponding attribute. Whereas this correspondence facilitates the import/export from/to vCard format it should be noted that a vCard import/export API is out of scope of this specification as parsing and serializing can be efficiently done in JavaScript, and libraries are readily available.

readonly attribute DOMString? id
Represents a unique identifier of the contact in the address book.
readonly attribute Date? lastUpdated
A Date element representing the date when the contact was last updated.
attribute ContactName name
An object representing the different naming attributes of the contact.
attribute ContactField[] emails
A ContactField element or set thereof containing the contact's email address(es). It maps to vCard's EMAIL attribute.
attribute DOMString[] photos
A string or set thereof representing the URI of the photo(s) of the contact. It maps to vCard's PHOTO attribute.
attribute ContactField[] urls
A ContactField element or set thereof containing the user's urls (e.g. personal blog). It maps to vCard's URL attribute.
attribute DOMString[] categories
A string or set thereof representing the category or categories associated to the contact (e.g. "family"). It maps to vCard's CATEGORIES attribute.
attribute ContactAddress[] addresses
A ContactAddress element or set thereof containing the user's physical address(es). It maps to vCard's ADR attribute
attribute ContactTelField[] phoneNumbers
A ContactTelField element or set thereof containing the user's telephone numbers. It maps to vCard's TEL attribute
attribute DOMString[] organizations
A string or set thereof representing the organization(s) the contact belongs to. It maps to vCard's ORG attribute
attribute DOMString[] jobTitles
A string or set thereof representing the contact's job title(s). It maps to vCard's TITLE attribute
attribute Date? birthday
A Date element representing the contact's birth date. It maps to vCard's BDAY attribute
attribute DOMString[] notes
A string or set thereof specifying supplemental information or a comment that is associated with the contact. It maps to vCard's NOTE attribute
attribute ContactField[] impp
A ContactField element or set thereof containing the user's instant messaging address(es). It maps to vCard's IMPP attribute
attribute Date? anniversary
A Date element representing the contact's anniversary. It maps to vCard's ANNIVERSARY attribute
attribute ContactGender gender
A string representing the contact's gender. It maps to the first component of vCard's GENDER attribute.

Steps

The Contact interface's contructor when invoked MUST run the following steps:

  1. Let contact be a new Contact object.
  2. Make a request to the system to generate a new unique contact identifier.
  3. Set the id attribute of contact to the generated contact identifier.
  4. Set the lastUpdated attribute of contact to the Date at which the constructor was invoked.
  5. Set the other attributes of contact to the value of the corresponding element in the contactInitDict dictionary, if present.

ContactInit Dictionary

ContactName name
sequence<ContactField> emails
sequence<DOMString> photos
sequence<ContactField> urls
sequence<DOMString> categories
sequence<ContactAddress> addresses
sequence<ContactTelField> phoneNumbers
sequence<DOMString> organizations
sequence<DOMString> jobTitles
Date birthday
sequence<DOMString> notes
sequence<ContactField> impp
Date anniversary
ContactGender gender

ContactsChangeEvent Interface

The ContactsChangeEvent interface represents events related to the set of contacts that have been simultaneously added, removed and/or modified. Changes that are applied to the address book in batches cause a ContactsChangeEvent with multiple contact references to be fired, whereas changes applied sequentially cause a ContactsChangeEvent with a single contact reference to be fired

readonly attribute DOMString[] added
Indicates the identifier(s) of the Contact object(s) that have been added.
readonly attribute DOMString[] modified
Indicates the identifier(s) of the Contact object(s) that have been modified.
readonly attribute DOMString[] removed
Indicates the identifier(s) of the Contact object(s) that have been removed.

ContactsChangeEventInit Dictionary

sequence<DOMString> added
sequence<DOMString> modified
sequence<DOMString> removed

Acknowledgements

The editors would like to express their gratitude to the Mozilla B2G Team for their technical guidance, implementation work and support, and specially to Tantek Çelik and Gregor Wagner, the original authors of B2G Contact API.