spacer

Web Intents

W3C Editor's Draft 11 September 2012

This version:
https://dvcs.w3.org/hg/web-intents/raw-file/tip/spec/Overview-respec.html
Latest published version:
www.w3.org/TR/web-intents/
Latest editor's draft:
https://dvcs.w3.org/hg/web-intents/raw-file/tip/spec/Overview-respec.html
Editors:
Greg Billock, Google
James Hawkins, Google
Paul Kinlan, Google

Copyright © 2011-2012 W3C® (MIT, ERCIM, Keio), All Rights Reserved. W3C liability, trademark and document use rules apply.


Abstract

This specification defines a service discovery and light-weight RPC mechanism for web apps called Web Intents.

This document defines DOM interfaces and markup used by client and service pages to create, receive, and reply to Web Intents messages, and the procedures the User Agent carries out to facilitate that process.

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 www.w3.org/TR/.

This document is produced by a the Web Intents Task Force, which is jointly operated by the DAP and WebApps Working Groups. The email address provided for feedback is that of the Task Force, where all feedback is welcome.

This document was published by the Device Applications (DAP) Working Group and Web Applications (WebApps) Working Group as an Editor's Draft. If you wish to make comments regarding this document, please send them to public-web-intents@w3.org (subscribe, archives). All feedback is 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 (Device Applications (DAP) Working Group, Web Applications (WebApps) Working Group) 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

Web Intents enable rich integration between web applications. Increasingly, services available on the web have a need to pass rich data back and forth as they do their jobs. Web Intents facilitate this interchange while maintaining the kind of loose coupling and open architecture that has proven so advantageous for the web. They exist purely client-side, mediated through the User Agent, allowing the user a great degree of control over the security and privacy of the exchanged data.

An Intent is a user-initiated action delegated to be performed by a service. It consists of an "action" string which tells the service what kind of activity the user expects to be performed (e.g. "share" or "edit"), a "type" string which specifies the data payload the service should expect, and the data payload itself.

The lifecycle of an Intent is that first, a client requests an Intent be handled. This Intent data is then passed to the User Agent, which allows the user to select which of potentially many possible services to use. Then the service is passed the Intent data and is provided a UI by the User Agent in which to perform the action specified in the Intent. Finally, the service may also return data as output back to the client.

Web Intents provides a declarative syntax that allows services to list the Intents they handle. Using this method, services mark up what actions they can handle and which data types they expect.

1.1 Example

Suppose there is a photo hosting application. This application allows a user to select images to be shared, edit those images, and then share them with friends. The application is built around making photos available to users, but has no built-in editor or sharing interface. But beside each photo, it can place an Edit button, with this kind of accompanying code:

Example 1
document.getElementById('edit-photo').addEventListener("click", function() {
  var intent = new Intent({"action":"webintents.org/edit",
                           "type":"image/jpeg",
                           "data":getImageDataBlob(...)});
  navigator.startActivity(intent, imageEdited);
}, false);

function imageEdited(data) {
  document.getElementById('image').src = data;
}

This code delegates image editing to third-party applications which can consume images prepared as blobs, and produce results in the same format. For instance, one such editor might be a meme-maker—an application allowing the user to place humorous messages on pictures they take.

Now that a picture has been edited in the selected service, and meme text added, the user undoubtedly wants to share the result with friends. Again, the photo hosting application may not have built-in sharing capabilities, but by adding a Share button near images, and with this kind of accompanying code, it can accomplish this integration:

Example 2
document.getElementById('share-photo').addEventListener("click", function() {
  var intent = new Intent({"action":"webintents.org/share",
                           "type":"text/uri-list",
                           "data":getPublicURIForImage(...)});
  navigator.startActivity(intent);
}, false);

This code delegates sharing functionality to an existing services chosen by the user which are capable of sharing urls. (getPublicURIForImage() is a marker for an application-specific piece of functionality getting the URL to be shared) So a social networking site selected by the user might produce a status update with a thumbnail of the image. A blogging site might provide a UI allowing the user to post the picture.

Note that with this integration, other more high-minded services can be selected by the user as well. Instead of using the service to add funny captions, the user might use a sophisticated photo editing application to adjust exposure, remove red-eye, or do any number of other transformations on the image. The user can have many such tools registered, and choose any of that set to use for any given image editing task. The photo hosting application isn't controlling which application the user chooses; it is loosely coupled with such applications by providing the data necessary for them to carry out their task, and controls allowing the user to launch these activities on the data.

In this way, an Intent is like the dual of a hyperlink. With a hyperlink, the source page specifies the exact URL to be navigated to. With an Intent, the source page specifies the nature of the task to be done, and the user can select any of a number of applications to be used to complete the task.

On the service side, the page needs to register itself as a Web Intents service, and handle the incoming intent data, possibly producing a response. That is done like this:

Example 3
<html>
<head>
<title>Image Meme Editor</title>
</head>
<body>
<intent action="webintents.org/edit" type="text/uri-list image/*"></intent>
<script>
  window.addEventListener("load", function() {
    if (window.intent) {
      setImageContentURI(window.intent.data);
    }
  }, false);

  document.getElementById('save-button').addEventListener("click", function() {
    window.intent.postResult(getImageDataURI(...));
  }, false);
</script>

The assumed pieces here (on both client and service pages) are functions which deal with the application's image display, for instance putting the image into a canvas and taking it back out again as a data URI. Or producing the public URI of the image on the site.

1.2 Normative parts

The normative parts of this specification are the API Description and the User Agent Behavior section. All other parts are informative.

2. Terminology

An Intent is an action with accompanying data, which is to be performed by a Service of the user's choosing.

2.1 Actors

A web page which creates an Intent and invokes the User Agent with it is a Client. The User Agent may also allow non-web-page sources invoke Intents. For instance, the User Agent may have UI which invokes Intents delivery, or may register for external OS hooks which trigger Intents.

A web page which can handle an Intent is a Service, possibly returning a piece of data to the calling Client page. (Note that the User Agent may have ways to deliver Intents to Services which are not web pages as well. These may be extension APIs, plug-in helpers, external OS handlers, etc.)

2.2 Life cycle of Intents and Services

Registration is how a web page page informs the User Agent that it (or another same-origin Service page) is capable of handling Intents.

Invocation refers to the API by which a Client page dispatches an Intent for handling.

Selection is the mechanism in which the User Agent decides which Service will handle a particular Intent.

Delivery is the means by which the User Agent passes an Intent to a Service page for handling.

Response is the means in which the Service can respond to an Intent by passing data back through the User Agent to the Client page.

The steps in a particular Intent invocation are asynchronous. The Service receives the Intent delivery and prepares its Response in a separate execution context. That Response is then returned to the calling Client in an asynchronous callback.

3. API Description

3.1 Intent parameters dictionary

This object can be used in the object-literal constructor of the Intent object. When using the object literal constructor, the action and type fields are required; all others are optional.

dictionary IntentParameters {
    DOMString               action;
    DOMString               type;
    any?                    data;
    sequence<Transferable>? transfer;
    URL?                    service;
    sequence<URL>?          suggestions;
};

3.1.1 Dictionary IntentParameters Members

action of type DOMString
An opaque string indicating the action type of the intent. The string must not be empty.
data of type any, nullable
The data payload used must be an object upon which the structured clone algorithm can be performed, including Transferables.
service of type URL, nullable
When present, this field marks the intent as an explicit intent. The value must be an absolute URL.
suggestions of type sequence<URL>, nullable
When present, this field provides a list of suggested Service URLs, each of which is an absolute URL that the Client is aware of and which can handle the intent.
transfer of type sequence<Transferable>, nullable
The list of Transferables, for use in the structured clone algorithm.
type of type DOMString
A string indicating the type of the data payload. The data payload must be described by this parameter, which must not be empty.

3.2 Intent object

The Intent object models a particular task which can be requested to be handled by Services. A Client page may invoke multiple Intents simultaneously. Specific Intent objects are immutable once created.

[Constructor(IntentParameters params),
Constructor(DOMString action, DOMString type, optional any data, optional sequence<Transferable> transferList)
] interface Intent { readonly attribute
DOMString action; readonly attribute DOMString type; readonly attribute any data; readonly attribute MessagePort[] ports; void postResult (any data, optional sequence<Transferable> transferable); void postFailure (any data); };

3.2.1 Attributes

action of type DOMString, readonly
This is an opaque string. Chosen strings should be namespaced by a URL namespace convention. The string must not be empty, or the constructor must throw an exception.
data of type any, readonly
The object used must be an object upon which the structured clone algorithm can be performed, including Transferables, or the constructor must throw an exception.
ports of type array of MessagePort, readonly
Only present when the Intent object is delivered to the Service page. Any ports used in the transferList of the constructor during invocation will be delivered to the service page in the ports attribute. See [POSTMSG]
type of type DOMString, readonly
The data payload must be described by the type parameter. Recommended type strings are MIME strings or self-documenting urls. The string must not be empty, or the constructor must throw an exception.

Notes on the intent object: The transferList parameter is not available post-creation. It becomes an internal implementation detail directing the User Agent to interpret some fields of the data argument as Transferable. The data and transferList arguments must be implemented following the W3C Web Messaging spec [POSTMSG].

The User Agent must perform the structured clone algorithm on creation of the Intent object.

3.3 Invocation API

The client invokes an intent by constructing an Intent object as above and calling the navigator.startActivity function on it. The callbacks passed to this method are invoked when the intent has been handled by the service. The User Agent will mediate the Service selection by enumerating the list of registered Services that match the requested Intent action and type. The user is then able to select which Service should handle the Intent.

[NoInterfaceObject]
interface Intents {
    void startActivity (Intent intent, optional IntentSuccessCallback onSuccess, optional optional IntentFailureCallback onFailure);
};

3.3.1 Methods

startActivity
Called to invoke an intent Service. The Intent object is described above. The onSuccess handler, if any, will be called by the user agent if the service is dispatched, processes the intent, and calls postResult on the Intent object it receives. The handler will be invoked with one parameter: the data received from the service. The onFailure handler, if any, will be called by the user agent if the service cannot be dispatched, if the user aborts the selection process, or if a service was chosen, received the intent, processes the intent, and calls postFailure on the Intent object it receives. The handler will be invoked with one parameter: the data received from the service. User Agents should restrict this method to only be successfully callable within the context of an explicit user gesture. An exception should be thrown if the Intent is invalid (i.e. null), or if the method is invoked without being the result of an explicit user gesture.
ParameterTypeNullableOptionalDescription
intentIntent
onSuccessIntentSuccessCallback
onFailureoptional IntentFailureCallback

The invocation API is implemented by the window.navigator object.

Navigator implements Intents;

All instances of the Navigator type are defined to also implement the Intents interface.

The callbacks passed to startActivity must provide these signatures:

callback IntentSuccessCallback = void (optional any data, optional MessagePort[] ports);
Callback IntentSuccessCallback Parameters
data of type any
The data passed will be the payload data from the structured cloneable object passed to the postResult method of the delivered Intent.
ports of type array of MessagePort
The ports will be any ports in the payload, as resulting from the structured clone algorithm with Transferables, as in the Web Messaging spec. [POSTMSG]
callback IntentFailureCallback = void (optional any data);
Callback IntentFailureCallback Parameters
data of type any
The data passed will be the payload data passed to the postFailure method of the delivered Intent.

3.4 Delivery and Response API

When the User Agent loads a Service page to handle an Intent invocation, it will place a window.intent object in the scope of the page.

[NoInterfaceObject]
interface IntentProvider {
    readonly attribute Intent intent;
};

3.4.1 Attributes

intent of type