WebAPI/ContactsAPI

Contacts API specification

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 (vCard4/hCard). - Tantek

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

Status

See bug 674720.

Team

• Interface/Standards: Tantek Çelik (IRC: tantek)
• Interface/Implementation: Gregor Wagner (IRC: gwagner)

Example

Example use of the API:

var contact = new mozContact();
contact.init({name: "Tom"}); // Bug 723206
var request = navigator.mozContacts.save(contact);
request.onsuccess = function() {alert("success");};
request.onerror = function() {alert("error")};

Proposed API

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

 interface ContactsManager
 {
   DOMRequest find(in ContactFindOptions options);
   DOMRequest clear();
   DOMRequest save(in Contact contact); // Success value is id? Or new Contact?
   DOMRequest remove(in Contact contact);
 };

 interface ContactFindOptions : nsISupports
 {
   attribute DOMString     filterValue;    // e.g. "Tom"
   attribute DOMString     filterOp;       // e.g. "contains"
   attribute DOMString[]   filterBy;       // e.g. "givenName"
   attribute DOMString     sortBy;         // e.g. "givenName"
   attribute DOMString     sortOrder;      // e.g. "descending"
   attribute unsigned long filterLimit;
 };

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 ContactTelephone : nsISupports
 {
   attribute DOMString type;   // may change to DOMString[] based on research      
   attribute DOMString number;
 };

 interface ContactAddress {
            attribute DOMString              type; // may change to DOMString[] based on research
            attribute DOMString              streetAddress;
            attribute DOMString              locality;
            attribute DOMString              region;
            attribute DOMString              postalCode;
            attribute DOMString              countryName;
 };

 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 ContactTelephone[]     tel;
            attribute DOMString[]            org;
            attribute DOMString[]            jobTitle; /* 'title' from vCard made specific */
            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              genderIdentity'; /* new in vCard4, gender sub-comp 2 */
 };

 [Constructor(in ContactProperties properties)]
 interface Contact : ContactProperties
 {
   readonly attribute DOMString id;
   readonly attribute Date      published;
   readonly attribute Date      updated;
   Contact clone(); // Do we need this function? "new Contact(oldContact)" should just work
 };

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.

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?
• E.g. 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)

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).
• pictures may use "blob:" URIs (to be defined) in the 'photo' property
  • convert blob photos to "data:" URIs when exporting to vCard, and similarly, convert vCard photo data URIs to blog photos when importing.

Priority 1 feature requests

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

• add interface ContactTelephone
  • done

• add interface Email
• add type for Email (similar to ContactTelephone)

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

• 'type' for email, impp, url
• '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.
• human relationships
• vCard4 extensions
• 'type:pref' for ContactTelephone - thus clearly requiring that tel 'type' be DOMString[].
  • iOS dialer implements this 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 this 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.

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)
• phonetic-family-name (iOS, MOAB) (2012-080 requested VCARDDAV)
• 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
• 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

ContactTelephone 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.
• 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 address books have a field in the UI?
      • A quick search didn't turn up any prior art.
      • 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. personally 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.

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

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. 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), 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 needlessly divergent like that.

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.

Issues

permissions and privacy

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 contacts specification [1] sharing some of the goals of this proposal.

[1] http://www.w3.org/TR/contacts-api/ (also editor's draft).

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.

Clients

Applications using the ContactsAPI:

• Gaia/Projects/MozContacts
  • Gaia/Contacts

Potential Clients

• Features/Thunderbird/Modern_Address_Book

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 section below 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.

See also

• WebAPI/CalendarAPI