Copyright © 2012 W3C® (MIT, ERCIM, Keio), All Rights Reserved. W3C liability, trademark and document use rules apply.
This specification defines a “Push API” that provides webapps with scripted access to server-sent application data, for simplicity referred to here as "Push messages" as delivered by "Push services". Push services are a way for application servers to send messages to webapps, whether or not the webapp is active in a browser window.
Push messages may be delivered via various methods, either via standardized protocols (e.g. Server-Sent Events [SSE], the GSM Short Message Service [GSM-SMS], SIP MESSAGE [RFC3428], or OMA Push [OMA-PUSH]), or via browser-specific methods. The specific method to be used by a webapp is either selected by the user through selecting a Web Intent Push Service provider, or by the browser. The Push API is defined to promote compatibility with any underlying delivery method.
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 was published by the Web Applications 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-webapps@w3.org
(subscribe,
archives)
using a subject prefix of [push-api].
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.
This section is non-normative.
As defined here, Push services support delivery of application server messages in the following contexts and related use cases:
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].
This specification defines conformance criteria that apply to a single product: the user agent that implements the interfaces that it contains.
Implementations that use ECMAScript to implement the APIs defined in this specification must implement them in a manner consistent with the ECMAScript Bindings defined in the Web IDL specification [WEBIDL], as this specification uses that specification and terminology.
The Function interface represents a function in the scripting language being used as defined in [HTML5].
The concepts queue a task and fires a simple event are defined in [HTML5].
The terms event handlers and event handler event types are defined in [HTML5].
The term Web Intent Push Service provider refers to a service implemented as described in [WEBINTENTS], and offering Push API binding to event delivery via the service.
The term push server refers to a system via which a push service is provided.
The term webapp refers to Web applications, i.e. applications implemented using Web technologies, and executing within the context of a Web user agent, e.g. a Web browser or other Web runtime environment.
User agents must not provide Push API access to Webapps without the express permission of the user. User agents must acquire consent for permission through a user interface for each call to the requestRemotePermission() method, unless a prearranged trust relationship applies.
user agents may support prearranged trust relationships that do not require such per-request user interfaces.
Permissions that are preserved beyond the current browsing session must be revocable.
This section is non-normative.
There are different deployment alternatives to allow application servers to deliver Push messages to webapps. In a typical deployment application servers send push messages to a push server, e.g. by a RESTful interface, which in turn delivers the message to the user agent providing the execution context for the webapp. The user agent then delivers the Push message to the corresponding webapp to which the Push message was addressed.
This API allows webapps to ask the user for permission to receive Push messages and to provide the user agent with the necessary information to activate the Push service. For instance, the webapp provides a unique application token that is used by the application server when sending a message to the push server to address an specific instance (or set thereof) of the application. In case several instances of a webapp register the same application token, e.g. in different user agents, then the push server deliver Push messages addressed to that application token to all of those instances (e.g. when a mail webapp is active in two browsers using the same mail account)
Also the webapp may provide additional information in order to allow the push server to verify that Push messages come from the right application server. Namely it can provide a public key that the push server can use to verify that the Push message comes from the right application server, which has signed the message with the associated private key
var token = getGuid(); // get GUID as unique token var mypush = requestRemotePermission(token); mypush.onerror = function () { alert("darn! "+e.message); }; mypush.onsuccess = function () { var activate = "http://example.com/push/activate?token="+token+ "&serviceUrl="+encodeURIComponent(mypush.serviceUrl)+ "&serverProtocols="+mypush.serverProtocols; asyncXHR(activate); // send activation request to application server mypush.wakeup = true; mypush.onmessage = function (event) { document.getElementById('message').innerHTML = event.data; }; }; /* Hypothetical end-to-end flow +--------+ +--------+ +--------+ +--------+ | webapp | | user | | push | | app | | | | agent | | server | | server | +--------+ +--------+ +--------+ +--------+ | | | | requestRemotePermission->| | | | | | | | (user accepts) | | | | | | | |<-setup push service->| | | | | | |<---success event---| | | | | | | |<--activate service with PushService attributes----------------->| | | | | | | |<----push message----| | | | per service API | | | | | | | (match to user agent) | | | | | | |<----push message-----| | | | per service protocol | | | | | | | (match to webapp) | | | | | | |<---message event---| | | | | | | */
PushManager InterfaceThis interface defines the operations that enable webapps to establish access to Push services.
interface PushManager {
PushService requestRemotePermission (DOMString appToken, optional DOMString publicKey, optional DOMString algorithm);
PushService checkRemotePermission (DOMString appToken);
};checkRemotePermissionPushService object that requestRemotePermission() received, but if the user has never allowed notifications for the webapp the error callback would run.| Parameter | Type | Nullable | Optional | Description |
|---|---|---|---|---|
| appToken | DOMString | ✘ | ✘ |
PushServicerequestRemotePermissionIn order to verify that Push messages received by the push server come from the right server, the application server may sign Push messages. In case messages are signed by the corresponding application server then the webapp must include in the publicKey attribute the public key that the push server can use to verify the signature of Push messages.The default signature algorithm is RSA-SHA256, which must be supported by push servers, although the webapp may propse the use of a different algorithm. If the webapp wants to indicate the use of a different signature algorithm it will indicate it in the algorithm attribute, which will be enconded according to [XMLSEC-ALGORITHMS]
Upon success, a PushService object is returned, with a Push service URL where the application server can send messages to this webapp. If the webapp has been granted permission already and is calling requestRemotePermission() again, the Push service URL will be returned without asking again for permission.
| Parameter | Type | Nullable | Optional | Description |
|---|---|---|---|---|
| appToken | DOMString | ✘ | ✘ | |
| publicKey | DOMString | ✘ | ✔ | |
| algorithm | optional DOMString | ✘ | ✔ |
PushServiceIf the user permits webapp access to Push service upon a call to the requestRemotePermission() method, the user agent must activate the service.
The particular Push service used by the user agent is transparent to the webapp and the requirements for its activation are either unspecified or as defined here.
PushService InterfaceThe PushService interface enables webapps to access Push services that have been permitted by the user.
interface PushService : EventTarget {
readonly attribute DOMString appToken;
readonly attribute DOMString publicKey;
readonly attribute DOMString algorithm;
readonly attribute DOMString serviceUrl;
readonly attribute DOMString[] serverProtocols;
readonly attribute DOMError error;
attribute boolean wakeup;
attribute Function? onsuccess;
attribute Function? onerror;
attribute Function? onmessage;
void close ();
readonly attribute unsigned short readyState;
const unsigned short CONNECTING = 0;
const unsigned short OPEN = 1;
const unsigned short CLOSED = 2;
};algorithm of type DOMString, readonlyrequestRemotePermission().appToken of type DOMString, readonlyrequestRemotePermission().error of type DOMError, readonlyonerror of type Function, nullablerequestRemotePermission() or checkRemotePermission().onmessage of type Function, nullableonsuccess of type Function, nullablerequestRemotePermission() or checkRemotePermission().publicKey of type DOMString, readonlyrequestRemotePermission().readyState of type unsigned short, readonlyserverProtocols of type array of DOMString, readonlyserviceUrl of type DOMString, readonlywakeup of type booleanCLOSED of type unsigned shortCONNECTING of type unsigned shortOPEN of type unsigned shortThe appToken attribute must return the application token that was passed as a parameter to requestRemotePermission().
The publicKey attribute must return the public key that was passed as a parameter to requestRemotePermission().
The algorithm attribute must return the signature algorithm that was passed as a parameter to requestRemotePermission().
The serviceUrl attribute must return the absolute URL where the application server can send Push service messages to this webapp.
The serverProtocols attribute must return an array of push service protocols which are supported by the push server via the serviceUrl. The list should be ordered by preference (e.g. protocols more likely to be deprecated first should go later in the array). Application servers are expected to use the first supported protocol in this list.
The error attribute must return any error that occured in processing the request, or during operation of the Push service.
If set to true, the wakeup, when a Push message is received and the webapp is not active in a browser window, the browser must invoke the webapp if possible, and deliver the Push message to it. Examples of cases in which webapps should be invokable include:
PushService object was created.
The readyState attribute represents the state of the Push service. It can have the following values:
CONNECTING (numeric value 0)OPEN (numeric value 1)CLOSED (numeric value 2)close() method was invoked.When the PushService object is created its readyState must be set to OPEN (1) if Push messages may be immediately received by the webapp (i.e. no further processing is required to activate the Push service). Otherwise readyState must be set to CONNECTING (0), and transition to OPEN (1) only when Push messages may be received by the webapp.
The close() method must abort any further operation of a Push service related to the PushService object, and must set the readyState attribute to CLOSED.
The following are the event handlers (and their corresponding event handler event types) that must be supported, as IDL attributes, by all objects implementing the PushService interface:
| Event handler | Event handler event type |
|---|---|
onsuccess | success
|
onmessage | message
|
onerror | error
|
When a Push message is received, the user agent must deliver the message data via the onmessage handler, if possible. If delivery is not possible, the user agent may discard the message, or may queue it for later delivery.
User agents that support Push API binding to the [OMA-PUSH] protocol must deliver related [OMA-PUSH] messages as a message event with the interface MessageEvent on the PushService object, with the event's data attribute set to the textual representation of the body of the received [OMA-PUSH] message.
User agents that support Push API binding to the [GSM-SMS] protocol must deliver related [GSM-SMS] messages as a message event with the interface MessageEvent on the PushService object, with the event's data attribute set to the textual representation of the body of the received [GSM-SMS] message.
User agents that support Push API binding to the [RFC3428] protocol must deliver related [RFC3428] messages as a message event with the interface MessageEvent on the PushService object, with the event's data attribute set to the textual representation of the body of the received [RFC3428] message.
This section is non-normative.
To be provided.
To be provided.