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:
navigator.getDataStores('contacts').then(function(stores) {
if (!stores.length)
return;
var store = stores[0];
// Create a contact.
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]
});
// Add new contact to the store.
store.insert(contact).then(function(id) {
console.log('Contact ' +
contact.name.givenNames[0] + ' ' +
contact.name.familyNames[0] + ' saved with id: ' +
id);
}, function(error) {
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 DataStore interface and the DataStoreKey type identifier are defined in [[!DATASTORE]].
This API must be only exposed to trusted content
The contacts data stores can be retrieved using the getDataStores() function on Navigator, as defined
in the Data Store API [[DATASTORE]], using "contacts" as label. This function returns an array of DataStore
objects asynchronously that can be used to get, update or insert Contact objects.
navigator.getDataStores('contacts').then(function(stores) {
if (!stores.length)
return;
var store = stores[0];
// ...
});
Which one is the system's default contacts datastore? the first one? Has a specific name?
The values stored in contacts data stores are of type Contact.
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 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 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.