Abstract

This specification defines a System Level API which offers a simple interface to manage user's contacts stored in the system's address book. A typical use case of the Contacts API is the implementation of an application to manage said address book.

Status of This Document

This section describes the status of this document at the time of its publication. Other documents may supersede this document. A list of current W3C publications and the latest revision of this technical report can be found in the W3C technical reports index at http://www.w3.org/TR/.

This document defines a System Level API to manage the user's contacts that are stored in the system's address book. Future versions of this specification are expected to align the contact data model with the Contacts API being defined by the Device APIs Working Group.

If you find any issue with this specification, please file a bug on Github.

This document was published by the System Applications Working Group as an Editor's Draft. If you wish to make comments regarding this document, please send them to public-sysapps@w3.org (subscribe, archives). All comments are welcome.

Publication as an Editor's Draft does not imply endorsement by the W3C Membership. This is a draft document and may be updated, replaced or obsoleted by other documents at any time. It is inappropriate to cite this document as other than work in progress.

This document was produced by a group operating under the 5 February 2004 W3C Patent Policy. W3C maintains a public list of any patent disclosures made in connection with the deliverables of the group; that page also includes instructions for disclosing a patent. An individual who has actual knowledge of a patent which the individual believes contains Essential Claim(s) must disclose the information in accordance with section 6 of the W3C Patent Policy.

This document is governed by the 1 August 2014 W3C Process Document.

Table of Contents

1. Introduction

This section is non-normative.

The Contacts API allows to manage (create, edit, remove, etc) user's contacts stored in the system's address book, and thus provides the functionality needed to implement an application to manage said address book.

An example of use is provided below:

Example 1
var contactName = new ContactName({
  givenNames: ['John'],
  familyNames: ['Doe']
  });
var mobilePhone = new ContactTelField({ types: ['home'], preferred: true, value: '+34698765432' });
var contact = new Contact({
  name: contactName,
  phoneNumbers: [mobilePhone]
  });
navigator.contacts.save(contact).then(
   function(contact) { window.console.log('Contact  ' +
          contact.name.givenNames[0] + ' ' +
          contact.name.familyNames[0] + ' saved!'); },
   function(error) {   window.console.error('Error: ' + error); } )

2. Conformance

As well as sections marked as non-normative, all authoring guidelines, diagrams, examples, and notes in this specification are non-normative. Everything else in this specification is normative.

The key word MUST is to be interpreted as described in [RFC2119].

This specification defines conformance criteria that apply to a single product: the user agent that implements the interfaces that it contains.

Implementations that use ECMAScript to implement the APIs defined in this specification MUST implement them in a manner consistent with the ECMAScript Bindings defined in the Web IDL specification [WEBIDL], as this specification uses that specification and terminology.

3. Terminology

The EventHandler interface represents a callback used for event handlers as defined in [HTML5].

The concepts queue a task and fire a simple event are defined in [HTML5].

The terms event handler and event handler event types are defined in [HTML5].

The Promise interface, the concepts of a resolver, a resolver's fulfill algorithm and a resolver's reject algorithm are defined in [DOM4].

4. Security and privacy considerations

This API must be only exposed to trusted content

6. ContactsManager Interface

The ContactsManager interface exposes the contacts management functionality. 

interface ContactsManager : EventTarget {
    Promise find (optional ContactFindOptions options);
    Promise clear ();
    Promise save (Contact contact);
    Promise remove (DOMString contactId);
                attribute EventHandler oncontactschange;
};

6.1 Attributes

oncontactschange of type EventHandler,
May be used to set an event handler to be called when contacts are added, deleted or changed in some way.

6.2 Methods

clear
This method allows to remove all contacts in the address book. It returns a Promise that will allow the caller to be notified about the result of the operation.
No parameters.
Return type: Promise
find
This method allows to search contacts within the address book that match the criteria indicated in the options parameter. It returns a Promise that will allow the caller to be notified about the result of the operation.
ParameterTypeNullableOptionalDescription
optionsContactFindOptions✘✔ Set of criteria that a contact needs to match to be included in the outcomes of the find operation.
Return type: Promise
remove
This method allows to remove a contact from the address book. It returns a Promise that will allow the caller to be notified about the result of the operation.
ParameterTypeNullableOptionalDescription
contactIdDOMString✘✘ The identifier of the Contact object that is requested to be removed from the address book.
Return type: Promise
save
This method allows to save a contact in the address book, e.g. an existing contact after having been edited. So if a contact with the same identifier, i.e. id, already exists in the address book, it will be updated. It returns a Promise that will allow the caller to be notified about the result of the operation.
ParameterTypeNullableOptionalDescription
contactContact✘✘ The Contact object that is requested to be saved in the address book.
Return type: Promise

The find method when invoked MUST run the following steps:

  1. Let promise be a new Promise object and resolver its associated resolver.
  2. Return promise and continue the following steps asynchronously.
  3. Make a request to the system to retrieve the contacts in the address book matching the criteria indicated in the options parameter.
  4. If there is an error invoke resolver's reject algorithm with no argument and terminate these steps.
  5. When the request has been completed:
    1. Let contacts be a new array of Contact objects providing the results of the find operation.
    2. Invoke resolver's fulfill algorithm with contacts as the value argument.

The clear method when invoked MUST run the following steps:

  1. Let promise be a new Promise object and resolver its associated resolver.
  2. Return promise and continue the following steps asynchronously.
  3. Make a request to the system to clear all the contacts in the address book.
  4. If there is an error invoke resolver's reject algorithm with no argument and terminate these steps.
  5. When the request has been completed invoke resolver's fulfill algorithm with no argument and terminate these steps.

The save method when invoked MUST run the following steps:

  1. Let promise be a new Promise object and resolver its associated resolver.
  2. Return promise and continue the following steps asynchronously.
  3. Make a request to the system to save in the address book the Contact object passed as parameter.
  4. If there is an error invoke resolver's reject algorithm with no argument and terminate these steps.
  5. When the request has been completed:
    1. Let contact be the Contact object as returned by the system, and which therefore has its id and lastUpdated parameters set, whereas they could be null in the original Contact object passed as parameter, for instance if it is a brand new Contact object not yet stored in the address book.
    2. Invoke resolver's fulfill algorithm with contact as the value argument.

The remove method when invoked MUST run the following steps:

  1. Let promise be a new Promise object and resolver its associated resolver.
  2. Return promise and continue the following steps asynchronously.
  3. Make a request to the system to remove the Contact object identified by the contactId passed as parameter from the address book.
  4. If there is an error invoke resolver's reject algorithm with no argument and terminate these steps.
  5. When the request has been completed invoke resolver's fulfill algorithm with no argument and terminate these steps.

Upon a change in a contact or set thereof is performed (i.e. contact(s) added / modified / removed) the system MUST fire a simple event named contactschange that implements the ContactsChangeEvent interface at the ContactsManager object

6.3 Event handlers

The following are the event handlers (and their corresponding event handler event types) that MUST be supported as attributes by the ContactsManager object:

event handler event handler event type
oncontactschange contactschange

The event named contactschange MUST implement the ContactsChangeEvent interface.

7. ContactFindOptions Dictionary

The ContactFindOptions dictionary represents the criteria used to select the contacts to be returned by a find operation. 

dictionary ContactFindOptions {
    DOMString           value;
    FilterOperator      operator;
    sequence<DOMString> fields;
    sequence<DOMString> sortBy;
    SortOrder           sortOrder;
    unsigned long       resultsLimit;
};

7.1 Dictionary ContactFindOptions Members

fields of type sequence<DOMString>
Represents the set of fields in which the search is performed (e.g. "givenName").
operator of type FilterOperator
Represents the filtering operator used for the filtering.
resultsLimit of type unsigned long
Represents the maximum number of results that can be returned by the search operation.
sortBy of type sequence<DOMString>
Represents the fields by which the results of the search are sorted (e.g. ["givenNames", "familyNames"]). The results are sorted by the first field, then by the following one, if present, and so on.
sortOrder of type SortOrder
Represents the order in which the results of the search are sorted.
value of type DOMString
Represents the value used for the filtering (e.g. "Tom").

7.2 Enumerations

There are 2 possible filter operations: 

enum FilterOperator {
    "contains",
    "is"
};
Enumeration description
contains With this operation, a contact will be returned if its filtered field contains the given value.
is With this operation, a contact will be returned if its filtered field matches exactly the given value.

The returned contacts can be sorted in one of the following orders: 

enum SortOrder {
    "ascending",
    "descending"
};
Enumeration description
ascending The contacts will be sorted in ascending order.
descending The contacts will be sorted in descending order.
Issue 1

It is for further study whether the level of flexibility of the filters needs to be increased and/or additional mechanisms need to be put in place so that applications can keep a local copy of the address book and perform the filtering locally (e.g. startTrackingChanges() and getNewChanges() methods)

8. ContactField Interface

The ContactField interface represents a user's attribute and the types associated to it. 

[Constructor(optional ContactFieldInit initDict)]
interface ContactField {
                attribute DOMString[] types;
                attribute boolean     preferred;
                attribute DOMString   value;
};

8.1 Attributes

preferred of type boolean,
Indicates whether this is the preferred contact field.
types of type array of DOMString,
Indicates the types of this contact field (e.g. "home", "work").
value of type DOMString,
A string that contains the user's address.

8.2 ContactFieldInit Dictionary

dictionary ContactFieldInit {
    sequence<DOMString> types;
    boolean             preferred;
    DOMString           value;
};

8.2.1 Dictionary ContactFieldInit Members

preferred of type boolean
types of type sequence<DOMString>
value of type DOMString

9. ContactTelField Interface

The ContactTelField interface represents a telephone number as well as metadata associated to it, namely the types (e.g. "voice", "text") and the carrier providing service to the telephony subscription associated to that number. 

[Constructor(optional ContactTelFieldInit initDict)]
interface ContactTelField : ContactField {
                attribute DOMString? carrier;
};

9.1 Attributes

carrier of type DOMString, , nullable
Indicates the carrier providing service to the telephony subscription associated to that number

9.2 ContactTelFieldInit Dictionary

dictionary ContactTelFieldInit : ContactFieldInit {
    DOMString carrier;
};

9.2.1 Dictionary ContactTelFieldInit Members

carrier of type DOMString

10. ContactAddress Interface

The ContactAddress interface represents a user's physical address and the types associated to it. This interface is based on vCard 4.0 ADR attribute. 

[Constructor(optional ContactAddressInit initDict)]
interface ContactAddress {
                attribute DOMString[] types;
                attribute boolean     preferred;
                attribute DOMString   streetAddress;
                attribute DOMString   locality;
                attribute DOMString   region;
                attribute DOMString   postalCode;
                attribute DOMString   countryName;
};

10.1 Attributes

countryName of type DOMString,
A string that contains the name of the country. It maps to the seventh component in vCard's ADR attribute.
locality of type DOMString,
A string that contains the name of the locality. It maps to the forth component in vCard's ADR attribute.
postalCode of type DOMString,
A string that contains the postal code. It maps to the sixth component in vCard's ADR attribute.
preferred of type boolean,
Indicates whether this is the preferred contact field.
region of type DOMString,
A string that contains the name of the region. It maps to the fifth component in vCard's ADR attribute.
streetAddress of type DOMString,
A string that contains the name of the street. It maps to the third component in vCard's ADR attribute.
types of type array of DOMString,
Indicates the types of this contact field (e.g. "home", "work").

10.2 ContactAddressInit Dictionary

dictionary ContactAddressInit {
    sequence<DOMString> types;
    boolean             preferred;
    DOMString           streetAddress;
    DOMString           locality;
    DOMString           region;
    DOMString           postalCode;
    DOMString           countryName;
};

10.2.1 Dictionary ContactAddressInit Members

countryName of type DOMString
locality of type DOMString
postalCode of type DOMString
preferred of type boolean
region of type DOMString
streetAddress of type DOMString
types of type sequence<DOMString>

11. The ContactGender enum

enum ContactGender {
    "male",
    "female",
    "other",
    "none",
    "unknown"
};
Enumeration description
malecontact is a male.
femalecontact is a female.
othercontact has another gender.
nonecontact does not have a gender (not applicable).
unknowncontact's gender is unknown.

12. ContactName Interface

The ContactName interface represents a user's naming attributes. 

[Constructor(optional ContactNameInit initDict)]
interface ContactName {
                attribute DOMString   displayName;
                attribute DOMString[] honorificPrefixes;
                attribute DOMString[] givenNames;
                attribute DOMString[] additionalNames;
                attribute DOMString[] familyNames;
                attribute DOMString[] honorificSuffixes;
                attribute DOMString[] nicknames;
};

12.1 Attributes

additionalNames of type array of DOMString,
A string or set thereof representing any additional name of the contact. It maps to the third component in vCard's N attribute.
displayName of type DOMString,
A string representing the contact's display name. It maps to vCard's FN attribute.
familyNames of type array of DOMString,
A string or set thereof representing the contact's family name(s). It maps to the first component in vCard's N attribute.
givenNames of type array of DOMString,
A string or set thereof representing the contact's given name(s). It maps to the second component in vCard's N attribute.
honorificPrefixes of type array of DOMString,
A string or set thereof representing the contact's honorific prefix(es). It maps to the forth component in vCard's N attribute.
honorificSuffixes of type array of DOMString,
A string or set thereof representing the contact's honorific suffix(es). It maps to the fifth component in vCard's N attribute.
nicknames of type array of DOMString,
A string or set thereof representing the contact's nick name(s). It maps to vCard's NICKNAME attribute.

12.2 ContactNameInit Dictionary

dictionary ContactNameInit {
    DOMString           displayName;
    sequence<DOMString> honorificPrefixes;
    sequence<DOMString> givenNames;
    sequence<DOMString> additionalNames;
    sequence<DOMString> familyNames;
    sequence<DOMString> honorificSuffixes;
    sequence<DOMString> nicknames;
};

12.2.1 Dictionary ContactNameInit Members

additionalNames of type sequence<DOMString>
displayName of type DOMString
familyNames of type sequence<DOMString>
givenNames of type sequence<DOMString>
honorificPrefixes of type sequence<DOMString>
honorificSuffixes of type sequence<DOMString>
nicknames of type sequence<DOMString>

13. Contact Interface

The Contact interface represents a contact stored in the address book. As a principle the attributes are based on vCard 4.0 and reuse the literal used in that standard. Any naming deviation is mentioned in the description of the corresponding attribute. Whereas this correspondence facilitates the import/export from/to vCard format it should be noted that a vCard import/export API is out of scope of this specification as parsing and serializing can be efficiently done in JavaScript, and libraries are readily available. 

[Constructor(optional ContactInit contactInitDict)]
interface Contact {
    readonly    attribute DOMString?        id;
    readonly    attribute Date?             lastUpdated;
                attribute ContactName       name;
                attribute ContactField[]    emails;
                attribute DOMString[]       photos;
                attribute ContactField[]    urls;
                attribute DOMString[]       categories;
                attribute ContactAddress[]  addresses;
                attribute ContactTelField[] phoneNumbers;
                attribute DOMString[]       organizations;
                attribute DOMString[]       jobTitles;
                attribute Date?             birthday;
                attribute DOMString[]       notes;
                attribute ContactField[]    impp;
                attribute Date?             anniversary;
                attribute ContactGender     gender;
};

13.1 Attributes

addresses of type array of ContactAddress,
A ContactAddress element or set thereof containing the user's physical address(es). It maps to vCard's ADR attribute
anniversary of type Date, , nullable
A Date element representing the contact's anniversary. It maps to vCard's ANNIVERSARY attribute
birthday of type Date, , nullable
A Date element representing the contact's birth date. It maps to vCard's BDAY attribute
categories of type array of DOMString,
A string or set thereof representing the category or categories associated to the contact (e.g. "family"). It maps to vCard's CATEGORIES attribute.
emails of type array of ContactField,
A ContactField element or set thereof containing the contact's email address(es). It maps to vCard's EMAIL attribute.
gender of type ContactGender,
A string representing the contact's gender. It maps to the first component of vCard's GENDER attribute.
id of type DOMString, readonly , nullable
Represents a unique identifier of the contact in the address book.
impp of type array of ContactField,
A ContactField element or set thereof containing the user's instant messaging address(es). It maps to vCard's IMPP attribute
jobTitles of type array of DOMString,
A string or set thereof representing the contact's job title(s). It maps to vCard's TITLE attribute
lastUpdated of type Date, readonly , nullable
A Date element representing the date when the contact was last updated.
name of type ContactName,
An object representing the different naming attributes of the contact.
notes of type array of DOMString,
A string or set thereof specifying supplemental information or a comment that is associated with the contact. It maps to vCard's NOTE attribute
organizations of type array of DOMString,
A string or set thereof representing the organization(s) the contact belongs to. It maps to vCard's ORG attribute
phoneNumbers of type array of ContactTelField,
A ContactTelField element or set thereof containing the user's telephone numbers. It maps to vCard's TEL attribute
photos of type array of DOMString,
A string or set thereof representing the URI of the photo(s) of the contact. It maps to vCard's PHOTO attribute.
urls of type array of ContactField,
A ContactField element or set thereof containing the user's urls (e.g. personal blog). It maps to vCard's URL attribute.

13.2 Steps

The Contact interface's contructor when invoked MUST run the following steps:

  1. Let contact be a new Contact object.
  2. Make a request to the system to generate a new unique contact identifier.
  3. Set the id attribute of contact to the generated contact identifier.
  4. Set the lastUpdated attribute of contact to the Date at which the constructor was invoked.
  5. Set the other attributes of contact to the value of the corresponding element in the contactInitDict dictionary, if present.

13.3 ContactInit Dictionary

dictionary ContactInit {
    ContactName               name;
    sequence<ContactField>    emails;
    sequence<DOMString>       photos;
    sequence<ContactField>    urls;
    sequence<DOMString>       categories;
    sequence<ContactAddress>  addresses;
    sequence<ContactTelField> phoneNumbers;
    sequence<DOMString>       organizations;
    sequence<DOMString>       jobTitles;
    Date                      birthday;
    sequence<DOMString>       notes;
    sequence<ContactField>    impp;
    Date                      anniversary;
    ContactGender             gender;
};

13.3.1 Dictionary ContactInit Members

addresses of type sequence<ContactAddress>
anniversary of type Date
birthday of type Date
categories of type sequence<DOMString>
emails of type sequence<ContactField>
gender of type ContactGender
impp of type sequence<ContactField>
jobTitles of type sequence<DOMString>
name of type ContactName
notes of type sequence<DOMString>
organizations of type sequence<DOMString>
phoneNumbers of type sequence<ContactTelField>
photos of type sequence<DOMString>
urls of type sequence<ContactField>

14. ContactsChangeEvent Interface

The ContactsChangeEvent interface represents events related to the set of contacts that have been simultaneously added, removed and/or modified. Changes that are applied to the address book in batches cause a ContactsChangeEvent with multiple contact references to be fired, whereas changes applied sequentially cause a ContactsChangeEvent with a single contact reference to be fired 

[Constructor(DOMString type, optional ContactsChangeEventInit
      eventInitDict)]
interface ContactsChangeEvent : Event {
    readonly    attribute DOMString[] added;
    readonly    attribute DOMString[] modified;
    readonly    attribute DOMString[] removed;
};

14.1 Attributes

added of type array of DOMString, readonly
Indicates the identifier(s) of the Contact object(s) that have been added.
modified of type array of DOMString, readonly
Indicates the identifier(s) of the Contact object(s) that have been modified.
removed of type array of DOMString, readonly
Indicates the identifier(s) of the Contact object(s) that have been removed.

14.2 ContactsChangeEventInit Dictionary

dictionary ContactsChangeEventInit : EventInit {
    sequence<DOMString> added;
    sequence<DOMString> modified;
    sequence<DOMString> removed;
};

14.2.1 Dictionary ContactsChangeEventInit Members

added of type sequence<DOMString>
modified of type sequence<DOMString>
removed of type sequence<DOMString>

15. Acknowledgements

The editors would like to express their gratitude to the Mozilla B2G Team for their technical guidance, implementation work and support, and specially to Tantek Çelik and Gregor Wagner, the original authors of B2G Contact API.

A. References

A.1 Normative references

[HTML5]
Ian Hickson; Robin Berjon; Steve Faulkner; Travis Leithead; Erika Doyle Navara; Edward O'Connor; Silvia Pfeiffer. HTML5. 28 October 2014. W3C Recommendation. URL: http://www.w3.org/TR/html5/
[RFC2119]
S. Bradner. Key words for use in RFCs to Indicate Requirement Levels. March 1997. Best Current Practice. URL: https://tools.ietf.org/html/rfc2119
[WEBIDL]
Cameron McCormack. Web IDL. 19 April 2012. W3C Candidate Recommendation. URL: http://www.w3.org/TR/WebIDL/

A.2 Informative references

[DOM4]
Anne van Kesteren; Aryeh Gregor; Ms2ger; Alex Russell; Robin Berjon. W3C DOM4. 10 July 2014. W3C Last Call Working Draft. URL: http://www.w3.org/TR/dom/