WebAPI/ContactsAPI

Contacts API specification

ContactsAPI is also known as WebContacts (or Contacts+).

Goals

Provide read/write DOM API access to the device address book, and the contacts contained therein with a simple minimal API that has a high-degree of interoperability with both device address books and commonly published web contact information (vCard/hCard). - Tantek

Related:

• The W3C DAP work is similar but problematic. See the W3C DAP section below for how the ContactsAPI fixes key problems with the DAP approach.
• A more "appy" ContactsAPI that allows apps to both access and be providers for contacts. For this see work on WebActions, WebActivities, and Labs/Contacts/ContentAPI.

Status

See bug 674720.

Proposed API

There is an object in window.navigator named mozContacts with the following interface:

 interface ContactsManager
 {
   void    find(in ContactFindOptions options,
                in ContactFindSuccessCallback successCB,
                in ContactErrorCallback errorCB);
   Contact create(in ContactProperties properties);
   void    clear(in ContactSuccessCallback successCB,
                 in ContactErrorCallback errorCB);
 };

 interface ContactFindOptions : nsISupports
 {
   attribute DOMString   filterValue;    // e.g. "Tom"
   attribute DOMString   filterOp;       // e.g. "contains"
   attribute DOMString[] filterBy;       // e.g. "givenName"
 };

 interface ContactFindSuccessCallback
 {
   void handleEvent([array, size_is(count)] in Contact contacts, in unsigned long count);
 };

TO DO: Research/document device-specific address book capabilities and represent using methods on the ContactsManager interface.

The following Contact interface is based vCard4/hCard properties, flattened for the simple/typical case of one address (adr) based on the microformats 2.0 hCard iteration.

 interface ContactAddress {
            attribute DOMString              streetAddress;
            attribute DOMString              locality;
            attribute DOMString              region;
            attribute DOMString              postalCode;
            attribute DOMString              countryName;
            attribute double                 latitude;
            attribute double                 longitude;
            attribute double                 altitude;
 };

 interface ContactProperties {
            attribute DOMString[]            name;
            attribute DOMString[]            honorificPrefix;
            attribute DOMString[]            givenName;
            attribute DOMString[]            additionalName;
            attribute DOMString[]            familyName;
            attribute DOMString[]            honorificSuffix;
            attribute DOMString[]            nickname;
            attribute DOMString[]            email;
            attribute DOMString[]            photo;
            attribute DOMString[]            url;
            attribute DOMString[]            category;
            attribute ContactAddress[]       adr;
            attribute DOMString[]            tel;
            attribute DOMString[]            org;
            attribute Date                   bday;
            attribute DOMString[]            note;
            attribute DOMString[]            impp; /* per RFC 4770, included in vCard4 */
            attribute Date                   anniversary; /* new in vCard4 */
            attribute DOMString              sex; /* new in vCard4, gender sub-component 1 */
            attribute DOMstring              gender-identity'; /* new in vCard4, gender sub-comp 2 */
 };

 interface ContactWriter : ContactProperties
 {
   void    save(in ContactSuccessCallback successCb,
                in ContactErrorCallback errorCb);
   void    remove(in ContactSuccessCallback successCb,
                  in ContactErrorCallback errorCb);
   Contact clone();
 };

 interface Contact : ContactWriter
 {
   readonly attribute DOMString id;
   readonly attribute Date      published;
   readonly attribute Date      updated;
 };

Note: despite hCard2 including a flat set of adr properties into the top level h-card object for ease of publishing, this interface always abstracts those properties into a ContactAddress sub-object for simplicity (smaller/cleaner) of interface. The interface is able to represent published data.

Notes of properties left out from vCard4/hCard(2), why the above is a subset of vCard4/hCard(2). Some common reasons:

• NU - Not commonly used in practice, either in address books or in publishing on the web. Reconsider such properties if usage changes.
• ER - Error prone whenever entered/published. Such properties are toast. Not getting added.
• AB - Absent from typical device address books (if you've seen a specific device with such fields in the address book, please list it here as a nested list item, preferably with screenshot of the UI). Reconsider such properties if added to address book UIs, note such research/data accordingly in #Considered_changes section below.

Specific deliberately omitted property notes:

• 'logo' - NU, 'photo' is used instead
• 'post-office-box' - NU, AB
• 'extended-address' - ER. in practice such data typically ends up in a long 'street-address'.
• 'organization-name' and 'organization-unit' are rarely separately specified, users/publishers preferring to use the simple flat 'org' property instead.

Added for B2G db (but not in any known existing device address books):

• ContactAddress 'geo' property components 'latitude', 'longitude' and additional 'altitude' from GeoLocation API
• Contact 'gender' property components 'sex', 'gender-identity' (from vCard4/hCard2 in particular)

Example

 function errorCb(contactError)
 {
   alert("Error: " + contactError.code);
 };

 function findCb(contacts)
 {
   for (var i=0; i<contacts.length; i++) {
     alert("Contact found: " + contacts[0].givenName);
   }
 };

 function successCb()
 {
   alert("Success");
 };

 let newContact = navigator.mozContacts.create({givenName: "Tom"}); 
 newContact.save(function(){alert("Contact saved")}, errorCb); 
 navigator.mozContacts.find({}, findCb, errorCb); // return all Contacts  
 navigator.mozContacts.find({filterValue: "Tom", filterOp: "contains", filterBy: "givenName"}, findCb, errorCb); 
 let otherContact = newContact.clone(); 
 otherContact.givenName = "Tim"; 
 otherContact.save(successCb, errorCb); 
 navigator.mozContacts.find({}, findCb, errorCb);
 newContact.remove(successCb, errorCb);
 navigator.mozContacts.clear(successCb, errorCb);

Considered changes

• mozContacts object might move to window.navigator.device;
• more Contact attributes (from Address Book UIs of BlackBerry - BB, iPhone/iTouch - iOS)
  • ringtone (BB, iOS)
  • job-title (BB, iOS)
  • messagetone (BB)
  • phonetic-given-name (iOS)
  • phonetic-family-name (iOS)
  • formal-name (per suggestion from Jonas), like name, but with all "honorable so and so" etc. included as you would formally address or introduce someone. needs examples of publication on the web, and/or device address books that actually include such a field (haven't seen one yet).

W3C DAP Contacts

The DAP WG (W3C) has contacts specification [1] sharing some of the goals of this proposal.

[1] http://dev.w3.org/2009/dap/contacts/

For the moment, the Contacts API proposal differs from the DAP specification in some key ways:

• The ContactsAPI is a simplified / flattened properties/interfaces/API per lessons learned with the development of both vCard4 and hCard (including hCard 2)
• The ContactsAPI's read/write API is explicitly designed to avoid multi-access write corruption.

Both of the above are fairly significant fixes to major problems in the W3C DAP Contacts API.

There's also the W3C's wiki page on ContactsMozDapComparison but it is quite out of date. It would be good to update that page with the advantages / reasoning of this ContactsAPI.

FAQ

Why are givenName familyName arrays instead of optional

• could use clarification of why a number of fields are arrays instead of optional DOMString. e.g. givenName, familyName. Those seem like 0-or-1 cases, not lists.
  • In short, i18n. Experience with vCard3 and hCard with international content has shown that multiple different languages/cultures have multiple given names and family names, and thus the change was made in vCard4 to make these multivalued. - Tantek 10:37, 25 October 2011 (PDT)

Why are flattened adr properties arrays instead of optional

• could use clarification of why a number of fields are arrays instead of optional DOMString. e.g. fields of the flattened adr. Those seem like 0-or-1 cases, not lists.
  • In short, simplification and i18n. The multivalued adr properties are a result of both lack of use / common mis-use of post-office-box and extended-address properties (such data is more often/reliably shoved into multiple lines of street-address) and countries having multiple lines/values for street-address and/or locality/region. - Tantek 10:37, 25 October 2011 (PDT)

Is the name property a composition or something users enter

• Is the name property a composition of given and family name or is it something users can enter?
  • In short, name is 'fn' and can be entered. The 'name' property is the replacement for 'fn' from vCard/hCard (what the DAP folks call 'displayName' or similar). This is an explicit renaming (to 'name') that multiple parties have independently done, and thus is being adopted in hCard 2 and thus we are adopting as well in the ContactsAPI. The 'name' property is something users can enter, DAP calls it 'displayName" or something like that.

Articles

Articles mentioning / discussion the ContactsAPI:

• 2011-11-30 ExtremeTech: Mozilla’s WebAPI for Firefox takes shape ...
• 2011-10-28 ExtremeTech: Will Firefox stand in the way of the cloud?