W3C

Pick Contacts Intent

W3C Working Draft 12 July 2012

This version:
http://www.w3.org/TR/2012/WD-contacts-api-20120712/
Latest published version:
http://www.w3.org/TR/contacts-api/
Latest editor's draft:
http://w3c-test.org/dap/contacts/
Previous version:
http://www.w3.org/TR/2011/WD-contacts-api-20110616/
Editors:
Richard Tibbett, Opera Software ASA
Robin Berjon, Robineko

Abstract

The Pick Contacts Intent defines a Web Intent [WEBINTENTS] that enables access to a user's address book service from inside a Web application. It defines both an Intent action/type pair that selects this operation, and the format of the contacts data that is returned by services implementing this specification

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 builds atop previous versions that were pure JavaScript APIs and turns them into an API built using Web Intents, while maintaining the data format which the JavaScript APIs had defined.

This document was published by the Device APIs Working Group as a 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). 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 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.

Table of Contents

1. Introduction

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 disjoint 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. When sharing of only a subset of a user's address book is possible, it often requires the user to type the information into a form herself rather than having it extracted from one of her address book services.

This specification enables a Web application to have access to a selected subset of a user's address book, obtained from arbitrary services not known to the Web application. The interactions, brokered using Web Intents [WEBINTENTS] are designed in order to maximise the user's security and privacy. Address book data may be sourced from a plurality of sources — both online and local to the user's device — so long as those sources are registered as Intent services with the user agent. It defines a common format which services use to provide data to Web applications in a consistent and interoperable manner.

The expectation is that data sharing happens 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 implementers of Pick Contacts Intent services and recipients of contact information (i.e. Web applications).

The following code illustrates how to obtain contact information from a user's address book:

Example 1
var intent = new Intent({ action:   "http://webintents.org/pick",
                          type:     "http://w3.org/type/contact",
                          extras:   { fields: ["displayName", "emails"] }});
navigator.startActivity(intent, contactsOK, contactsFail);

function contactsOK (contacts) {
    // iterate over the array of contacts to do something useful with them
}
function contactsFail (err) {
    // display an error to the user
}

When the above code is run, the user would typically be prompted by her user agent to select a service able to pick a contact (there may be several such services, if she has multiple address book sources). Upon selecting a service, she will be presented with an interface enabling her to choose what contact information is returned to the Web application. Upon completing her choice, the contacts data would be returned to the Web application in the contactsOK callback.

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 words must, must not, required, should, should not, recommended, may, and optional in this specification are to be interpreted as described in [RFC2119].

There is only one single conformance requirement placed upon the user agent product: a user agent must support Web Intents [WEBINTENTS].

The conformance criteria in this specification apply to a single product: the contact service which exposes a Web Intent service that handles Pick Contact Intents as defined in this specification.

The data returned by the contact service is described in this specification using [WEBIDL]. When this data is provided using JavaScript, then the contact service must do so in a manner consistent with the ECMAScript Bindings defined in the Web IDL specification.

3. Security and Privacy Considerations

This section is non-normative.

The Intent 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 should 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.

3.1 Privacy considerations for implementers of the Pick Contacts Intent

This section is non-normative.

A contact service should not provide contact information to Web sites without the express permission of the user. Obtaining the user's express permission to access a set of contacts does not imply that the user has granted permission for the same Web site to access more contact information. A contact service should take great care to ensure that the user can clearly see which information is about to be shared, and must not share more information than has been requested by the Web application.

A user agent may have prearranged trust relationships with a specific contact service that do not require such user interaction.

3.2 Privacy considerations for recipients of contact information

Web sites operators that retrieve contacts information using this Intent 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 of 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 applications when requesting and using such information.

3.3 Additional implementation considerations

Further to the requirements listed in the previous section, implementers of a user agents 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 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 a user agent's responsibility and not prescribed by this specification. However, in designing these measures, implementers are advised to enable user awareness of information sharing, and to provide easy access to user interfaces that enable revocation of permissions that Web applications have to access this Intent.

4. Intent Description

The action for this Intent is http://webintents.org/pick.

The type for this Intent is http://w3.org/type/contact.

When a contact service is matched for delivery using these action and type, it must respond in one of two ways:

4.1 Intent Extras

The Pick Contact Intent can be instantiated with an extras field that adheres to the following dictionary.

4.1.1 The ContactIntentExtras dictionary

The ContactIntentExtras dictionary describes the options that can be applied to contact searching.

dictionary ContactIntentExtras {
    DOMString?     search;
    unsigned long? limit;
    DOMString[]    fields;
};
4.1.1.1 Dictionary ContactIntentExtras Members
fields of type array of DOMString
An array of field names corresponding to the name of the fields in the Contact dictionary that the Web application is requesting from the contact service. The contact service must not return defined fields on the contact objects that it provides other than those present in this list. If a field name is provided that the contact service does not recognise as a field of the Contact dictionary, then it must ignore it.
limit of type unsigned long, nullable
By default a contact service may return as many contacts as the user selects. If limit is specified, the contact service must not return more than limit contacts. The contact service should enforce this limitation in the user interface that it exposes.
A string which provides a hint to the contact service to facilitate contacts selection by the user. The exact manner in which this hint is exploited is entirely up to the contact service.

5. Data Format

Upon successful invocation, the contact service must return an array of Contact dictionaries.

5.1 The Contact dictionary

The Contact dictionary captures the properties of a contact object. All properties included in this interface have a corresponding definition in [POCO-SCHEMA], [RFC2426] (also known as vCard), and [OMA-CAB], thereby allowing the data format to be supported across implementations supporting these various contact representations.

Additional attributes may be included according to the provisions detailed in Extended Contact Properties and Parameters.

dictionary Contact {
    DOMString              id;
    DOMString?             displayName;
    ContactName?           name;
    DOMString?             nickname;
    ContactField[]?        phoneNumbers;
    ContactField[]?        emails;
    ContactAddress[]?      addresses;
    ContactField[]?        ims;
    ContactOrganization[]? organizations;
    Date?                  birthday;
    DOMString?             note;
    ContactField[]?        photos;
    DOMString[]?           categories;
    ContactField[]?        urls;
};

5.1.1 Dictionary Contact Members

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 contact service may set the year value 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
A globally unique identifier for the given Contact object.
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 dictionary.
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 organisations 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.

Note

A contact service should not use this attribute 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.

5.2 The ContactName dictionary

The ContactName dictionary describes a contact's name in detail.

dictionary ContactName {
    DOMString? familyName;
    DOMString? givenName;
    DOMString? middleName;
    DOMString? honorificPrefix;
    DOMString? honorificSuffix;
};

5.2.1 Dictionary ContactName Members

familyName of type DOMString, nullable
This attribute contains the family name (also referred to as the last name) of this Contact.
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.

5.3 The ContactField dictionary

The ContactField dictionary is a reusable component that is used to capture contact fields of the Contact dictionary that have some modicum of structure.

dictionary ContactField {
    DOMString  type;
    DOMString? value;
    boolean    pref;
};

5.3.1 Dictionary ContactField Members

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.

5.4 The ContactAddress dictionary

The ContactAddress dictionary is a reusable component that is used to capture addresses within the Contact dictionary.

dictionary ContactAddress {
    boolean    pref;
    DOMString? type;
    DOMString? streetAddress;
    DOMString? locality;
    DOMString? region;
    DOMString? postalCode;
    DOMString? country;
};

5.4.1 Dictionary ContactAddress Members

country of type DOMString, nullable
This attribute contains the country name corresponding to this ContactAddress.
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).

5.5 The ContactOrganization dictionary

The ContactOrganization dictionary is a reusable component that is used to support contact organisations within the Contact dictionary.

dictionary ContactOrganization {
    boolean    pref;
    DOMString? type;
    DOMString? name;
    DOMString? department;
    DOMString? title;
};

5.5.1 Dictionary ContactOrganization Members

department of type DOMString, nullable
The department within which this Contact works.
name of type DOMString, nullable
The 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, nullable
This attribute contains the type of organisation this object is representing.

5.6 The ContactError dictionary

If the contact service encounters an error then it must return an error (through postFailure()) using the ContactError dictionary.

dictionary ContactError {
    DOMString message;
};

5.6.1 Dictionary ContactError Members

message of type DOMString
A message describing the error.

5.7 Extended Contact Properties and Parameters

A contact service may extend the dictionaries described in in the Data Formats section with additional fields. If providing an extended field, a contact service must prefix its name with X (U+0058 LATIN CAPITAL LETTER X) or use a vendor-specific prefix.

A. References

A.1 Normative references

[RFC2119]
S. Bradner. Key words for use in RFCs to Indicate Requirement Levels. March 1997. Internet RFC 2119. URL: http://www.ietf.org/rfc/rfc2119.txt
[WEBIDL]
Cameron McCormack. Web IDL. 27 September 2011. W3C Working Draft. (Work in progress.) URL: http://www.w3.org/TR/2011/WD-WebIDL-20110927/
[WEBINTENTS]
Greg Billock; James Hawkins; Paul Kinlan. Web Intents. Editors' Draft. (Work in progress.) URL: http://dvcs.w3.org/hg/web-intents/raw-file/tip/spec/Overview.html

A.2 Informative references

[OMA-CAB]
Converged Address Book Enabler, Version 1.0, Open Mobile Alliance, URL: http://www.openmobilealliance.org/
[POCO-SCHEMA]
Joseph Smarr. Portable Contacts 1.0 Draft C: Contact Schema 5 August 2008. URL: http://portablecontacts.net/draft-spec.html#schema
[RFC2426]
F. Dawson, T. Howes. vCard MIME Directory Profile. September 1998. URL: http://www.ietf.org/rfc/rfc2426.txt