--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/spec/Overview-respec.html Tue Jan 24 15:13:25 2012 -0800
@@ -0,0 +1,619 @@
+<!DOCTYPE html>
+<html>
+ <head>
+ <title>Web Intents</title>
+ <meta http-equiv='Content-Type' content='text/html;charset=utf-8'/>
+ <!--
+ === NOTA BENE ===
+ For the three scripts below, if your spec resides on dev.w3 you can check them
+ out in the same tree and use relative links so that they'll work offline,
+ -->
+ <script src='http://dev.w3.org/2009/dap/ReSpec.js/js/respec.js' class='remove'></script>
+ <script src='http://dev.w3.org/2009/dap/ReSpec.js/bibref/biblio.js' class='remove'></script>
+ <script class='remove'>
+ var respecConfig = {
+ // specification status (e.g. WD, LCWD, NOTE, etc.). If in doubt use ED.
+ specStatus: "ED",
+
+ // the specification's short name, as in http://www.w3.org/TR/short-name/
+ shortName: "web-intents",
+
+ // if your specification has a subtitle that goes below the main
+ // formal title, define it here
+ // subtitle : "an excellent document",
+
+ // if you wish the publication date to be other than today, set this
+ // publishDate: "2009-08-06",
+
+ // if the specification's copyright date is a range of years, specify
+ // the start date here:
+ // copyrightStart: "2005"
+
+ // if there is a previously published draft, uncomment this and set its YYYY-MM-DD date
+ // and its maturity status
+ // previousPublishDate: "1977-03-15",
+ // previousMaturity: "WD",
+
+ // if there a publicly available Editor's Draft, this is the link
+ edDraftURI: "http://dev.w3.org/2011/webapps/TODO.html",
+
+ // if this is a LCWD, uncomment and set the end of its review period
+ // lcEnd: "2009-08-05",
+
+ // if you want to have extra CSS, append them to this list
+ // it is recommended that the respec.css stylesheet be kept
+ extraCSS: ["http://dev.w3.org/2009/dap/ReSpec.js/css/respec.css"],
+
+ // editors, add as many as you like
+ // only "name" is required
+ editors: [
+ { name: "Greg Billock",
+ company: "Google", companyURL: "http://google.com/" },
+ { name: "James Hawkins",
+ company: "Google", companyURL: "http://google.com/" },
+ { name: "Paul Kinlan",
+ company: "Google", companyURL: "http://google.com/" },
+ ],
+
+ // authors, add as many as you like.
+ // This is optional, uncomment if you have authors as well as editors.
+ // only "name" is required. Same format as editors.
+
+ //authors: [
+ // { name: "Your Name", url: "http://example.org/",
+ // company: "Your Company", companyURL: "http://example.com/" },
+ //],
+
+ // name of the WG
+ wg: "Web Applications (WebApps) Working Group",
+
+ // URI of the public WG page
+ wgURI: "http://www.w3.org/2008/webapps/",
+
+ // name (with the @w3c.org) of the public mailing to which comments are due
+ wgPublicList: "public-web-intents",
+
+ // URI of the patent status for this WG, for Rec-track documents
+ // !!!! IMPORTANT !!!!
+ // This is important for Rec-track documents, do not copy a patent URI from a random
+ // document unless you know what you're doing. If in doubt ask your friendly neighbourhood
+ // Team Contact.
+ wgPatentURI: "TODO",
+ };
+ </script>
+ </head>
+ <body>
+ <section id='abstract'>
+ <p>
+ This specification defines a service discovery and light-weight RPC
+ mechanism for web apps called Web Intents.
+ </p>
+ <p>
+ 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.
+ </p>
+ </section>
+
+ <section>
+ <h2>Introduction</h2>
+ <p>
+ 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.
+ </p>
+ <p>
+ An Intent is an action 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 (i.e. "share" or "edit"), a "type" string which
+ specifies the data payload the service should expect, and the data payload
+ itself.
+ </p>
+ <p>
+ A client requests an Intent be handled, the User Agent allows the
+ user to select which service to use, and the service performs the action
+ of the Intent, possibly using data passed as input in the Intent.
+ The service may return data as output to the client.
+ </p>
+ <p>
+ Web Intents provides a declarative syntax that allows
+ services to list the Intents they handle. Using this method, pages mark
+ up what actions they can handle what data types they expect.
+ </p>
+ <section>
+ <h3>Example</h3>
+ <p>
+ 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 <b>Edit</b> button, with this kind of accompanying
+ code:
+ </p>
+ <pre class="example">
+ document.getElementById('edit-photo').onclick = function() {
+ var intent = new Intent("http://webintents.org/edit",
+ "text/uri-list;type=image/jpeg",
+ getImageDataURI(...));
+ navigator.startActivity(intent, imageEdited);
+ });
+
+ function imageEdited(data) {
+ document.getElementById('image').src = data;
+ }
+ </pre>
+ <p>
+ This assumes an image editor exists which can consume images specified as
+ URIs (including data URIs), and produces a result in the same format. For
+ instance, one such editor might be a meme-maker—an application allowing
+ the user to place humorous messages on top of pictures they take.
+ </p>
+ <p>
+ Now that a picture has been selected 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 accompany code,
+ it can accomplish this integration:
+ </p>
+ <pre class="example">
+ document.getElementById('share-photo').onclick = function() {
+ var intent = new Intent("http://webintents.org/share",
+ "text/uri-list;type=image/jpeg",
+ getPublicURIForImage(...));
+ navigator.startActivity(intent);
+ });
+ </pre>
+ <p>
+ 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 can utilize 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 at any given time. The photo
+ hosting application isn't controlling which such application any given
+ user uses, it is loosely coupled with such appliations by providing the
+ data necessary for them to carry out their task and controls allowing the
+ user to launch these activities on the data.
+ </p>
+ <p>
+ On the service page, it needs to register itself as a service, and
+ handle the incoming intent data, possibly producing a response. That is
+ done with this kind of code:
+ </p>
+ <pre class="example">
+ <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.onload = function() {
+ if (window.intent) {
+ setImageContentURI(window.intent.data);
+ }
+ }
+
+ document.getElementById('save-button').onclick = function() {
+ window.intent.postReply(getImageDataURI(...));
+ }
+ </script>
+ </pre>
+ <p>
+ The assumed pieces here 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.
+ </p>
+ </section>
+ </section>
+
+ <section>
+ <h2>Terminology</h2>
+ <p>
+ An <dfn>Intent</dfn> is an action with accompanying data, which is to be
+ performed by a Service of the user's choosing.
+ </p>
+ <section>
+ <h3>Actors</h3>
+ <p>
+ A <dfn>Client</dfn> is a web page which creates an intent and invokes
+ it.
+ </p>
+ <p>
+ A <dfn>Service</dfn> is a web page which can handle a Web Intent,
+ possibly returning a piece of data to the calling Client page.
+ </p>
+ </section>
+ <section>
+ <h3>Life cycle of intents</h3>
+ <p>
+ <dfn>Registration</dfn> is how a Service page informs the User Agent
+ that it is capable of handling Intents.
+ </p>
+ <p>
+ <dfn>Invocation</dfn> refers to the API by which a Client page
+ dispatches an intent for handling.
+ </p>
+ <p>
+ <dfn>Selection</dfn> is the mechanism in which the User Agent decides
+ which service will handle a particular intent.
+ </p>
+ <p>
+ <dfn>Delivery</dfn> is the means by which the User Agent hands intent
+ data to a Service page for handling.
+ </p>
+ <p>
+ <dfn>Response</dfn> is the means in which the Service can respond to an
+ Intent by passing data back through the User Agent to the Client page.
+ </p>
+ </section>
+ </section>
+
+ <section>
+ <h2>API Description</h2>
+
+ <section>
+ <h3>Intent object</h3>
+ <p>
+ The client requests a specific intent handler and optionally sends in a callback to
+ receive data from the service. The browser mediates 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.
+ </p>
+ <dl title='[Constructor(in string action, in string type, in any data) raises DOMException] interface Intent' class='idl'>
+ <dt>readonly attribute DOMString action</dt>
+ <dd>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.</dd>
+ <dt>readonly attribute DOMString type</dt>
+ <dd>The data payload MUST be described by the type parameter.
+ Recommended type strings are MIME strings and self-documenting urls. The
+ string MUST NOT be empty, or the constructor MUST throw an exception.</dd>
+ <dt>readonly attribute any data</dt>
+ <dd>The object used MUST be a Transferable or an object upon which the
+ structured clone algorithm can be performed, or the constructor MUST
+ throw an exception.</dd>
+
+ <dt>void postResult(in any data)</dt>
+ <dd>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 a Transferable object [[!HTML5]] upon which the structured
+ clone algorithm can be performed.</dd>
+ <dt>void postFailure(in any data)</dt>
+ <dd>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 a Transferable object upon which the structured
+ clone algorithm can be performed.</dd>
+ </dl>
+ </section>
+
+ <section>
+ <h3>Invocation API</h3>
+ <p>
+ The client invokes an intent by constructing an object as above and invoking
+ a <code>navigator.startActivity</code> function on it. The callbacks are invoked when
+ the intent has been handled.
+ </p>
+ <dl title='[NoInterfaceObject] interface Intents' class='idl'>
+ <dt>void startActivity (in Intent intent, in optional onSuccess, in optional onFailure)</dt>
+ <dd>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.
+ <div class="exception" title="DOMException">
+ An exception MAY be thrown if the intent is unfit for the stated intent.
+ For example, the Intent is malformed (i.e. null) or the method is invoked without
+ being the result of an explicit user gesture.
+ </div>
+ </dd>
+ </dl>
+ <p>
+ The invocation API is implemented by the <code>window.navigator</code> object.
+ </p>
+ <dl title='Navigator implements Intents' class='idl'></dl>
+ </section>
+
+ <section>
+ <h3>Delivery and Response API</h3>
+ <p>
+ When the user agent loads a service page to handle an intent invocation, it
+ will place a <code>window.intent</code> object in the scope of the page.
+ </p>
+
+ <dl title='[NoInterfaceObject] interface IntentProvider' class='idl'>
+ <dt>readonly attribute Intent intent</dt>
+ <dd>The intent object as delivered to the service page.</dd>
+ </dl>
+ <dl title='DOMWindow implements IntentProvider' class='idl'></dl>
+
+ <p>
+ This object will only be made available to service pages when they are
+ loaded in the context of an intent invocation. In other situations, the User
+ Agent MUST NOT make <code>DOMWindow</code> implement
+ <code>IntentProvider</code>.
+ </p>
+ <p>
+ The <code>window.intent</code> object MUST be made available across
+ same-origin redirects of the service page. It MUST NOT be available if
+ redirects cross a same-origin boundary.
+ </p>
+ <p>
+ 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 <code>window.intent</code>
+ data would be available to all three page loads.
+ </p>
+ <p>
+ This will also work: http://example.com/service to
+ http://example.com/newservice. In this sequence, the <code>window.intent</code>
+ data is available to both pages.
+ </p>
+ <p>
+ In this sequence, the <code>window.intent</code> 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
+ </p>
+ <p>
+ 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 sequence
+ when they are in the same origin as that to which it was originally
+ delivered, but MUST NOT be available to any other pages. If the user navigates to a
+ different URL, even within the same origin, the intent data MUST NOT be made
+ available.
+ </p>
+ </section>
+
+ <section>
+ <h3>Registration Markup</h3>
+ <p>
+ Service pages declaratively mark themselves as providing handling
+ functionality for particular intent actions and types. A User Agent MUST NOT
+ deliver an intent to a page which is not described in its metadata
+ describing what intents it can handle. The algorithm for matching intents is
+ that the action string provided in invocation and registration must match
+ exactly, and the type strings must match exactly except for possible [[!RFC2046]]
+ MIME subtype wildcards.
+ <pre>
+ <!ENTITY % Disposition "{window|inline}">
+
+ <!ELEMENT INTENT - O EMPTY -- a Web Intents registration →
+ <!ATTLIST INTENT
+ action %URI; #REQUIRED -- URI specifying action --
+ type %ContentTypes,%URI; #REQUIRED -- advisory content type --
+ href %URI; #IMPLIED -- URI for linked resource --
+ title %i18n; #IMPLIED -- service title --
+ disposition %Disposition "window" -- where the service is created --
+ >
+ </pre>
+ </p>
+ <p>
+ The <code>dispositon</code> attribute allows a service to choose which
+ context to be opened in. The User Agent MUST NOT allow the client any
+ ability to change the disposition. The <code>window</code> disposition means
+ that the service is opened in a new tab or window context. The
+ <code>inline</code> 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.
+ </p>
+ <p>
+ The User Agent SHOULD discard any registration markup which is not
+ same-origin.
+ </p>
+ </section>
+
+ </section>
+
+ <section>
+ <h2>User Agent Behavior</h2>
+ <p>
+ 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, but
+ </p>
+ <p>
+ The User Agent MUST NOT allow web pages the ability to discover passively
+ which services the user has configured to handler 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.
+ </p>
+ <p>
+ 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.
+ </p>
+ <p>
+ For intents invoked by client web applications, the User Agent MUST
+ require that such invocations be directly caused by 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).
+ </p>
+ <p>
+ 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.
+ </p>
+ <p>
+ When the User Agent delivers an intent payload to a web application, it
+ MUST make the <code>window.intent</code> 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 <code>window.intent</code>
+ object in the scope of pages which do not have registration metadata
+ declaring themselves as intent handlers. This means that any use of
+ <code>window.intent</code> in pages which do not explicitly declare
+ themselves as web intents handlers MUST NOT be overwritten by the User
+ Agent.
+ </p>
+ <p>
+ When a new context is opened for the service page, the User Agent MUST
+ connect the <code>postResult</code> and <code>postFailure</code> methods
+ of the <code>window.intent</code> object so that they return their
+ serializable payloads to the registered handlers the User Agent received
+ in the invoking <code>navigator.startActivity</code> call. If the user
+ closes the service page before it has responded, the User Agent SHOULD
+ invoke the <code>onFailure</code> 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 SHOULD
+ invoke the <code>onFailure</code> callback in the client page invocation,
+ if any.
+ </p>
+ <p>
+ The User Agent SHOULD allow any serializable 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.
+ </p>
+ <p>
+ In the same way User Agents MAY dispatch intents caused 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 level 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 SHOULD pass
+ any serializable object may need to be relaxed for some kinds of handlers.
+ </p>
+ <p>
+ User Agents MAY also dispatch intents based on data-specific controls
+ derived from microdata in pages. 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.
+ </p>
+ <p>
+ 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.
+ </p>
+ </section>
+
+ <section>
+ <h2>Use Cases and Requirements</h2>
+ <section>
+ <h3>Sharing</h3>
+ <p>
+ Web Intents should be useful to enable 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.
+ </p>
+ </section>
+ <section>
+ <h3>Integration with local web apps</h3>
+ <p>
+ Local web apps should be able to invoke and handle intents.
+ </p>
+ </section>
+ <section>
+ <h3>Persistent connections</h3>
+ <p>
+ 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.
+ </p>
+ <p>
+ 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.
+ </p>
+ </section>
+ <section>
+ <h3>Integration with external applications</h3>
+ <p>
+ 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.
+ </p>
+ </section>
+ <section>
+ <h3>Translating existing web platform features to intents</h3>
+ <p>
+ 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.
+ </p>
+ <p>
+ 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.
+ </p>
+ </section>
+ <section>
+ <h3>Authentication</h3>
+ <p>
+ 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.
+ </p>
+ </section>
+ </section>
+
+ <section class='appendix'>
+ <h2>Acknowledgements</h2>
+ <p>
+ Many thanks to Robin Berjon for making our lives so much easier with his cool tool.
+ </p>
+ <p>
+ See also <a href="http://www.webintents.org/">webintents.org</a> for
+ more examples and a sample Javascript implementation of Web Intents.
+ </p>
+ </section>
+ </body>
+</html>
+