The Contacts Writer API defines the high-level interfaces required to add and remove contact information to and from a user's unified address book.
This specification is built on top of an accompanying specification [[CONTACTS-API]] that enables read access to a user's unified address book.
Interesting summary of the general issues with a Writer API in the web context: http://lists.w3.org/Archives/Public/public-device-apis/2010Jul/0112.html
This document represents the early consensus of the group on the scope and features of the proposed Contacts API. Issues and editors note in the document highlight some of the points on which the group is still working and would particularly like to get feedback.
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.
Every operating system and a large number of web-based service providers have different ways of representing address book information. Most users are required to maintain a plurality of contact lists which leads to multiple copies of address book data. The multiplicity of address books that a user is required to maintain often leads to disjointed and inconsistent information being stored across a user's address book providers.
Providing address book information to these service providers means handing over all of your data and trusting these providers with the security and privacy of storing and sharing of your information. When sharing this data with 3rd parties users are, more often than not, required to hand over access to their whole address book. Users are implicitly required to trust 3rd parties with all of their data when, in reality, the user may only wish, or need, to share a subset of their address book information so that an application can fulfill its purpose.
This specification defines the concept of a user's unified address book - where address book data may be sourced from a plurality of sources - both online and locally. This specification then defines the interfaces on which 3rd party applications can access a user's unified address book; with explicit user permission and filtering. The focus of this data sharing is on making the user aware of the data that they will share and putting them at the centre of the data sharing process; free to select both the extent to which they share their address book information and the ability to restrict which pieces of information related to which contact gets shared.
The API itself is agnostic of any underlying address book sources and storage. A conforming implementation is required to implement all fields defined in this specification.
The following code extracts illustrate how to search, add, remove and update contact information in a given address book:
Creating a new contact.
// Create new contact
var myContact = navigator.service.contacts.create({displayName: 'Robert'}});
// Add additional contact attributes as required...
// myContact.nicknames.push('bobby');
Saving a new contact in the underlying addressbook.
// previous example follow-on...
function successContactCallback(contact) {
// do something with resulting contact object
alert(contact.displayName);
// ...
}
// Save new contact
myContact.save(successContactCallback, generalErrorCB);
Editing an existing contact.
// previous example follow-on...
// e.g. add a new phone number
myContact.phoneNumbers.push({type: 'home', value: '+440000000002'});
// Update existing contact
myContact.save(successContactCallback, generalErrorCB);
Removing an existing contact.
// previous example follow-on... // Remove existing contact myContact.remove(successContactCallback, generalErrorCB);
The overall architecture for addressing privacy in DAP is still under construction. As it is finalized, there may be changes made to this API to reflect requirements or support for privacy-related functionality.
The API defined in this specification can be used to create, find, save and remove contact information from a user's address book(s). All API methods disclose information related to a user's contacts such as their phone number(s), email address(es) and other personally identifying information. The distribution of this information could potentially compromise the user's privacy. A conforming implementation of this specification MUST provide a mechanism that protects the user's privacy and this mechanism should ensure that no contact information is creatable, retrivable, updateable or removable without the user's express permission.
A user agent must not create, find, save or delete contact information to Web sites without the express permission of the user. A user agent must acquire permission through a user interface, unless they have prearranged trust relationships with users, as described below. The user interface must include the URI of the document origin, as defined in [[HTML5]]. Those permissions that are acquired through the user interface and that are preserved beyond the current browsing session (i.e. beyond the time when the browsing context, as defined in [[HTML5]], is navigated to another URL) MUST be revocable and a user agent must respect revoked permissions.
Obtaining the user's express permission to access one API method does not imply the user has granted permission for the same Web site to access other methods provided by this API, or to access the same method with a different set of arguments, as part of the same permission context. If a user has expressed permission for an implementation to, e.g. find a set of existing contacts, the implementation must seek the user's express permission if and when any additional create, find, save or remove function is called on this API.
A user agent may have prearranged trust relationships that do not require such user interfaces. For example, while a Web browser will present a user interface when a Web site performs an address book request, a Widget Runtime MAY have a prearranged, delegated security relationship with the user and, as such, a suitable alternative security and privacy mechanism with which to authorize the creation, retrieval, update and/or removal of contact information.
Recipients MUST only request contact information when necessary. Recipients MUST only use the contact information for the task for which it was provided to them. Recipients MUST dispose of contact information once that task is completed, unless expressly permitted to retain it by the user. Recipients MUST also take measures to protect this information against unauthorized access. If contact information is stored, users should be allowed to update and delete this information.
The recipient of contact information MUST not retransmit the contact information without the user's express permission. Care should be taken when retransmitting and use of encryption is encouraged.
Recipients MUST clearly and conspicuously disclose the fact that they are collecting contact data, the purpose for the collection, how long the data is retained, how the data is secured, how the data is shared if it is shared, how users can access, update and delete the data, and any other choices that users have with respect to the data. This disclosure MUST include an explanation of any exceptions to the guidelines listed above.
Further to the requirements listed in the previous section, implementors of the Contacts API are also advised to consider the following aspects that can negatively affect the privacy of their users: in certain cases, users can inadvertently grant permission to the User Agent to disclose their contacts to Web sites. In other cases, the content hosted at a certain URL changes in such a way that the previously granted contact permissions no longer apply as far as the user is concerned. Or the users might simply change their minds.
Predicting or preventing these situations is inherently difficult. Mitigation and in-depth defensive measures are an implementation responsibility and not prescribed by this specification. However, in designing these measures, implementers are advised to enable user awareness of contact sharing, and to provide easy access to interfaces that enable revocation of permissions.
The ContactsWriter interface exposes a database collecting contacts information, such that they may be created, updated, and deleted.
Contact object.
This method takes one argument. When called, it returns a Contact object.
The newly created Contact object MUST NOT be stored in the user's address book as a result of
calling this method. The Contact save() method MUST be called on the response of this method to store the new Contact object in the user's address book.
The ContactWriter interface captures a single contact item. This interface extends ContactProperties attributes.
All Contact objects MUST include all attributes supported by the implementation,
regardless of whether these attributes have been assigned a non-null value or a null value.
If a supported attribute has not been assigned a value by the user and/or implementation, then this attribute MUST still be
present in the resulting Contact object and MUST have a value of null.
Create a deep clone copy of the current object minus the current object's id attribute.
The resulting object MUST be provided with a newly generated id attribute to distiguish the cloned object from the original object.
Add or update (as appropriate) the current Contact object to the Contacts.
This method takes one or two arguments. When called, it immediately returns a PendingOp object, as defined in
[[!CORE-DEVICE]], and then asynchronously starts a save contact process defined as follows:
null errorCB argument, invoke the errorCB with a PENDING_OPERATION_ERROR code.
Contact.id value is not recognized in Contacts or a Contact.id value has not been set, create and set a new Contact.id value and add the current object as a new object to Contacts.
Contact.id already exists in Contacts then update the existing object in Contacts.
successCB. If the attempt fails, and the method was invoked with a
non-null errorCB argument, this method must invoke the errorCB with a ContactError object as an argument.
Remove the current contact from the address book.
In the case that the current id attribute is null and this method is invoked, a ContactErrorCB MUST be triggered as part of the remove contact
process. This error MUST consist of a ContactError object with a code of NOT_FOUND_ERROR.
This method takes one or two arguments. When called, it immediately returns a PendingOp object, as defined in
[[!CORE-DEVICE]], and then asynchronously starts a remove contact process defined as follows:
null errorCB argument, invoke the errorCB with a PENDING_OPERATION_ERROR code.
Contacts.
Contacts was successful, set the current object's Contact.id value to null.
successCB. If the attempt fails, and the method was invoked with a
non-null errorCB argument, this method must invoke the errorCB with a ContactError object as an argument.
Contact save() or Contact remove() method.
The ContactError interface encapsulates all errors in the manipulation of Contact objects in the Contacts API.
This specification is primarily intended to provide the user with the ability to view and control the contact information that may be shared, saved or removed from their unified address book. This annex provides some examples of a conformant user experience that this specification enables.
Include Contact creation/modification writeback mockup.
Include Contact deletion writeback mockup.