This page is targeted at Firefox OS/Gecko developers. If you're a Web developer who wants to know how to use the Contacts API, check the MDN page.

Basic Examples

Create contact example

var contact = new mozContact({name: ["John Doe"], givenName: ["John"], familyName: ["Doe"]});

var request = navigator.mozContacts.save(contact);

request.onsuccess = function() {
   alert("Success saving contact. New contact ID: " + contact.id);
};

request.onerror = function() {
   alert("Error saving contact.");
};

Update contact example

// "contact" is the same contact object as in the save example above. The contact must have its ID field set to update it.
// Note that when updating array fields (like telephones) all the phone numbers must be specified, not just the one you want to update.
contact.tel = [{type: ["home"], value: "8675309", carrier: "myCarrier", pref: 1}, {type: ["home", "custom type"], value: "1234567", pref: 0}];
var request = navigator.mozContacts.save(contact2);

request.onsuccess = function() {
   alert("Success updating contact.");
};

request.onerror = function() {
   alert("Error updating contact.");
};

Remove/delete contact example

// "contact" is the same contact as in the create and update examples. A contact object must have its ID property set in order to remove it.
var request = navigator.mozContacts.remove(contact);

request.onsuccess = function() {
    alert("Success removing contact.");
};

request.onerror = function() {
    alert("Error removing contact.");
};

Find contacts example

var options = {filterBy: ["givenName"],
               filterOp: "equals",
               filterValue: "John",
               sortBy: "familyName",
               sortOrder: "ascending"
};

var request = navigator.mozContacts.find(options);

request.onsuccess = function() {
    if(request.result.length > 0) {
        alert("Found " + request.result.length + " contacts");
        for (var i=0; i<request.result.length; i++) {
            for (var j=0; j<request.result[i].name.length; j++) {
               alert("Found contact with name: " + request.result[i].name[j]);
            }
        }
    } else {
        alert("No contacts found.");
    }
};

request.onerror = function() {
    alert("Error finding contacts.");
};

Get all contacts example

var cursor = navigator.mozContacts.getAll({});

cursor.onsuccess = function() {
    if (cursor.result) {
        alert("Got contact with name: " + cursor.result.name.join(" "));
        cursor.continue();
    } else {
        alert("Done!");
    }
};

cursor.onerror = function() {
    alert("Error getting contacts");
};

Get contacts count example

var request = navigator.mozContacts.getCount();

request.onsuccess = function() {
    alert("Number of contacts: " + request.result);
};

request.onerror = function() {
    alert("Error getting contacts count.");
};

cursor.onerror = function() {
    alert("Error getting all contacts.");
};

Clear (delete all) contacts examples

var request = navigator.mozContacts.clear();

request.onsuccess = function() {
    alert("Contacts cleared.");
};

request.onerror = function() {
    alert("Error clearing contacts.");
};

API

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

ContactManager

 [NoInterfaceObject]
 interface ContactManager : EventTarget {
   DOMRequest find(optional ContactFindOptions options);
   DOMCursor  getAll(optional ContactFindSortOptions options);
   DOMRequest clear();
   DOMRequest save(mozContact contact);
   DOMRequest remove(mozContact contact);
   DOMRequest getRevision();
   DOMRequest getCount();
   attribute  EventHandler oncontactchange;
 };

ContactFindSortOptions

 dictionary ContactFindSortOptions {
   DOMString sortBy;                    // "givenName" or "familyName"
   DOMString sortOrder = "ascending";   // e.g. "descending"
 };

ContactFindOptions

 dictionary ContactFindOptions : ContactFindSortOptions {
   DOMString      filterValue;  // e.g. "Tom"
   DOMString      filterOp;     // e.g. "startsWith"
   any            filterBy;     // e.g. ["givenName", "nickname"]
   unsigned long  filterLimit = 0;
 };

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

ContactField

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 ContactField {
   attribute DOMString[] type; // ["home"], ["work"], etc.
   attribute DOMString?  value;
   attribute boolean?    pref; // false = no pref, true = preferred (vCard3 TYPE:PREF; vCard4 PREF:1)
 };

ContactTelField

 interface ContactTelField : ContactField {
   attribute DOMString? carrier; // experimental extension - not in vCard!
 };

ContactAddress

 interface ContactAddress {
   attribute DOMString[] type; // ["home"], ["work"], etc.
   attribute DOMString?  streetAddress;
   attribute DOMString?  locality;
   attribute DOMString?  region;
   attribute DOMString?  postalCode;
   attribute DOMString?  countryName;
   attribute boolean?    pref; // false = no pref, true = preferred (vCard3 TYPE:PREF; vCard4 PREF:1)
 };

mozContact

 [Constructor(optional ContactProperties properties)]
 interface mozContact {
            attribute DOMString id;
   readonly attribute Date? published;
   readonly attribute Date? updated;
 
            attribute Date? bday;
            attribute Date? anniversary; /* new in vCard4 */
 
            attribute DOMString? sex; /* new in vCard4, gender sub-component 1 */
            attribute DOMString? genderIdentity; /* new in vCard4, gender sub-comp 2 */
 
            attribute Blob[] photo;
 
            attribute ContactAddress[] adr;
 
            attribute ContactField[] email;
            attribute ContactField[] url;
            attribute ContactField[] impp; /* per RFC 4770, included in vCard4 */
 
            attribute ContactTelField[] tel;
 
            attribute DOMString[] name;
            attribute DOMString[] honorificPrefix;
            attribute DOMString[] givenName;
            attribute DOMString[] phoneticGivenName; /* proposed vCard4 addition, bug 909224 */
            attribute DOMString[] additionalName;
            attribute DOMString[] familyName;
            attribute DOMString[] phoneticFamilyName; /* proposed vCard4 addition, bug 909224 */
            attribute DOMString[] honorificSuffix;
            attribute DOMString[] nickname;
            attribute DOMString[] category;
            attribute DOMString[] org;
            attribute DOMString[] jobTitle; /* 'title' from vCard made specific */
            attribute DOMString[] note;
            attribute DOMString[] key; /* takes a key URI per RFC6350 6.8.1 */
 };

ContactProperties

 dictionary ContactProperties {
   Date?                          bday;
   Date?                          anniversary;
 
   DOMString?                     sex;
   DOMString?                     genderIdentity;
 
   sequence<Blob>?                photo;
 
   sequence<ContactAddressInit>?  adr;
 
   sequence<ContactFieldInit>?    email;
   sequence<ContactFieldInit>?    url;
   sequence<ContactFieldInit>?    impp;
 
   sequence<ContactTelFieldInit>? tel;
 
   sequence<DOMString>?           name;
   sequence<DOMString>?           honorificPrefix;
   sequence<DOMString>?           givenName;
   sequence<DOMString>?           additionalName;
   sequence<DOMString>?           familyName;
   sequence<DOMString>?           honorificSuffix;
   sequence<DOMString>?           nickname;
   sequence<DOMString>?           category;
   sequence<DOMString>?           org;
   sequence<DOMString>?           jobTitle;
   sequence<DOMString>?           note;
   sequence<DOMString>?           key;
 };

The boolean 'pref' field has been added for compatibility with both vCard3 and vCard4 use of 'pref'.

• false = no preference, same as if unspecified in vCard3 or vCard4.
• true = preferred, same as TYPE:PREF in vCard3 and PREF:1 in vCard4

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 since typical device address books cluster address information accordingly, e.g. for a home or work address. The interface is able to represent published data.

Android considerations

The Firefox for Android implementation of the contacts has a few discrepancies from the specs listed here. They are as follows:

• The "name" field must always be consistent with the "honorificPrefix", "givenName", "familyName", and "honorificSuffix" fields. For example, a contact with the "name" field set to "Dr. John Doe Junior" should have "honorificPrefix" set to "Dr.", "givenName" set to "John", etc.

• The "getRevision()" function is not supported on Android. Calling it will always return an error.

• The "updated" and "published" timestamps are not supported on Android. They will never be set.

• The preferred field for a phone, email, address, etc., if not set to true, will default to false even if the field is omitted completely.

• The photo field is not yet supported.

Methodology for inclusion

The ContactsAPI includes properties as needed for the following:

What is the Gaia Contacts Requirements priority level?

1. Gaia Contacts App UI v1 milestone (must be present on linked wiki page).

2. Gaia Contacts App UI v2 milestone (must be present on linked wiki page).

Meeting one of those criteria is required for inclusion in the ContactsAPI. All other feature requests for the ContactsAPI will be prioritized, considered, and developed as follows:

3. Interoperable properties on other devices (multiple).

• If there is more than one implementation, are they interoperable?
• Demonstrate that a feature is in the UI of multiple devices by attaching screenshots, and
• Check this by importing the vCards from one device implementation on another device implementation (e.g. by emailing a contact from one device to another) and seeing if the same values are shown in the UI of both devices, both when each is the sender and receiver. Check that the value round-trips without loss of fidelity.

4. More vCard4 features.

• Is there an existing vCard feature for the requested feature?

5. Feature parity with other devices.

• Are there any existing shipping device implementations of the feature?
• If so, please create a few contacts with various settings for the feature, export the contacts (by email etc.) as vCards, and attach those so we can analyze the current implementation(s).
• One or more devices may support a contacts UI feature that does not exist or interoperate with other devices. Such features may be worthy of consideration if they're deemed essential from a competitive perspective.

6. New stuff. Wish lists (typically from individuals) for what they want in their own super address books.

These priority levels will be used to group/document all ContactsAPI requests. If you think a feature should be considered for a higher priority level, please provide the necessary research demonstrating that it deserves the higher priority level.

Considered changes

implementation details

• mozContacts object might move to window.navigator.device;
• favorite contacts may be implemented as category: "favorite"
• a favorite phone number (iOS feature) for a contact may be implemented as type:"favorite" on the phone number (add to the type array as necessary).

Priority 1 feature requests

Gaia Contacts App UI v1 feature requirements will gestate here and then migrate into the interface description above.

Priority 2 feature requests

Gaia Contacts App UI v2 feature requirements will gestate here and then migrate into the interface description above.

• more Contact attributes (from Address Book UIs of BlackBerry (BB), iPhone/iTouch (iOS), MacOS Address Book (MOAB).
  • ringtone (BB, iOS)
    • per contact? (likely), or per tel?
  • messagetone (BB) (i.e. SMS, email, IM)
    • per contact? (likely), or per tel?

Priority 3 feature requests

Features requested by one or more individuals which are interoperably implemented by current (multiple) implementations.

• source-url string[] - same as vCard SOURCE property. Renamed to make the data expected more clear.
• source-name string[] - same as vCard NAME property - note, has NOTHING to do with the name of the entry/person/company - this is simply optional display text for the source-url, and this renamed accordingly. Plus we already have a name property which is the name of the contact.
  • H2VX exports vCard SOURCE/NAME (tested with http://h2vx.com/vcf/https://webfwd.org/about/team/ and viewing the downloaded .vcf file in a text editor).
  • Apple Address Book does not display SOURCE/NAME but *does* round-trip import/export them with full fidelity (only one value per field tested, tested by importing forementioned H2VX download, exporting Pascal via ctrl-click in the UI, and viewing the exported .vcf file in a text editor)
  • requested by JOSE MANUEL CANTERA FONSECA 2012-06-18 in email to dev-webapi as "origin" - note: client application should set the source-url to the *specific* URL that a contact was retrieved from, e.g. their personal website with hCard, their Facebook profile URL, their Twitter profile URL etc., NOT a generic "Facebook.com" URL.

Priority 4 feature requests

Features requested by one or more individuals which are already present in the vCard4 spec, and likely implemented by by one or more implementations (but not interoperably).

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)

Some common problems:

• 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.

E.g. properties left out from vCard4/hCard(2), why the above is a subset of vCard4/hCard(2). 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.
• 'sort-string' / 'sort-as'. per suggestion from Jonas, the Japanese iPhone has a field for "phonetic last name" which can be used for sorting. The existing vCard3 sort-string property or vCard4 sort-as (sub)property could be used to capture this if the only intended use is sorting.
• 'related' - human relationships (MOAB)
  • husband - use 'spouse'
  • father - use 'parent'
  • brother - use 'sibling'
  • ex-wife - no existing value
  • daughter - use 'child'
  • manager - no existing value, there is mention on the XPN Examples research page on the microformats wiki
  • PhD supervisor - no existing value. similar to previous 'manager' request. may be too domain specific to be worth standardizing.
• vCard4 extensions

Priority 5 feature requests

Features requested by one or more individuals which exist in one or more other devices but are not interoperable (and thus worthy of proposing for addition to vCard if not already in vCard).

More Contact attributes (from Address Book UIs of BlackBerry (BB), iPhone/iTouch (iOS), MacOS Address Book (MOAB) :

• phonetic-given-name (iOS, MOAB) (2012-080 requested VCARDDAV, Bugzilla 909224 request for inclusion in ContactsAPI)
• phonetic-family-name (iOS, MOAB) (2012-080 requested VCARDDAV, Bugzilla 909224 request for inclusion in ContactsAPI)
• favorite contact (as a native feature rather than workaround with category:favorite)
  • implemented by Android AB

Priority 6 feature requests

Features requested by one or more individuals which are not in any existing device implementations. Wish list.

Contact properties:

• formal-name - 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). Outstanding questions:
  • what existing device address books have a field in the UI?
    • what do they export in vCards when such a field is used?
  • are there any examples of real world websites that publish this property?
• custom dates
  • Child's birthday - use a separate contact for the child with 'bday' instead and then this upgrades to level 4 - just needs the 'related' property.
  • First met (who?)
  • Divorced (who?)
• tagged fields - allow any contact field to be arbitrarily tagged with one or more tags by the user.
• t-shirt-size - as used in https://phonebook.mozilla.org
• food like/dislike/restriction/allergy (helpful when ordering or preparing food for a group)
  • all are useful when planning a dinner party
  • dislikes are things a person dislikes but isn't going to freak out if there's a little bit of
  • restrictions are things a person chooses to not eat, for any number of optional reasons, e.g. health, ecological/ethical, religious, tradition/custom
  • allergies are things a person should or MUST not eat because they cause distress, illness, and potentially death.

ContactField properties:

• category - suggestion from Jonas. The field would be an array of strings. That way we can add "favorite" to the category array to favorite a phone number, and we could add "operator:Telephonica" to indicate a particular operator.
  • ContactField already has a 'type' DOMString[], and 'PREF' is already used as *a* type value by other implementations (Android AB, iOS AB) to indicate "favorite" phone number of a contact.
• carrier per request from Telefonica. Recommendation: postpone til after v1. Outstanding questions:
  • What problem is it solving?
    • Rates in Brazil depend a lot on the carrier of the person you are communicating with.
  • Is this a "nice to have" stretch innovative feature or is it a competitive parity feature? In which case...
    • What existing device(s) address books have a field in the UI? As of now there no known devices / address books that support a "carrier" designation on "tel" values.
      • A quick search didn't turn up any prior art or devices. If anyone knows of ANY device or address book software that supports a "carrier" designation on a per phone number basis, please provide the specific name of the device and a URL to its description on the web (e.g. at a place where you can buy it). Better yet, if you have such a device, create a contact with phone number with "carrier" designated, export a .vcf from it and send that along for analysis.
      • When found, what do they export in vCards when such a field is used?
  • Can this information be automatically determined rather than user-entered?
    • This information is available in operator network infrastructure (HLR), there are also some services that offer this information publicly, and some applications are built in different countries to expose that information. In Spain, for instance an app in the Android Market for doing it. Unknown how to do this in Brazil.
  • Problem: adds additional burden to the user to investigate and fill out the carrier of phone numbers from friends. How exactly is the user supposed to be able to *know* what carrier the number is associated with in order to pick it?
    • E.g. in the US we have no idea if the cell phone numbers of friends are serviced by AT&T, Verizon, Sprint, T-Mobile, Virgin Mobile etc. and frankly, don't (and shouldn't) care, since the functionality is equivalent.
  • Possible workaround: one way to implement a "carrier" designation on telephone numbers would be to use custom machine-types on the phone number, that is, along with "home", "work", "pref" etc. standard types, we can use custom machine-types of the form: "label:value", e.g. "carrier:tmobile".
  • Current recommendation: strongly recommend we postpone "carrier" to after v1. If no one else in the market has this feature, then it shouldn't be a blocker for us to ship v1.

Out of scope

The following features have been determined to be out of scope for the ContactsAPI:

• arbitrary key/value storage with a contact.
  • issues: This might cause a lot of problems e.g.:
    • database upgrades: Our multi-process support for all types for our database is not 100% functional yet. We might run into all kind of problems when we have to upgrade databases.
    • exporting: How should we deal with exporting random data.
    • search: Should we allow to search random data?
  • work-around: If a web app wants to store arbitrary key/value data associated with a contact, the web app should simply use the UUID of the contact as an index into alternative storage (e.g. using WebStorage API) and attach any additional key/value data there to that index.

FAQ

How do we best converge contact data models

The ContactsAPI is based on the popular vCard/hCard standards.

For contact data models, the best way to converge is to base work on those two. We have been doing this across numerous contacts related formats/schema/API using vCard as the point of coordination, and the IETF VCARDDAV list for that.

Any exceptions must be noted explicitly with reasons.

One exception is the "carrier" field which has been marked experimental, and which should be proposed to VCARDDAV by someone who can justify it with real world use cases / examples, or dropped from the ContactsAPI.

Should the ContactsAPI data model change for DAP Contacts

In short, no, the ContactsAPI should not change for DAP Contacts.

Since the ContactsAPI's data model is already directly based on the core and more popular vCard/hCard standards, it should NOT be changed in response to other downstream specifications.

Instead, any other downstream specifications (whether DAP Contacts or others) should be encouraged to converge with the ContactsAPI, or at least with vCard/hCard directly.

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.
  • 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.
  • 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?
  • The name property is 'fn' and can be entered by users. The 'name' property is the replacement for 'fn' (formatted name) from vCard/hCard. This is an explicit renaming (to 'name') that multiple parties have independently done (decentralized convergent evolution, the one exception being DAP which called it 'displayName'), and thus is being adopted in hCard 2 and thus we are adopting as well in the ContactsAPI.

Why are abbreviations used for adr bday org tel

• Why are abbreviations used for the 'adr', 'bday', 'org', and 'tel' properties?
  • property names re-used literally from vCard/hCard. 'adr', 'bday', 'org', and 'tel' are re-used with the same semantics from vCard and hCard (which itself is a well-established part of the web platform). It is better to re-use literal names of existing properties rather than re-name them in a good intentioned (but ill-wrought) attempt to "fix" names (for differing opinions/values of "fix"). This is a general design principle borne out of experience with earlier attempts at re-use/re-naming which resulted in unnecessary vocabulary divergence. See preserve literal vocabulary when reusing meaning.

Why re-use property names from vCard and hCard

• Why re-use property names from vCard and hCard?
  • clarity, continuity, interoperability, avoiding divergence. Re-using names when re-using semantics from well established existing standards has the advantage of better consistency, clarity, understanding, continuity, interoperability, and perhaps most importantly, avoiding divergence, which is exactly what does happen (and has) when people re-name things, abbreviations or otherwise. See: avoid renaming when reusing and note the provided example of the failed/divergent efforts to rename the 'org' property in particular over the years.

What is impp

• What is impp?
  • impp is defined by RFC 4770 and incorporated into vCard4. The 'impp' property is for specifying URLs for instant messaging and presence protocol communications associated with a contact.

Does every API structure imply a UI structure requirement

• Does every API property, structure, array require similar structures in the UI?
  • No. There is no 1:1 API drives UI causality. For example: the vCard format exposes an array, and there are plenty of phones that import/export vCards and thus have some sort of implementation (including UI) that handles it in some way. Do all phones support all of vCard? No. But they are able to handle import/export of a format that supports whole arrays of types for example.

Which existing address books support multiple communication types

• Which existing (shipping) address book support multiple communication types, e.g. an array of 'type' strings for tel, email, etc.?
  • Both iOS and Android ABs support types (plural) for communication properties, as discerned by creating multiple phone numbers, and setting one of them to preferred, for each contact, and then exporting vCards, showing that the preferred phone number's type is exported as an array: "PREF,HOME" (i.e. for a preferred home number), or "WORK,FAX" (i.e. for a work fax number)
  • Thus at a minimum for data portability fidelity from other platforms, the ContactsAPI must support the multiple types exported(emailed,shared,etc.) by iOS and Android AB.
  • A new Address Book UI (e.g. Gaia) can choose to support some simplified UI (e.g. looking for PREF in particular, and then assuming just one other type).

Background:

• iOS dialer implements PREF in the UI as "favorite" (displayed as a star * to the far right of the phone number) and allows more than one number to be a "favorite". However only the first such number listed is exported as a vCard tel type:pref. The other numbers' "favoriteness" is lost upon export from iPhone (email contact etc.). iOS fails to respect this "pref" type upon vCard import - thus fails roundtrip (on its own or across devices).
• Android AB implements PREF as "default" (displayed as a checkmark to the right of the specific number) and allows only one number to be the "default". Android also exports this as vCard tel type:pref. Android also fails to respect this "pref" type upon vCard import - thus fails roundtrip (on its own or across devices).
• Originally "favorite" for telephone number suggestion from Jonas. Which phone number of several of a contact is a "favorite" that is caller prefers to use.

Summary:

• 'type:work,fax' in vCard exports is how implementations implement a multiple type contact address out of several - thus clearly requiring that ContactField have a notion of multiple types and
  • thus 'type' is DOMString[].
• 'type:pref' in vCard exports is how implementations implement a preferred contact address out of several of the same type - thus clearly requiring that ContactField have a notion of 'pref'.
  • thus interface ContactField now has boolean pref property accordingly.

Implementation

• B2G: See bug 674720.
• Android: See bug 857730.

Issues

permissions and privacy

See: WebAPI/Security/Contacts

iOS Apps had a major embarrassment with the disclosure that apps like Path were automatically uploading your address book to their servers. More here:

http://kottke.org/12/02/more-on-iphone-address-book-privacy

We need a permissions/privacy model for ContactsAPI that is better and reflects user expectations. For now we're going with a whitelist for implementation purposes.

This is an open issue and needs some UI/UX flows figured out from which we will add to the API accordingly.

W3C DAP Contacts

The DAP WG (W3C) has a contacts API working draft [1] sharing some of the goals of this proposal.

[1] http://www.w3.org/TR/2011/WD-contacts-api-20110616/

The Contacts API proposal differs from the DAP specification in some key ways:

• The ContactsAPI preserves much better convergence with vCard4/hCard.
• 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.

• Update W3C ContactsMozDapComparison page with the advantages / reasoning of the ContactsAPI.

Clients

Applications using the ContactsAPI:

• Gaia/Projects/MozContacts
  • Gaia/Contacts

Potential Clients

• Gaia/Email
  • specifically to get a contact's email address and key
  • then massage that key URI into a key object that can be passed to the Crypto API to encrypt an email for the recipient.
  • see microformats key examples use cases for more details.
• Features/Thunderbird/Modern_Address_Book

Background

key property

The key property is defined as:
attribute DOMString[] key;
where each instance is a a key URI per RFC6350 6.8.1.

Mozilla can be an industry leader here by including public keys in address books by default so communication applications can start using and depending on them.

• B2G implementation bug: Bug 807688: Add 'key' a'la hCard to Contacts API
• related UI implementation bug: Bug 807717 - "key" field in Contacts app

Background and research:

• public keys on web pages: key examples research.
• 'key' is supported in hCards by both Firefox Operator and H2VX hCard to vCard.
• not implemented by MOAB, neither vCard import, nor any key field in the UI by default, nor in the UI for adding fields to a contact.

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?

Related

• W3C DAP work - similar but problematic. See the W3C DAP Contacts section for how the ContactsAPI fixes key problems with the DAP approach.
• A more "appy" Contacts API - that allows web apps to both access and be providers for contacts. This ContactsAPI is focused specifically on device contacts access for reasons of design simplification and prioritization for B2G. For exploring a broader / more 'appy' Contacts API see work on WebActions, WebActivities, and Labs/Contacts/ContentAPI.

Also Known As

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

See also

• WebAPI/Security/Contacts
• WebAPI/CalendarAPI