WebAPI/ContactsAPI

From MozillaWiki
Jump to navigation Jump to search

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

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.

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

Status

See bug 674720.

Example

Example use of the API: 

var contact = new mozContact();
mozContact.init({name: "Tom"}); // Bug 723206
var request = navigator.mozContacts.save(mozContact);
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;
 };

 interface nsIDOMContactTelephone : nsISupports
 {
   attribute jsval type;        // DOMString[]
   attribute DOMString number;
 };

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 jsval                  type;
            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 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:

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). Demonstrate that a feature is in the UI of multiple devices, and that when you export a contact (as a vCard / .vcf file) from each of those devices with that feature, that it successfully imports into the other devices, and round-trips without loss of fidielity.
  • 4. More vCard4 features. 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. 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;
  • favorites may be implemented as category: "favorite"
  • pictures may use "blob:" URIs (to be defined) in the 'photo' property

Priority 1 feature requests

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

  • add interface ContactTelephone
    • change ContactProperties tel from "DOMString[]" to "ContactTelephone[]"
    • define a new "interface ContactTelephone" with
      • DOMString[] type; // or just DOMString type; and force multivalues to be comma delimited e.g. iOS "work fax" becomes "work,fax" for vCard compat.
      • DOMString number;

Priority 2 feature requests

Gaia Contacts App UI v2 feature requests 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?
  • add type to interface ContactAddress:
    • DOMString[] type; // or just DOMString type; and force multivalues to be comma delimited e.g. "dom postal" becomes "dom,postal" for vCard compat.

Priority 3 feature requests

None currently.

Priority 4 feature requests

Features requested by one or more individuals which are already present in the vCard4 spec.

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

Priority 5 feature requests

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

Priority 6 feature requests

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

  • 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).
  • custom dates
  • favorites (as a native feature rather than workaround with category:favorite)
  • 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

Out of scope

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

  • arbitrary key/value storage with a contact. 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://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.

Clients

Applications using the ContactsAPI:

Potential Clients

Articles

Articles mentioning / discussion the ContactsAPI:

Retrieved from "https://wiki.allizom.org/index.php?title=WebAPI/ContactsAPI&oldid=424678"