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.

Publication as a Working Group Note 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.

The email address provided for feedback is that of the Task Force, where all feedback is welcome.

Changes since the previous version include clarifications, corrections, and updates to the document ( diff ).

This document was produced by the Web Intents Task Force , a joint activity of the Device APIs Working Group and the Web Applications Working Group The Working Groups have not performed interop testing on the material in this document. Implementers are cautioned that this material is subject to change and that an alternative design may be pursued in the future.

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/.

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

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.

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:

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.

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.

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.

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:

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.

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:

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.

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.

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.

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.

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.

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.

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

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

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

Registration is how a web page page informs the User Agent that it (or another same-origin Service page) is capable of handling 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.)

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.

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

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. IntentParameters { DOMString action DOMString type any? data sequence< Transferable >? transfer URL? service sequence< URL >? suggestions dictionary}; 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 The data payload used MUST be an object upon which the structured clone algorithm can be performed, including Transferables. service of type URL When present, this field marks the intent as an explicit intent. The value MUST be an absolute URL. suggestions of type sequence< URL 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 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 { DOMString action readonly attribute DOMString type readonly attribute any data readonly attribute MessagePort [] ports readonly attribute void postResult any data sequence< Transferable transferable optional ); void postFailure any data ); ] interface}; 3.2.1 Attributes action of type DOMString 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 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 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 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. 3.2.2 Methods postFailure Only present when the Intent object is delivered to the Service page. The payload passed to this method will be returned to the onFailure callback registered by the client page in the startActivity call (if any). The playload must be an object upon which the structured clone algorithm can be performed, including Transferables. [ HTML5 ] Parameter Type Nullable Optional Description data any ✘ ✘ void Return type: postResult Only present when the Intent object is delivered to the Service page. The payload passed to this method will be returned to the onSuccess callback registered by the client page in the startActivity call (if any). The payload must be an object upon which the structured clone algorithm can be performed. The Transferables array, if present, will specify transferable elements in the data payload argument, as per [ HTML5 ] [ POSTMSG ] Parameter Type Nullable Optional Description data any ✘ ✘ transferable sequence<Transferable> ✘ ✔ void Return type: 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 IntentSuccessCallback onSuccess optional IntentFailureCallback onFailure optional ); ] interface}; 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. Parameter Type Nullable Optional Description intent Intent ✘ ✘ onSuccess IntentSuccessCallback ✘ ✔ onFailure IntentFailureCallback ✘ ✔ void Return type: 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: IntentSuccessCallback = void any data optional MessagePort [] ports optional callback); 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 ] IntentFailureCallback = void any data optional callback); 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 { Intent intent readonly attribute ] interface}; 3.4.1 Attributes intent of type Intent The intent object as delivered to the service page (includes postResult and postFailure methods). Window implements IntentProvider All instances of the Window type are defined to also implement the IntentProvider interface. This object will only be made available to Service pages when they are loaded in the context of an intent invocation. Even if the same URL is loaded in other situations, the User Agent MUST NOT make Window implement IntentProvider . Similarly, if a Service page is registered, but the User Agent loads it and it does not contain the declarative markup marking it as expecting to handle the Intent the User Agent is delivering, the User Agent MUST NOT make Window implement IntentProvider . The window.intent object MUST be made available across same-origin redirects of the service page. It MUST NOT be made available if redirects cross an origin boundary. So the following redirect sequence will work: http://example.com/service to http://example.com/login back to http://example.com/service. In this case, the window.intent data would be made available to all three page loads. This will also work: http://example.com/service to http://example.com/newservice. In this sequence, the window.intent data is available to both pages. In this sequence, the window.intent is only available to example.com pages: http://example.com/service to http://login.example.com and back to http://example.com/service. The intent data is not provided to http://login.example.com The window.intent object MUST be made available to a page on the same-origin as the originally-delivered page if the user initiates a navigation on the browsing context in which that Service page is displayed, AND the new page has declarative syntax marking it as a handler for the Intent type the User Agent is delivering. In other words, in the browsing context in which the Intent is originally delivered, the intent data MUST be made available to pages in a redirect or navigation sequence when they are in the same origin as that to which it was originally delivered (and have the enabling markup), but MUST NOT be made available to any other pages. This allows Service pages to delegate handling, to redirect to login screens, and so forth, but does not make the Intent data available to any such pages encountered which are not in the same origin. Multiple invocation by code in the service page MUST throw a Javascript exception. The User Agent MUST NOT allow a particular Intent to be replied to multiple times.