Copyright © 2011 W3C® (MIT, ERCIM, Keio), All Rights Reserved. W3C liability, trademark and document use rules apply.
The Contacts API defines the high-level interfaces required to obtain read access to a user's unified address book.
This API includes the following key interfaces:
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 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 document was published by the Device APIs and Policy Working Group as a Last Call Working Draft. This document is intended to become a W3C Recommendation. If you wish to make comments regarding this document, please send them to public-device-apis@w3.org (subscribe, archives). The Last Call period ends 14 July 2011. All feedback is welcome.
Publication as a Working 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 is a Last Call Working Draft and thus the Working Group has determined that this document has satisfied the relevant technical requirements and is sufficiently stable to advance through the Technical Recommendation process.
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 section is non-normative.
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. This in turn often leads to disjointed and inconsistent information being stored across a user's address book providers.
When sharing contact data with third parties users are, more often than not, required to hand over access to their whole address book. Users are implicitly required to trust third 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 fulfil 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. It then defines the interfaces through which third 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.
A set of Security and Privacy Considerations are presented for the discretion of both implementors of the Contacts API and recipients of contact information (i.e. web pages). This specification provides a set of non-normative User Interaction Guidelines demonstrating an example user experience that is compliant with the Security and Privacy Considerations described herein.
This specification also provides informative examples illustrating how to add and update contact information, utilising existing web platform APIs.
The following code illustrates how to obtain contact information from a user's address book:
function success (contacts) { // do something with resulting contact objects for (var i in contacts) alert(contacts[i].name); // ... } function error (err) { // do something with resulting error alert(err.code); // ... } // Perform an address book search. Obtain the 'name' and 'emails' properties // and initially filter the list to Contact records containing 'Bob': navigator.contacts.find( ['name', 'emails'], success, error, {filter: 'Bob'} ); // ..is equivalent to: navigator.contacts(/* parameters */)
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 words must, must not, required, should, should not, recommended, may, and optional in this specification are 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.
A conforming implementation is required to implement all fields defined in this specification.
The terms document base URL, browsing context, event handler attribute, event handler event type, task, task source and task queues are defined by the HTML5 specification [HTML5].
The task source used by this specification is the device task source.
To dispatch a success event means that an event with the name
success, which does not bubble and is not cancellable, and which uses the
Event interface, is to be dispatched at the ContactFindCB object.
To dispatch an error event means that an event with the name
error, which does not bubble and is not cancellable, and which uses the Event
interface, is to be dispatched at the ContactErrorCB object.
The API defined in this specification can be used to find contact information from a user's address books. This discloses information related to a user's contacts such as their phone numbers, email addresses and other personally identifying information. The distribution of this information could potentially compromise the user's privacy, or the user's contacts' 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 retrievable without the user's express permission.
A user agent must not provide 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 document base URL. 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 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 find 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 [WIDGETS] runtime may have a prearranged, delegated security relationship with the user and, as such, a suitable alternative security and privacy mechanism with which to authorise the retrieval of contact information.
This section is non-normative.
Web sites operators that retrieve contacts information using this API are denoted as recipients below.
Recipients should only request contact information when necessary, and only use the contact information for the task for which it was provided to them.
Recipients should dispose of contact information once that task is completed, unless expressly permitted to retain it by the user. Recipients should also take measures to protect this information against unauthorised access. If contact information is stored, users should be allowed to update and delete this information.
The recipient of contact information should not retransmit the contact information without the user's express permission. Care should be taken when retransmitting and use of encryption is encouraged.
Recipients should 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 should include an explanation of any exceptions to the guidelines listed above.
Note that even if a user gives permission to share their contact information this can have serious privacy implications for those parties whose contacts are shared, as they may not wish such sharing to occur. This should be considered by web services when requesting and using such information.
This section is non-normative.
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 that web applications have to access this API.
ServiceContacts interface
The ServiceContacts interface is exposed on the Navigator
object [NAVIGATOR]. Its goal is to provide an access point to the functionality in this
specification.
[NoInterfaceObject]
interface ServiceContacts {
readonly attribute Contacts contacts;
};
contacts of type Contacts, readonlyNavigator implements ServiceContacts;All instances of the Navigator type are defined to also implement the ServiceContacts interface.
Contacts interface
The Contacts interface exposes a database of contact information that may be retrieved.
Multiple contact groups can be represented within this unified address book by specifying consistent
categories values as part of individual
Contact objects. Multiple contact groups can be displayed by filtering on the required
categories values via
the Contacts find() operation.
[NoInterfaceObject]
interface Contacts {
caller void find (DOMString[] fields, ContactFindCB successCB, optional ContactErrorCB errorCB, optional ContactFindOptions options);
};
findFind contacts in the address book according to the find contacts process detailed below.
This method takes two, three or four arguments. When called, it starts the following find contacts process:
find() operation is still pending a response), run these
substeps:
ContactError
object whose code attribute has the value PENDING_OPERATION_ERROR and
queue a task to invoke errorCallback with error as its argument.
Contact objects obtained by searching contacts in the address book
according to the rules defined in Contact Search Processing,
or null if the search has failed.
ContactError
object whose code attribute has its value set according to the type of failure that occurred and
queue a task to invoke errorCallback with error as its argument.
| Parameter | Type | Nullable | Optional | Description |
|---|---|---|---|---|
| fields | DOMString[] | ✘ | ✘ | The search qualifier. |
| successCB | | ✘ | ✘ | Function to call when the asynchronous operation completes successfully. |
| errorCB | | ✘ | ✔ | Function to call when the asynchronous operation fails. |
| options | | ✘ | ✔ | The options to apply to the output of this method. |
caller voidContact interface
The Contact interface captures the properties of a contact object. All properties included in this
interface have a corresponding definition in [POCO-SCHEMA], [RFC2426] (aka vCard), and [OMA-CAB], thereby
allowing the API to be supported across implementations supporting these various contact formats.
All Contact objects must include all attributes supported by the implementation, regardless
of whether these attributes have been assigned a null value or not. If a supported attribute has not been
assigned a value by the user or the implementation, then this attribute must still be present in the
resulting Contact object and must have a value of null.
Additional attributes may be included according to the provisions detailed in
Extended Contact Properties and Parameters. If an
extended attribute is supported by the current implementation and has not been assigned a value by the
user or the implementation, then this extended attribute must still be present in the resulting
Contact object and must have a value of null.
[NoInterfaceObject]
interface Contact {
readonly attribute DOMString id;
attribute DOMString? displayName;
attribute ContactName? name;
attribute DOMString? nickname;
attribute ContactField[]? phoneNumbers;
attribute ContactField[]? emails;
attribute ContactAddress[]? addresses;
attribute ContactField[]? ims;
attribute ContactOrganization[]? organizations;
attribute Date? birthday;
attribute DOMString? note;
attribute ContactField[]? photos;
attribute DOMString[]? categories;
attribute ContactField[]? urls;
};
addresses of type array of ContactAddress, nullable
This attribute represents one or more physical addresses associated with this Contact.
birthday of type Date, nullable
This attribute contains birthday of this Contact.
The year value may be set to 0000 when the age of the Contact is private or the year is not
available.
categories of type array of DOMString, nullable
This attribute contains one or more user-defined categories/tags/labels associated with this
Contact. e.g. "family", "favourite", "cryptozoologists".
displayName of type DOMString, nullable
This attribute contains the name of this Contact in a form that is suitable for display
to the user.
emails of type array of ContactField, nullable
This attribute represents one or more email addresses associated with this Contact.
id of type DOMString, readonly
A globally unique identifier for the given Contact object.
An implementation must maintain this globally unique identifier when a Contact is added
to an address book.
ims of type array of ContactField, nullable
This attribute represents one or more instant messaging identifiers associated with this
Contact.
name of type ContactName, nullable
This attribute represents the full name of this Contact indicated by the name components
associated with the ContactName object.
nickname of type DOMString, nullable
This attribute contains the nickname (or a casual name) for this Contact.
note of type DOMString, nullable
This attribute contains the personal notes (free-text) for this Contact that is managed by the
user of the address book.
organizations of type array of ContactOrganization, nullable
This attribute represents one or more organizations associated with this Contact.
phoneNumbers of type array of ContactField, nullable
This attribute captures one or more phone numbers associated with this Contact.
photos of type array of ContactField, nullable
This attribute represents one or more photos associated with this Contact.
The photos must be specified in the value attribute of the ContactField object
by using a URL pointing to an image resource. The data: URI scheme may be used in order
to provide inline data.
This attribute should not be used to send down arbitrary photos taken by this user, but specifically profile photos of the contact suitable for display when describing the contact.
urls of type array of ContactField, nullable
This attribute represents one or more URLs associated with this Contact e.g. personal web page,
blog.
The web resources must be specified using the value attribute of the
ContactField object, and its type field may be set to "blog" or
"profile".
ContactName interface
The ContactName interface describes a contact's name.
[NoInterfaceObject]
interface ContactName {
attribute DOMString? formatted;
attribute DOMString? familyName;
attribute DOMString? givenName;
attribute DOMString? middleName;
attribute DOMString? honorificPrefix;
attribute DOMString? honorificSuffix;
};
familyName of type DOMString, nullable
This attribute contains the family name (also referred to as the last name) of this Contact.
formatted of type DOMString, nullable
This attribute contains the full name, including all the individual components such as
givenName, middleName, familyName, prefix,
suffix as appropriate for the user's culture, and formatted for display (e.g. Mr. Joe Smith
Jr).
givenName of type DOMString, nullable
This attribute contains the given name (also referred to as the first name) of this Contact.
honorificPrefix of type DOMString, nullable
This attribute contains the honorific prefix (or title) of this Contact. E.g. Mr., Dr., Ms.,
Mrs.
honorificSuffix of type DOMString, nullable
This attribute contains the honorific suffix of this Contact. E.g. Jr, III, Sr.
middleName of type DOMString, nullable
This attribute contains the middle name of this Contact.
ContactField interface
The ContactField interface is a reusable component that is used to capture contact fields of the
Contact interface that have some modicum of structure.
[NoInterfaceObject]
interface ContactField {
attribute DOMString type;
attribute DOMString? value;
attribute boolean pref;
};
pref of type boolean
This attribute indicates whether this instance of the ContactField is the
preferred, or primary, value for the contact property this ContactField is
representing in the Contact interface. By default, the value is false.
type of type DOMString
This attribute contains the type information for this ContactField and its content varies subject
to the contact property this ContactField is representing. For example, if the ContactField
is representing a phoneNumber property, the type attribute can be set to
home, mobile; if the ContactField is representing the ims
property, the type attribute could be set to xmpp, irc, bbm, etc.
value of type DOMString, nullable
This attribute contains the value for this ContactField and its content varies subject to the
contact property this ContactField is representing. For example, if the ContactField is
representing an email, the value attribute could be set to JoeSmith@example.com,
and if the ContactField is representing a url, the value attribute can be set to
http://www.example.org/joesmith, etc.
ContactAddress interface
The ContactAddress interface is a reusable component that is used to capture addresses
within the Contact interface.
[NoInterfaceObject]
interface ContactAddress {
attribute boolean pref;
attribute DOMString? type;
attribute DOMString? formatted;
attribute DOMString? streetAddress;
attribute DOMString? locality;
attribute DOMString? region;
attribute DOMString? postalCode;
attribute DOMString? country;
};
country of type DOMString, nullable
This attribute contains the country name corresponding to this ContactAddress.
formatted of type DOMString, nullable
This attribute contains the full physical address including street, locality,
region, postalCode, and country as appropriate, and formatted for
display.
locality of type DOMString, nullable
This attribute contains the locality (or city) name corresponding to this ContactAddress.
postalCode of type DOMString, nullable
This attribute contains the postal code (or zip) corresponding to this ContactAddress.
pref of type boolean
This attribute indicates whether this instance of the ContactAddress is the preferred, or primary, value for the contact.
By default, the value is false.
region of type DOMString, nullable
This attribute contains the region (or state/province) name corresponding to this ContactAddress.
streetAddress of type DOMString, nullable
This attribute contains the street address corresponding to this ContactAddress.
type of type DOMString, nullable
This attribute contains the type of address this object is representing (e.g. work, home, premises, etc).
ContactOrganization interface
The ContactOrganization interface is a reusable component that is used to support contact
organisations within the Contact interface.
[NoInterfaceObject]
interface ContactOrganization {
attribute boolean pref;
attribute DOMString? type;
attribute DOMString? name;
attribute DOMString? department;
attribute DOMString? title;
};
department of type DOMString, nullable
The department within which this Contact works.
name of type DOMString, nullableThe name of the organisation.
pref of type boolean
This attribute indicates whether this instance of the ContactOrganization is the preferred, or
primary, value for the contact. By default, the value is false.
title of type DOMString, nullable
The job title that the Contact holds inside this organisation.
type of type DOMString, nullableThis attribute contains the type of organization this object is representing.
ContactFindOptions interface
The ContactFindOptions interface describes the options that can be applied to contact searching.
When a ContactFindOptions parameter is provided to the Contacts find()
operation, it should be processed according to the provisions detailed in
Options Processing.
[NoInterfaceObject]
interface ContactFindOptions {
attribute DOMString? filter;
attribute boolean? multiple;
};
filter of type DOMString, nullablemultiple of type boolean, nullableContacts find() operation.
By default this option is set to false.
ContactFindCB interfaceThis is the wrapper interface for callbacks indicating success of the find() operation.
[Callback=FunctionOnly, NoInterfaceObject]
interface ContactFindCB {
void onsuccess (Contact[] contactObjs);
};
The following is the event handler attribute (and its corresponding event handler event
type) that must be supported as a DOM attribute by the ContactFindCB object.
| event handler attribute | event handler event type |
|---|---|
onsuccess |
success |
ContactErrorCB interfaceThis is the wrapper interface for callbacks indicating failure of the find() operation.
[Callback=FunctionOnly, NoInterfaceObject]
interface ContactErrorCB {
void onerror (ContactError error);
};
onerror| Parameter | Type | Nullable | Optional | Description |
|---|---|---|---|---|
| error | | ✘ | ✘ | The ContactError object capturing the type of the error. |
void
The following is the event handler attribute (and its corresponding event handler event
type) that must be supported as a DOM attribute by the ContactErrorCB object.
| event handler attribute | event handler event type |
|---|---|
onerror |
error |
ContactError interface
The ContactError interface encapsulates all errors in the manipulation of
Contact objects.
[NoInterfaceObject]
interface ContactError {
const unsigned short UNKNOWN_ERROR = 0;
const unsigned short INVALID_ARGUMENT_ERROR = 1;
const unsigned short TIMEOUT_ERROR = 2;
const unsigned short PENDING_OPERATION_ERROR = 3;
const unsigned short IO_ERROR = 4;
const unsigned short NOT_SUPPORTED_ERROR = 5;
const unsigned short PERMISSION_DENIED_ERROR = 20;
readonly attribute unsigned short code;
};
code of type unsigned short, readonlyINVALID_ARGUMENT_ERROR of type unsigned shortIO_ERROR of type unsigned shortNOT_SUPPORTED_ERROR of type unsigned shortPENDING_OPERATION_ERROR of type unsigned shortPERMISSION_DENIED_ERROR of type unsigned shortTIMEOUT_ERROR of type unsigned shortUNKNOWN_ERROR of type unsigned short
The Contacts find()
method provides an operation to search for one of more Contact objects within the Contacts database.
The search qualifier provides an application with a way to request the specific subset of
Contact properties it wishes to obtain in any resulting
successful callback. The search qualifier is deployed to minimize the data that needs to be
shared with an application in order to let that application fulfill its function on behalf of the user.
The search qualifier is included within a Contacts find() operation as
the fields parameter.
A search qualifier must be specified from a requesting application as a part of any Contacts find() operation.
If the search qualifier provided is of zero-length then the current Contacts find() operation and
the current find() operation was invoked with a non-null
errorCB parameter, then the user agent must invoke the errorCB function
with an error code of INVALID_ARGUMENT_ERROR.
In the case that the search qualifier provided is of non-zero-length then the
current Contacts find() operation must return only the matching Contact properties within any resulting Contact object(s).
If a provided search qualifier element (fields[x]) does not match a Contact attribute, fields[x] should be ignored when
executing the current Contacts find() operation.
We call composed attributes Contact
attributes of types object, which contain information only available
only through child attributes of that object, or array.
A requesting application must be able to request both the full composed Contact attribute and also be able to request individual parts
of a composed Contact attribute in the search
qualifier provided to a Contacts find() operation.
For example, the name attribute of a Contact object is defined to be of composed type ContactName. Therefore, a requesting application may
request either the full composed attribute (i.e. name) or specific individual attributes
of this composed attribute (i.e. name.formatted, name.familyName,
name.givenName, name.middleName, name.honorificPrefix,
name.honorificSuffix) as part of a Contacts find() operation's
search qualifier.
In the case that a composed Contact attribute is
defined as an array of composed objects, specific individual attributes can be referenced
by using the composed attribute name, a dot (.) character and the individual attribute
to be retrieved.
For example, the addresses attribute of Contact allows multiple ContactAddress objects to be defined. To request
individual attributes of this composed attribute an application would request e.g.
addresses.locality, addresses.region, etc.
The following Contact search is initiated:
navigator.contacts( ['emails.value', 'name', 'friends'],
function(contacts) {
for(i in contacts) {
for(j in contacts[i].emails)
alert(contacts[i].emails[j]);
}
} );
The above example logically implies:
Contact attributes
requested in the provided search qualifier (name, emails.value -
friends is not a valid Contact attribute
so ignore this element).
By default, the Contacts find() operation must return either an empty sequence or a single Contact object, accessible as part of the sequence returned in
the ContactFindCB callback function.
If a ContactFindOptions object is
provided to the Contacts find() operation and its multiple attribute is set to
true, the Contacts find() operation must return either an empty sequence, a single Contact object or [X] number of Contact objects, accessible as part of the sequence returned in
the ContactFindCB callback function.
A search filter may be specified from a requesting web application to provide a hint to the user agents as to which contacts the user can select to share with the application.
The search filter is defined through the filter
attribute of the ContactFindOptions object
provided to a Contacts find() operation.
The actual usage of this search filter is user-agent dependant, but is expected to represent the logical union of provided values that are matched therein.
The properties and parameters defined on the Contact
interface may be extended by implementors of this specification.
Non-standard, private properties and parameters should have a prefixed name starting with
X (U+0058 LATIN CAPITAL LETTER X) or use a vendor-specific prefix. Extended properties and
parameters can be defined bilaterally between user agents without outside
registration or standardization.
It is recommended that authors define both a formal vCard grammar and a WebIDL grammar for their proposed extension to ensure interoperability between vCard databases and other non-standard Contact databases and formats. It is also recommended that authors provide documentation of their extension properties and parameters within the public domain.
A new parameter is required by Company X to provide information related to a user's accounts registered across different networks and services.
The [WEBIDL] syntax for this parameter is defined as follows:
Contact implements ContactExtended;[NoInterfaceObject]
interface ContactExtended {
attribute ContactAccount[] Xaccounts;
};
Xaccounts of type array of ContactAccountaccounts].[NoInterfaceObject]
interface ContactAccount {
attribute DOMString domain;
attribute DOMString username;
attribute DOMString userid;
};
domain of type DOMString
See [[POCO-SCHEMA] Section 7.6. domain].
userid of type DOMString
See [[POCO-SCHEMA] Section 7.6. userid].
username of type DOMString
See [[POCO-SCHEMA] Section 7.6. username].
The corresponding vCard [RFC2426] notation for this parameter is defined as follows:
The following ABNF grammar extends the grammar found in [RFC2426] (Section 4). X-ACCOUNT Purpose: To specify the components of the accounts for the vCard object. Value type: A single structured text value, separated by the SEMI- COLON character (ASCII decimal 59). Cardinality: (0,n) Special notes: The structured type value consists of a sequence of account components. The component values must be specified in their corresponding position. The structured type value corresponds, in sequence, to the domain; the username; the userid. When a component value is missing, the associated component separator must still be specified. The text components are separated by the SEMI-COLON character (ASCII decimal 59). ABNF: X-ACCOUNT-param = ; no parameter allowed X-ACCOUNT-value = list-component 3(";" list-component)
This parameter will be used within the Contacts API as follows:
var contact = ...; // ...obtain individual contact object for(var i in contact.Xaccounts) { alert(contact.Xaccounts[i].domain); // thesocialnetwork.com alert(contact.Xaccounts[i].username); // null alert(contact.Xaccounts[i].userid); // 344aesq2 }
This parameter will be used within the vCard format [RFC2426]] as follows:
X-ACCOUNT;thesocialnetwork.com;;344aesq2
The API contained in this document can be invoked either programmatically (for example, inline within a general script) or resulting from the interaction of a user.
The interaction of a user is when a user invokes the API from an HTMLElement [HTML5] within the current
browsing context via a valid auto-invocation event.
A valid auto-invocation event includes any of the following event types, as defined in [DOM-LEVEL-3-EVENTS]:
clickdblclickmouseup
The find() method on Contacts should, if
the method was invoked by an interaction of a user (as opposed to having been created and executed
in general script), display the Contact Picker directly.
This section is non-normative.
This specification is primarily intended to provide the user with the ability to view and control the contact information that may be shared from their unified address book. This annex provides some examples of a conformant user experience that this specification enables.
A website requests access to a user's address book with the following code:
<script type="text/javascript"> function successContactFindCallback(contacts) { // do something with resulting contact objects for (var i in contacts) alert(contacts[i].name); // ... } function generalErrorCB(error) { // do something with resulting errors alert(error.code); // ... } // Perform an address book search. Obtain the 'name' and 'emails' properties // and initially filter the list to Contact records containing 'Bob': navigator.contacts.find(['name', 'emails'], successContactFindCallback, generalErrorCB, {filter: 'Bob'} ); </script>
As a result of executing this code, the user agent may provide a non-blocking contact search notification as follows:
If an additional find() operation is called by the current web application before the user has
clicked 'Select' or 'Cancel' on the current notification, an error will be invoked with a code of
PENDING_OPERATION_ERROR if that
operation was defined with a non-null errorCB parameter.
If the user clicks 'Cancel', the errorCB, if non-null for the current
find() operation, will be invoked with an error code of PERMISSION_DENIED_ERROR.
If the user clicks 'Select', the user agent may provide a contact picker, utilizing all of the parameters provided in the find() operation as follows:
In this dialog, the user is provided with a summary of the sharing that the application is requesting and the option to select one or more contacts (as appropriate) from the user interface.
If an additional find() operation is called by the current web application before the user has
clicked 'Select' or 'Cancel' on the current notification, an error will be invoked with a code of
PENDING_OPERATION_ERROR if that
operation was defined with a non-null errorCB parameter.
If the user clicks 'Cancel', the errorCB, if non-null for the current
find() operation, will be invoked with an error code of PERMISSION_DENIED_ERROR.
If the user clicks 'Select', the ContactFindCB
associated to the current find() operation will be invoked with the contact information selected by the
user provided as the only parameter.
Further to this initial sharing of Contact information, the Security and Privacy Considerations section expects that the user should easily be able to review and revoke access that web applications have to this API at a later time.
A website requests access to a user's address book with the following code:
<input type="button" value="Share Contacts" onclick="getContacts()" /> <script type="text/javascript"> function successContactFindCallback(contacts) { // do something with resulting contact objects for (var i in contacts) alert(contacts[i].name); // ... } function generalErrorCB(error) { // do something with resulting errors alert(error.code); // ... } function getContacts() { // Perform an address book search. Obtain the 'name' and 'emails' properties // and initially filter the list to Contact records containing 'Bob': navigator.contacts( ['name', 'emails'], successContactFindCallback, generalErrorCB, { filter: 'Bob' } ); // is equivalent to: navigator.contacts.find(/* parameters */); } </script>
This code may render as follows within the user agent:
If the user clicks on the rendered button element then the user agent may directly provide a
contact picker, as defined in API Invocation via
DOM Events, utilizing all of the parameters provided in the find() operation as
follows:
In this dialog, the user is provided with a summary of the sharing that the application is requesting and the option to select one or more contacts (as appropriate) from the user interface.
If an additional find() operation is called by the current web application before the user has
clicked 'Select' or 'Cancel' on the current notification, an error will be invoked with a code of
PENDING_OPERATION_ERROR if that
operation was defined with a non-null errorCB parameter.
If the user clicks 'Cancel', the errorCB, if non-null for the current
find() operation, will be invoked with an error code of PERMISSION_DENIED_ERROR.
If the user clicks 'Select', the ContactFindCB
associated to the current find() operation will be invoked with the contact information selected by the
user provided as the only parameter.
Further to this initial sharing of Contact information, the Security and Privacy Considerations section expects that the user should easily be able to review and revoke access that web applications have to this API at a later time.
This section is non-normative.
The ability to add and update contact information is not a function of the API provided in this specification. Instead, the intention is to reuse existing web platform APIs and paradigms in order to acheive add and update functionality.
In this section we show how the existing web platform would be used to provide add and update writeback functionality to allow users to add new contacts or update existing contacts from a web page to their unified address book.
A valid Contact resource is a web resource with a .vcard or .vcf
filename extension or a web resource with a MIME-type matching a valid media type. A vCard
object is a text-based representation of contact information provided according to any version of
the vCard family of specifications.
Need to add informative references to all specs within the 'vCard family of specifications'.
To handle the saving of a new Contact, a user agent should register as the default handler for any valid Contact resource.
A valid media type will be one of the following web resource MIME types:
text/vcardtext/x-vcardtext/directorytext/directory;profile=vCardOn invocation of a valid Contact resource, the user agent should, on successful download of the valid Contact resource, store the given resource in the user's unified address book according to the rule for storing a Contact resource. As part of this standard download process, the user agent may present a dialog to the user allowing them to select a different application with which to handle the given resource, thereby overriding the use of the unified address book for the storage of the data contained therein and bypassing the rule for storing a Contact resource.
The rule for storing a Contact resource is defined as follows:
Let Contact be the parsed key/value pairs contained in the valid Contact resource.
UID key then process the valid Contact
resource as follows.
UID provided.null) then update the contents of MatchedContact with the contents of
Contact and exit this rule.As part of the rule for storing a Contact resource, the user agent may provide additional dialogs to the user after successful completion of the download and before the Contact information is saved to the unified address book, such as to show a preview of the Contact information contained therein as it will be stored in the user's unified address book. The user may be able to override the information provided before accepting the additions and permanently storing the given data in their unified address book.
This section is non-normative.
A web page can dynamically generate a vCard object on the client side for download to the user's unified address book via either data: URIs [RFC2397] or using the [FILE-WRITER] and [FILE-API] interfaces. The following examples show two methods for creating a vCard object dynamically and then presenting this to the user. The user may then save this information by clicking on the presented information, download the dynamically generated vCard object and invoke a suitable application with which to handle the dynamic resource.
<a id="vcard">Save our Contact Details</a> <script type="text/javascript"> var vcard = 'BEGIN:VCARD\r\n' + 'VERSION:2.1\r\n' + 'N:Doe;John\r\n' + 'FN:John Doe\r\n' + 'TEL;WORK;VOICE:123456\r\n' + 'END:VCARD'; // assign vCard as a Data URI to an anchor element for presentation and download by the user document.getElementById('vcard').href = "data:text/x-vcard;charset=utf-8," + encodeURIComponent( vcard ); </script>
<a id="vcard">Save our Contact Details</a> <script type="text/javascript"> // obtain an ArrayBuffer consisting of valid vCard syntax (out of scope) var vCardObj = getVCard( /* ... */ ); // create a new vCard Blob [FILE-WRITER] var contactBlobBuilder = new BlobBuilder(); contactBlobBuilder.append( vCardObj ); var contactBlob = contactBlobBuilder.getBlob( "text/x-vcard" ); // obtain a vCard Blob URL [FILE-API] var contactBlobURL = window.URL.createObjectUrl( contactBlob ); // assign vCard Blob URL to an anchor element for presentation and download by the user document.getElementById('vcard').href = contactBlobURL; </script>
This section is non-normative.
To update an existing Contact, the user must have already shared the contact information to edit
with the current web page via the find() operation of the Contacts interface. This section assumes that the user is
already sharing some contact information with the current web page via this process.
If this existing Contact information is to be updated in the user's unified address book then the
developer will assign the id attribute, as returned in the Contact object, as
the UID property of any resulting vCard object to be processed by the user
agent according to the rule for storing a Contact resource.
The examples below show two methods for updating an existing Contact in the user's unified address book by maintaining a valid UID property while changing other parameters of the Contact card. The user is then required to click on the resulting anchor element to download the modified Contact resource.
<a id="vcard">Save our Contact Details</a> <script type="text/javascript"> // Obtain a single existing Contact object resulting from navigator.contacts.find() var existingContactObj = ...; var vcard = 'BEGIN:VCARD\r\n' + 'VERSION:3.0\r\n' + 'UID:' + existingContactObj.id + '\r\n' + // assign the Contact.id to a UID property 'N:Doe;John\r\n' + 'FN:John Doe\r\n' + 'TEL;HOME;VOICE:654321\r\n' + 'END:VCARD'; // assign vCard as a Data URI to an anchor element for presentation and download by the user document.getElementById('vcard').href = "data:text/x-vcard;charset=utf-8," + encodeURIComponent( vcard ); </script>
<a id="vcard">Update our Contact Details</a> <script type="text/javascript"> // Obtain a single existing Contact object resulting from navigator.contacts.find() var existingContactObj = ...; // Modify some parameters as required. e.g. add a new phone number existingContactObj.phoneNumbers.push({ type: 'home', value: '654321' }); // With the existing Contact object, create an ArrayBuffer consisting of valid vCard // syntax (out of scope) making sure to set the resulting vCard UID property to // the id parameter returned in the existing Contact object var vCardObj = getVCard( existingContactObj ); // create a new vCard Blob [FILE-WRITER] var contactBlobBuilder = new BlobBuilder(); contactBlobBuilder.append( vCardObj ); var contactBlob = contactBlobBuilder.getBlob( "text/x-vcard" ); // obtain a vCard Blob URL [FILE-API] var contactBlobURL = window.URL.createObjectUrl( contactBlob ); // assign vCard Blob URL to an anchor element for presentation and download by the user document.getElementById('vcard').href = contactBlobURL; </script>