Labs/Contacts/ContentAPI

The Contacts add-on adds a database of contact data to the browser, and allows web pages to request data from this database to use in web content.

Exposed Functions

In a Firefox web browser which has installed the Contacts addon, the following new method becomes available to web content:

window.navigator.people.find( filter, fields, successCallback, failureCallback)

The arguments are interpreted as follows:

• filter is an object that expresses a set of substring matches that must be met by contacts to be included in the result set. The attributes of the object are the fields that will be searched, and the values are the substrings that must be found.

For example, a filter of { emails: "@mozilla.com" } will include only contacts whose emails list contains at least one object that contains the substring "@mozilla.com".

• fields is an array of strings that express which fields of the contact will be made available to the web page. The strings should be drawn from the set of known properties described in "Contact Schema", below. The user will be asked to confirm each of the fields, and may choose to deny access to some fields, in which case the web page will receive a subset of what was requested.

For example, a fields argument could be ["displayName", "emails", "phoneNumbers"].

Also note the special field argument "idHash", which returns to MD5 hash of all the email addresses of the contact. (TODO: automatically salt the hash with the hostname?)

• successCallback is a function that will be called when the contact result set is found. It takes a single argument, which is an array of objects.

For example, the success callback could be

function(people) { 
 for (var i=0;i<people.length;i++) {
  processPerson(people[i]);
 }
}

• failureCallback is a function that will be called if the lookup fails. It takes a single argument, which is an explanatory string.

For example, the failure callback could be

function(error) {
 $("errorMsg").innerHTML = "Unable to load contacts: " + error;
}

Contact Schema

The schema for Contacts is Portable Contacts version 1.0.

Importers will coerce data into this format when necessary. The most relevant fields for web pages that are consuming this data are:

• displayName
• name (with subproperties givenName and familyName)
• emails (list; objects have type and value)
• phoneNumbers (list; objects have type and value)
• addresses (list; objects have streetAddress, locality, city, country, postalCode)
• accounts (list; objects have domain, userid, username)
• photos (list; objects have type and value; "thumbnail" and "profile" are canonical types)

Deltas from W3C Contacts API

The W3C Device APIs and Policy Working Group is working to standardize a Contacts API for web-enabled devices; you can read the latest draft here.

The Firefox implementation is lagging behind that API a bit; notable differences include:

• W3C service point is navigator.service.contacts.find
• W3C API puts fields first, and makes filter a subproperty of the options (fourth) argument
• W3C API includes a multiple/single selector, and implies that the success callback will receive a single contact in the single case.
• W3C API includes "save", "remove", and "clone" operations.
• W3C API includes a number of more complex search operations (and weighting rules) than what is currently supported in the add-on.
• W3C API includes error codes rather than strings for error callbacks
• W3C API includes an "updatedSince" option to find

Experimental "Services" API

In version 0.4 and later of the Contacts add-on, experimental service support is included.

The services API adds a "services" property to the Contact object, which has one or more functions attached to it that allow interaction with a contact's social web services.

The implementation of these services is variable, depending on the web service involved, but the names and APIs of the service methods are designed to allow for a degree of interoperability and automatic discovery of a person's "social API".

At present, the services API includes the following methods:

• updates(callback) invokes the callback repeatedly, passing an array of objects representing recent updates. The properties of the update object are:
  • text: always present; a short text message
  • source: always present; the name of the service that provided the update
  • sourceLink: always present; a link to the page of the service that provided the update
  • link: optional; a link to more detail for the update

• pictureCollectionsBy(callback) invokes the callback repeatedly, passing an array of objects representing photo collections managed by the user. The properties of each photoCollection are:
  • name: always present; a name for the collection
  • created_time: optional; the time the collection was created, in a form that new Date() can parse.
  • location: optional; a location for the collection
  • primaryPhotoThumbnailURL: optional; a URL to an image that is a thumbnail for the collection
  • primaryPhotoURL: optional; a URL for more detail about the primaryPhoto
  • getPhotos(callback): a function that, when invoked, returns an array of photo objects through the callback (see below)

• picturesOf(callback) invokes the callback, passing an array of objects representing photos of the contact. The objects are photos, see below.

• The getPhotos (of a collection) and picturesOf methods produce a list of pictures The fields of each picture are:
  • name: optional; a filename or label for the picture
  • homeURL: the URL of a page containing more detail about a picture
  • location: optional; the location of the picture
  • photoThumbnailURL: a URL to an image that is a thumbnail of this image

• sendPrivateMessageTo(message, callback) submits the given message to a service of the contact that will deliver the message privately. (Note that the message may be subject to significant restrictions; we need to provide a better API to understand character limits, two-way permissions, etc.)