Copyright © 2011-2012 W3C® (MIT, ERCIM, Keio), All Rights Reserved. W3C liability, trademark and document use rules apply.
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.
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 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 a First Public 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-web-intents@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 (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.
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.
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:
document.getElementById('edit-photo').addEventListener("click", function() { var intent = new Intent({"action":"http://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:
document.getElementById('share-photo').addEventListener("click", function() { var intent = new Intent({"action":"http://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:
<html> <head> <title>Image Meme Editor</title> </head> <body> <intent action="http://webintents.org/edit" type="text/uri-list;type=image/*,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.
The normative parts of this specification are the API Description and the User Agent Behavior section. All other parts are informative.
An Intent is an action with accompanying data, which is to be performed by a Service of the user's choosing.
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.)
Registration is how a Service page informs the User Agent that it 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.
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;
Object extras;
URL service;
sequence<URL> suggestions;
};
IntentParameters
Membersaction
of type DOMStringdata
of type anyextras
of type Objectservice
of type URLsuggestions
of type sequence<URL>transfer
of type sequence<Transferable>type
of type DOMStringThe Intent object models a particular task which can be requested to be handled by Services. It is left up to the client page whether to launch 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;
DOMString getExtra (DOMString key);
void postResult (any data, optional sequence<Transferable> transferable);
void postFailure (any data);
};
action
of type DOMString, readonlydata
of type any, readonlyports
of type array of MessagePort, readonlytype
of type DOMString, readonlygetExtra
Parameter | Type | Nullable | Optional | Description |
---|---|---|---|---|
key | DOMString | ✘ | ✘ |
DOMString
postFailure
Parameter | Type | Nullable | Optional | Description |
---|---|---|---|---|
data | any | ✘ | ✘ |
void
postResult
Parameter | Type | Nullable | Optional | Description |
---|---|---|---|---|
data | any | ✘ | ✘ | |
transferable | sequence<Transferable> | ✘ | ✔ |
void
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.
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 IntentFailureCallback
onFailure);
};
startActivity
null
), or if
the method is invoked without being the result of an explicit user gesture.
Parameter | Type | Nullable | Optional | Description |
---|---|---|---|---|
intent |
| ✘ | ✘ | |
onSuccess |
| ✘ | ✔ | |
onFailure |
| ✘ | ✔ |
void
The invocation API is implemented by the window.navigator
object.
Navigator implements Intents
;
The callbacks passed to startActivity must provide these signatures:
callback IntentSuccessCallback = void (optional any data, optional MessagePort[] ports);
IntentSuccessCallback
Parametersdata
of type anyports
of type array of MessagePortcallback IntentFailureCallback = void (optional any data);
IntentFailureCallback
Parametersdata
of type any
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;
};
intent
of type Intent
, readonlyWindow 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 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 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 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 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.
Service pages declaratively mark themselves (or other same-origin pages)
as providing handling functionality for particular intent actions and types
using the <intent>
tag.
A User Agent must not deliver an Intent to a web app service page which
does not include markup describing what intents it can handle which matches
the intent being delivered (See the section on Matching action and type for
delivery).
interface HTMLIntentElement : HTMLElement {
attribute DOMString action;
attribute DOMString type;
attribute DOMString href;
attribute DOMString title;
attribute DOMString disposition;
};
action
of type DOMStringaction
attribute is missing, the intent Service is
assumed to handle display of the provided type(s) in the type
attributes.disposition
of type DOMStringdisposition
attribute allows a service to choose which
context to be opened in. The User Agent must not allow the Client page any
ability to change the disposition. The window
disposition means
that the service is opened in a new tab or window context. The
inline
disposition means that the User Agent should open the
service in a context directly related to the client page context in an
overlappable way. The User Agent must not allow this UI surface to be
under the control of the client page.href
of type DOMStringhref
attribute
is missing, the service URI will be set to the URI in which the tag is
found.title
of type DOMStringtitle
attribute is missing, the User Agent should
use the title of the registered Service page as the service title.type
of type DOMString
This section should not be construed as limiting the ability of the User
Agent to manage registration of non-web services. That is, the User Agent
may handle intent invocations locally, using extensions, or with
third-party system services. This section solely governs how web-app service pages
register and unregister with the User Agent with the
<intent>
tag.
The User Agent must not obey any registration markup which is not
same-origin. That is, a page may only register href
attributes
for other service handlers on its same origin. A page may register itself
as a Service handler, by leaving the href
attribute empty.
For cross-page registration, when the href
attribute points to a different
resource, the User Agent should interpret intent registrations additively.
That is, an intent descriptor from the tag would be added to the registry
if it is not present (if the user approves the addition).
The User Agent should treat any registration markup which has both
action
and type
attributes missing as if the
markup specified no intent capability on the |href| page. That is, a page may
unregister itself implicitly by removing all intent tags, or explicitly
by keeping the tag present, but without action
or
type
attributes. Such explicit unregistration should
be honored for any tag with a same-origin href
attribute.
The intent tags on the service handler page itself should be interpreted by the User Agent as authoritative. That is, if the User Agent loads a service page, and sees that not all intent descriptors it believes will be handled by the page are actually handled, it would replace the currently-registered set with the new set declared by the page.
If a registered service page is retrieved and has a non-20x error code [HTTP11], the User Agent should take the following actions:
30x: redirect to the indicated page. If the page is on-domain, and has intent markup, the intent will be re-delivered. If the redirect is permanent (301), the User Agent may update its service registration records to reflect that.
40x: indicate to the user that the page cannot be loaded, along with any remediation capabilities (i.e. authentication for 403 or payments for 402). In the case of error 410, the User Agent should unregister the handler from its internal registry.
50x: indicate to the user that the page cannot be loaded.
When the User Agent loads a page with registration markup, it should allow the user to configure that page as a web intents service. The details of this process is left up to the User Agent. The model is that the page advises of the ability to handle intents, and the User Agent may remember that. The User Agent must not deliver an intent to a Service discovered in this way before the user has made a specific action allowing it.
The User Agent must not allow web pages the ability to discover passively which services the user has configured to handle particular intents, or any intents, whether by enumeration or exact query. There may be mechanisms for the user to actively grant this information to web pages, but it must not be made available passively.
The User Agent may provide additional mechanisms for web intents service registration. For example, by external applications, through a separate API, as a result of a permissions bundle in a downloaded web application, or pre-bundled. (TODO: add example of a local network service)
For intents invoked by client web applications, the User Agent must require that such invocations be in the context of a user gesture. User Agents may also dispatch intents invoked through other mechanisms. For example, hardware events (i.e. plugging in a USB storage device) or software events (i.e. downloading a file).
When a client page invokes an intent, the User Agent dispatches it to a chosen service. The details of this process are left up to the User Agent. The User Agent may dispatch intents to web application service pages, helper applications, proxy them through connections to other hardware, etc. In general, though, the User Agent must provide a way for the user to configure which intents are delivered to which services. This process should be configurable on a per-invocation basis for most intents, although defaulting rules, as long as they are configurable by the user, are expected to mean that the User Agent need not present specific UI controls on every invocation.
When the User Agent delivers an intent payload to a web application, it
must make the window.intent
object available as the document
is loaded and parsed, so that scripts on the page may process the intent
data as they load. User agents must not place a window.intent
object in the scope of pages which do not have registration metadata
declaring themselves as intent handlers. This means that any use of
window.intent
in pages which do not explicitly declare
themselves as web intents handlers must not be overwritten by the User
Agent. It also means that Service pages cannot access
window.intent
in scripts which occur before the page parses
the intents registration markup. If such scripts are simply declaring
functions to be called later, that will work, but scripts which run before
the registration markup is parsed won't find window.intent
set, even though it may be made available later in the page load, and so are
likely broken.
When a new context is opened for the service page, the User Agent must
connect the postResult
and postFailure
methods
of the window.intent
object so that they return their
serializable payloads to the registered handlers the User Agent received
in the invoking navigator.startActivity
call. If the user
closes the service page before it has responded, the User Agent must
invoke the onFailure
callback in the client page invocation,
if any. If the user cancels a service selection UI control the User Agent
displays in the course of dispatching an intent, the User Agent must
invoke the onFailure
callback in the client page invocation,
if any.
The User Agent should allow any serializable and/or Transferable object to be passed between client to service and back from service to client. This includes Blobs [BLOB], MessagePorts, etc. The User Agent may inspect the payload of intents and present specialized UI corresponding to well-known intent types. The User Agent must not categorically prohibit dispatch of unknown intent types. This is not meant to prohibit the User Agent from performing filtering functions on intents, such as suppressing unwanted intent invocations, intents as used as an attack vector, and other mis-use.
In the same way User Agents may dispatch Intents triggered by non-web mechanisms to web applications, User Agents may dispatch intents invoked by web applications to handlers which are not web applications. In those cases, the User Agent should provide a public API mechanism for external connection to the intent dispatch mechanism selected. For example, the User Agent may be able to run an Operating System command in response to an intent. The User Agent could provide a configuration interface such that the user can install handler applications, and a documented format in which intent payload data is translated to that application. In these cases, the requirement that User Agents pass any serializable object is relaxed for some kinds of handlers.
User Agents may also dispatch intents directly based on data-specific controls derived from microdata in pages, or based on other User Agent-level features. For instance, if the user has services registered which handle text/vcard, then the User Agent may provide the user with a way to invoke particular intents that consume such data as it detects it in web pages.
If the user has no services registered for a particular type of intent, the User Agent may display options from other sources of data about services it knows can handle that intent type so that the user can complete the activity.
When handling an Intent marked as explicit (that is, constructed with the object literal constructor with a non-empty service field), the expected User Agent behavior is that if this "service" attribute is present, it should not display a service selection mechanism to the user. Instead, the service url should be loaded directly to handle the intent. (This is not a hard restriction. The User Agent may provide a way for the user to intercept even an explicit invocation.)
During delivery, all restrictions are still in place. That is, the User
Agent must follow the above requirements on placing the
window.intent
object in the scope of the page, and respect
any declarative metadata in that service page. If the user agent needs
information about the service (i.e. disposition, title, etc) for use
in preparing its UI, it may load the service URL and examine the page
for any declarative metadata.
The User Agent may ask the user if they wish to install this service, just like for any other visit of the page.
When an Intent is delivered, the User Agent must verify that the Service to which the intent is to be delivered (either from an explicit invocation or from the result of a user selection) has a registration record supporting the action and type of the Intent being delivered by following these steps:
If the user has no persistent information about a qualifying service for a particular intent registered with the User Agent, the User Agent should present the user with the option to select from the default services proposed by the client at invocation (from the suggestions parameter).
If the user agent needs information about the all or any of the suggested services (i.e. disposition, title, icon, etc) for use in preparing its UI, it may load the suggested default service URL(s) and examine the page(s) for the <intent> tag, reading off such information, or load the favicon for the site(s). The User Agent may ask the user if they wish to install all or any of the suggested services, just as for any other visit of those pages.
The User Agent must follow the matching algorithm of the "Matching action and type for delivery" section before delivering the Intent to a suggested service, just as for any Intent delivery.
Web Intents should be useful to enable users to share content as they encounter it on web pages. Whether by implicit controls made available by the User Agent or explicit controls placed in web pages, Web Intents should handle the use case of a user wishing to share a page as a whole, or particular content on the page. The user should be able to select the sharing application of choice to accomplish this task.
Local web apps should be able to invoke and handle intents.
Web Intents invocations are modeled on RPC, but there are times when a persistent connection is desired. There are a few different methods that Web Intents should support for this. One is returning URIs which can be loaded by clients in an iframe and then messaged using other web platform features. Another is returning a defaulting token which the client can then use to target other intents directly at a known target. A third is returning a MessagePort to the client which can be used for subsequent communication.
In these cases, Web Intents is acting as a way for the user to attach a particular client page to a persistently-available service. It is up to the particular types of intents to describe exactly how this should work. i.e. whether the connection is permanent or temporary, whether tokens are user-consumable or opaque.
It should be possible for intents to be routed to external helper applications. For instance, a locally available photo editing tool could be configured to interact with the browser to handle an image edit intent. Or the browser could discover home networking equipment on the local network and make it available for particular types of intents.
It should be possible to translate a few existing features to use Web Intents, thus putting web applications on the same footing as local resources. For instance, it should be possible for the User Agent to translate file selection controls to intents such that the use can choose to upload a file from a cloud storage locker as well as from local disk. In these cases, the User Agent may supply built-in intent handlers corresponding to existing functionality.
Another use case is allowing web applications to function as plug-ins. For example, a link returning a resource of a type which the user agent doesn't know how to display can be translated into an intent which allows the user to configure a web application capable of reading that resource type and viewing it. This would let web apps function as plug-ins.
It is expected that many services for Web Intents will be ones the user has an account with. The service should be able to use standard login mechanisms in the context the User Agent places them within to perform authentication. That is, the service page handling an intent should be loaded with the same cookie jar and access to localStorage, etc. with which it runs in a normal browsing context. Intent data should be persisted by the User Agent across login redirects.
The user needs to have confidence that the Service will user the data associated with the action for the purpose intended and not share or retain the data inappropriately. For this reason it is important that the user have control over Intents, in particular the selection mechanism which determines which Service will handle a particular Intent. This offers the possibility of user decision and control related to the choice of Service, allowing them to take into account expectations regarding the Service, including Service policies related to retention and secondary use. This relates to the privacy principles of control and consent [DAP-PRIVACY-REQS]. For this reason a user should be made aware of explicit intents and be able to view and change them; implementations should be encouraged to offer this functionality. The minimum data necessary for a Service should be included as Intent parameters, corresponding to the privacy principle of minimization [DAP-PRIVACY-REQS].
Many thanks to Robin Berjon for making our lives so much easier with his cool tool.
See also webintents.org for more examples and a sample Javascript implementation of Web Intents.