WebAPI/ContactsAPI/2012

From MozillaWiki
Jump to: navigation, search

Contacts API specification 2012

  • This version: This is a snapshot of the ContactsAPI specification as of 2012 that was implemented in B2G milestone 1.
  • Current version: ContactsAPI
  • Editor: Tantek Çelik (IRC: tantek)

Acknowledgments

Thanks to contributions to the specification and the implementation written by 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")};

API

Note: this is the 2012 snapshot of the ContactsAPI. For the latest version of the API, see:


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;
 };

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 and current typical mobile address book user interfaces. 

 interface ContactField : nsISupports
 {
   attribute DOMString[] type;  // for primary/favorite (use:"PREF"), "home", "work", etc.
   attribute DOMString value;
 };

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

 interface ContactAddress {
            attribute DOMString[]            type; // for primary/favorite (use:"PREF"), "home", "work", etc.
            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 ContactField[]         email;
            attribute DOMString[]            photo;
            attribute ContactField[]         url;
            attribute DOMString[]            category;
            attribute ContactAddress[]       adr;
            attribute ContactTelField[]      tel;
            attribute DOMString[]            org;
            attribute DOMString[]            jobTitle; /* 'title' from vCard made specific */
            attribute Date                   bday;
            attribute DOMString[]            note;
            attribute ContactField[]         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;
 };

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.

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

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" (e.g. for a home 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).

More details:

  • Summary: 'type:pref' for ContactField is how implementations implement a preferred contact address out of several of the same type - thus clearly requiring that ContactField '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.
    • interface ContactField now has DOMString[] type accordingly.

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.

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.

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

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

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:

Articles

Articles mentioning / discussion the ContactsAPI:

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

Retrieved from "https://wiki.mozilla.org/index.php?title=WebAPI/ContactsAPI/2012&oldid=1021371"