Contacts API

Non-standard
This feature is not on a current W3C standards track, but it is supported on the Firefox OS platform. Although implementations may change in the future and it is not supported widely across browsers, it is suitable for use in code dedicated to Firefox OS apps.

This API is available on Firefox OS for privileged or certified applications only.

Summary

The Contacts API provides a simple interface to manage a user's contacts stored in the system's address book. A typical use case for the Contacts API is the implementation of an application to manage an address book.

Note: Because personal information regarding a user's contact are pieces of sensitive data, only privileged and certified apps are allowed to directly access that API. Other applications are encouraged to use Web Activities to delegate operations on contacts.

Managing contacts

Contacts stored in the system's address book are accessible through the navigator.mozContacts property, which is itself an instance of the ContactManager interface.

Adding a contact

Creating a new entry in the system's address book is done in two steps:

  1. Instantiate a new mozContact object and fill in all necessary properties. The mozContact interface defines all possible properties for a given contact. Those properties are mostly the same as the ones defined in the vCard 4.0 specification, with the following exceptions:
    • The vCard N attribute is split into five properties: familyName, givenName, additionalName, honorificPrefix, honorificSuffix
    • The vCard FN attribute has been renamed name
    • The vCard GENDER attribute is split into two properties: sex, genderIdentity
    • Be careful: most properties are arrays. Firefox v1.3 is much more strict in ensuring this and therefore some working code in Firefox v1.2 can stop working in Firefox v1.3 because of this.
  2. Use the ContactManager.save() method with the contact object as its first parameter. The method returns a DOMRequest to keep track of the save operation's success or error.
// first way: setting the properties directly
var person = new mozContact();
person.givenName  = ["John"];
person.familyName = ["Doe"];
person.nickname   = ["No kidding"];
// second way: using a value object
var contactData = {
  givenName: ["John"],
  familyName: ["Doe"],
  nickname: ["No kidding"]
};
var person = new mozContact(contactData); // Firefox OS 1.3 takes a parameter to initialize the object
if ("init" in person) {
  // Firefox OS 1.2 and below uses a "init" method to initialize the object
  person.init(contactData);
}
// save the new contact
var saving = navigator.mozContacts.save(person);
saving.onsuccess = function() {
  console.log('new contact saved');
  // This update the person as it is stored
  // It includes its internal unique ID
  // Note that saving.result is null here
};
saving.onerror = function(err) {
  console.error(err);
};

Finding a contact

There are two methods to retrieve a contact from the system's address book:

Both methods expect a parameter which is an object that defines the filter and sort options. ContactManager.getAll only accepts the sort options. Those options are:

  • sortBy: A string representing the field by which the results of the search are sorted. Currently only givenName and familyName are supported.
  • sortOrder: A string indicating the result's sort order. Possible values are descending or ascending.

And the filter options:

  • filterBy: An array of strings representing all the fields to filter by.
  • filterValue: The value to match against.
  • filterOp: The filter comparison operator to use. Possible values are equals, startsWith, and match, the latter being specific to telephone numbers.
  • filterLimit: The number of contacts to retrieve for the find method.

find returns a DOMRequest object and getAll returns a DOMCursor object to access the success or error of a search.

If the search is successful, the result of the search is available in the DOMRequest.result property as either an Array of mozContact objects for find, or a single mozContact object for getAll. To receive the next result in the list with getAll, call the cursor's continue() method.

var options = {
  filterValue : "John",
  filterBy    : ["givenName","name","nickName"],
  filterOp    : "contains",
  filterLimit : 1,
  sortBy      : "familyName",
  sortOrder   : "ascending"
}
var search = navigator.mozContacts.find(options);
search.onsuccess = function() {
  if (search.result.length === 1) {
    var person = search.result[0];
    console.log("Found:" + person.givenName[0] + " " + person.familyName[0]);
  } else {
    console.log("Sorry, there is no such contact.")
  }
};
search.onerror = function() {
  console.warn("Uh! Something goes wrong, no result found!");
};
var allContacts = navigator.mozContacts.getAll({sortBy: "familyName", sortOrder: "descending"});
allContacts.onsuccess = function(event) {
  var cursor = event.target;
  if (cursor.result) {
    console.log("Found: " + cursor.result.givenName[0] + " " + cursor.result.familyName[0]);
    cursor.continue();
  } else {
    console.log("No more contacts");
  }
};
allContacts.onerror = function() {
  console.warn("Something went terribly wrong! :(");
};

Updating a contact

When retrieving a contact through find() or getAll() (or after a successful call to save() for a new contact), this contact has some metadata attached to it:

Updating the contact is just about changing its properties values, then saving it through a call to the save() method.

Note: Each time a contact is added, updated, or deleted a contactchange event is fired in order to keep track of any change on the system's address book. This event can be handled with the ContactManager.oncontactchange property.

Deleting a contact

A call to the ContactManager.remove() method will simply delete the mozContact object that was passed in.

In some edge cases, it's also possible to get rid of all contacts. To do this, use ContactManager.clear(). Be careful when calling that method; there is no way back.

Specifications

Specification Status Comment
Contacts Manager API
The definition of 'Contacts Manager API' in that specification.
Working Draft  
vCard Format Specification IETF RFC RFC 6350

Browser compatibility

Feature Chrome Firefox (Gecko) Internet Explorer Opera Safari
basic support No support No support No support No support No support
Feature Android Chrome for Android Firefox Mobile (Gecko) Firefox OS IE Mobile Opera Mobile Safari Mobile
basic support No support No support 18.0 1.1 No support No support No support

See also

Document Tags and Contributors

 Last updated by: chrisdavidmills,