If you find any issue with this specification, please file a bug on Github.
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.
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]].
This API must be only exposed to trusted content
The ContactsManager interface exposes the contacts management functionality.
options parameter.
It returns a Promise that will allow the caller to
be notified about the result of the operation.
find
operation.
Promise that will allow the caller to
be notified about the result of the operation.
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 object that is requested to be saved in
the address book.
Promise that will allow the caller to
be notified about the result of the operation.
Contact object that is
requested to be removed from the address book.
The find method when invoked MUST run the
following steps:
Promise object
and resolver its associated resolver.
options parameter.
Contact objects providing the results of the
find operation.
value argument.
The clear method when invoked MUST run the
following steps:
Promise object
and resolver its associated resolver.
The save method when invoked MUST run the
following steps:
Promise object
and resolver its associated resolver.
Contact object passed as parameter.
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.
value argument.
The remove method when invoked MUST run the
following steps:
Promise object
and resolver its associated resolver.
Contact object identified by the
contactId passed as parameter from the address book.
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 The following are the event handlers (and their corresponding
event handler event types) that MUST be supported as attributes
by the ContactsManager object:
contactschange that implements the
ContactsChangeEvent interface at the
ContactsManager object
Event handlers
event handler
event handler event type
oncontactschangecontactschange
The event named contactschange MUST implement the
ContactsChangeEvent interface.
The ContactFindOptions dictionary represents the criteria used
to select the contacts to be returned by a find operation.
There are 2 possible filter operations:
The returned contacts can be sorted in one of the following orders:
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)
The ContactField interface represents a user's attribute and the types associated to it.
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.
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.
ContactGender enumThe ContactName interface represents a user's naming attributes.
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.
Date element representing the date when the contact
was last updated.
ContactField element or set thereof containing the
contact's email address(es). It maps to vCard's EMAIL attribute.ContactField element or set thereof containing the
user's urls (e.g. personal blog). It maps to vCard's URL attribute.ContactAddress element or set thereof containing the
user's physical address(es). It maps to vCard's ADR attributeContactTelField element or set thereof containing the
user's telephone numbers. It maps to vCard's TEL attributeDate element representing the contact's birth date.
It maps to vCard's BDAY attribute
ContactField element or set thereof containing the
user's instant messaging address(es). It maps to vCard's IMPP
attributeDate element representing the contact's anniversary.
It maps to vCard's ANNIVERSARY attributeThe Contact interface's contructor when invoked MUST run the following steps:
Contact object.
id attribute of contact to the
generated contact identifier.
lastUpdated attribute of contact to
the Date at which the constructor was invoked.
contactInitDict dictionary, if
present.
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
Contact object(s)
that have been added.Contact object(s)
that have been modified.Contact object(s)
that have been removed.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.