Push API W3C Working Draft 15 August 2013 This version: http://www.w3.org/TR/2013/WD-push-api-20130815/ Latest published version: http://www.w3.org/TR/push-api/ Latest editor's draft: http://dvcs.w3.org/hg/push/raw-file/tip/index.html Previous version: http://www.w3.org/TR/2012/WD-push-api-20121018/ Editors: Copyright © 2013 W3C ® ( MIT , ERCIM , Keio, Beihang), All Rights Reserved. W3C liability, trademark and document use rules apply.

1. Introduction This section is non-normative. As defined here, push services support delivery of application server messages in the following contexts and related use cases: the user is actively involved in the use of a webapp: this relates to any normal use case in which a webapp user may benefit from push notifications while the user is actively using the webapp

the user is not actively involved in the use of a webapp, but the webapp is active in a window of the browser or executing as a web worker: this relates to use cases such as social networking, messaging, web feed readers, etc in which the user may not be actively using a webapp but still benefits from push notifications being sent to (or via) the webapp, to keep the user up-to-date

the webapp is not currently active in a browser window: this relates to use cases in which the user may close the webapp, but still benefits from the webapp being able to be restarted when a push notification is received, e.g. the WebRTC use case in which an incoming call can invoke the WebRTC webapp

multiple webapps are running, but push notifications are delivered only to the webapp that requested them, e.g. any normal use case in which multiple webapps are active in the browser and utilizing push services

multiple instances of the same webapp are active in the browser, and push notifications specific to each instance of the webapp are delivered only to the specific instance, e.g. when a mail webapp is active in two windows using different mail accounts

multiple instances of the same webapp are active in different browsers, and push notifications are delivered to a set of instances of the webapp, e.g. when a mail webapp is active in two browsers using the same email account

multiple instances of the same webapp are active in different browsers, and push notifications are delivered to all instances of the webapp, e.g. when a message is to be broadcasted to all users of the webapp

2. Conformance 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.

4. Security and privacy considerations 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 register() 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.

5. Push Framework This section is non-normative. There are different deployment alternatives to allow application servers to deliver push notifications to webapps. In a typical deployment application servers send a push notification to a Push server, e.g. by a RESTful interface, which in turn sends a push notification to the user agent providing the execution context for the webapp. The user agent then delivers the push notification to the corresponding webapp to which it was addressed. The push notification MAY include a version number of the latest information available through this push registration, which the webapp may retrieve if not coincident with the latest version it has already retrieved. The push notification system MUST ensure that the application eventually has the latest version of data on the application server. The push server may lose intermediate notifications or may lose all state, while fulfilling this requirement. In such an event, it will deliver a push-register system message to the application, so that the application may fetch the latest data from the application server. Example 1 pushRegistrations = null ; function registerPush () { navigator . push . register (). then ( function ( value ) { pushRegistrations . push ( value ); registerWithAppServer ( value ); }, function ( reason ) { alert ( "darn! " + reason );} ); } function reRegisterPush ( pushRegistration ) { for ( reg in pushRegistrations ) { if ( pushRegistrations [ reg ] == pushRegistration ) pushRegistrations . splice ( reg , 1 ); } registerPush (); } navigator . push . registrations (). then ( function ( registrations ) { if ( registrations . length == 0 ) registerPush (); // assume at least one needed else pushRegistrations = registrations ; }, function ( reason ) { alert ( "darn! " + reason );} ); function registerWithAppServer ( pushRegistration ) { var activate = "http://example.com/push/activate?pushRegistrationId=" + encodeURIComponent ( pushRegistration . pushRegistrationId )+ "&pushEndpoint=" + encodeURIComponent ( pushRegistration . pushEndpoint ); asyncXHR ( activate ); // send activation request to application server }; function gotPush ( message ) { if ( message . version == null ) { var reset = "http://example.com/push/reset?pushRegistrationId=" + encodeURIComponent ( pushRegistration . pushRegistrationId )+ "&pushEndpoint=" + encodeURIComponent ( pushRegistration . pushEndpoint ); asyncXHR ( reset ); // send reset request to application server } else { if ( message . version > last_version ) { var getdata = "http://example.com/push/get?pushRegistrationId=" + encodeURIComponent ( pushRegistration . pushRegistrationId )+ "&last=" + last_version + "¤t=" + message . version ; gotdata = function ( data ) { // handle retrieved data } asyncXHR ( getdata , gotdata ); // send data retrieval request to app server } } } if ( navigator . hasPendingMessages ( "push" )) { // do any special pre-processing before push messages are delivered } last_version = null ; // initialize last message version navigator . setMessageHandler ( "push" , gotPush ); navigator . setMessageHandler ( "push-register" , reRegisterPush ); /* Hypothetical end-to-end flow +--------+ +--------+ +--------+ +--------+ | webapp | | user | | push | | app | | | | agent | | server | | server | +--------+ +--------+ +--------+ +--------+ | | | | |-----register------>| | | | | | | | (user accepts) | | | | | | | |<-setup push service->| | | | | | |<---success---------| | | | | | | |<--activate service with PushService attributes----------------->| | | | | | | |<--push notification-| | | | per service API | | | | | | | (match to user agent) | | | | | | |<--push notification--| | | | per service protocol | | | | | | | (match to webapp) | | | | | | |<---system message--| | | | | | | */

6. Navigator Interface Navigator { PushManager push readonly attribute partial interface}; 6.1 Attributes push of type PushManager The object that exposes the push service management interface.

10. PushRegisterMessage Interface The PushRegisterMessage interface represents a System Message related to a push registration that is no longer valid and thus needs to be created again by the webapp by means of a new invocation of the register method. PushRegisterMessage { DOMString pushRegistrationId readonly attribute interface}; 10.1 Attributes pushRegistrationId of type DOMString MUST return the identifier of the push registration to which this System Message is related.