1. Introduction This section is non-normative. As defined here, push services support delivery of webapp 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 messages 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 messages 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 message is received, e.g. the WebRTC use case in which an incoming call can invoke the WebRTC webapp

multiple webapps are running, but push messages 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 messages 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 messages 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 messages 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 ].

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. User agents MUST implement the Push API to be HTTPS-only. SSL-only support provides better protection for the user against man-in-the-middle attacks intended to obtain push registration data. Browsers may ignore this rule for development purposes only. Permissions that are preserved beyond the current browsing session MUST be revocable.

5. Push Framework This section is non-normative. Although push services are expected to differ in deployment, a typical deployment is expected to have the following general entities and example operation for delivery of push messages: Webapp servers request delivery of a push message to a webapp via a RESTful API exposed by a push server

The push server delivers the message to a specific user agent

The user agent delivers the push message to the specific webapp intended to receive it. This overall framework allows webapp servers to inform webapps that new data is available at the webapp server, or pass the new data directly to the webapp in the push message. The push API enables delivery of arbitrary application data to webapps, and makes no assumptions about the over-the-air/wire protocol used by push services. As such, the details of what types of data flow through a push services for a particular webapp are specific to the push service and webapp. As needed, clarification about what data flows over-the-air/wire should be sought from push service operators or webapp developers. The following code and diagram illustrate a hypothetical use of the push API. 5.1 Example This section is non-normative. Example 1 // https://example.com/serviceworker.js this . onpush = function ( event ) { console . log ( event . data ); // From here we can write the data to IndexedDB, send it to any open windows, // display a notification, etc. } // https://example.com/webapp.js navigator . serviceWorker . ready . then ( function ( serviceWorkerRegistration ) { serviceWorkerRegistration . pushRegistrationManager . register (). then ( function ( pushRegistration ) { console . log ( pushRegistration . registrationId ); console . log ( pushRegistration . endpoint ); // The push registration details needed by the application server to push // messages to the push service are now available, and can be sent to the // application server using, for example, an XMLHttpRequest. }, function ( error ) { // During development it often helps to log errors to the console. In a // production environment it might make sense to also report information // about errors back to the application server. console . log ( error ); } }); }); 5.2 Sequence diagram This section is non-normative. Fig. 1 Example flow of events for registration, message delivery, and unregistration 5.3 Push Server Discovery and API Use This specification does not define either specific normative methods via which webapps can determine the applicable push system, or initiate push requests through that system via a push server API. While these limitations add complexity for webapp developers, they reflect the current reality of a diversity of push systems, for which convergence at least in push server APIs, is not expected to be a short-term possibility. While a converged push server API is a worthwhile goal and may be addressed in a different specification, the Push API defined here has been designed to enable the current variety of push systems to be used as appropriate for the webapp host device or software platform. This section provides examples of how a webapp can be designed to work with a variety of hypothetical push systems as needed. The Push API provides several interface parameters and attributes that can enable a webapp to deliver and obtain the necessary push system specific data enabling use of that particular push system. These parameters and attributes include: The registrationId of a PushRegistration , as an opaque string to the Push API, may be used by push systems to provide meaningful data to the webapp server through the webapp. For example, the registrationId may be used as a push server API request parameter or request body element for specific push systems.

of a , as an opaque string to the Push API, may be used by push systems to provide meaningful data to the webapp server through the webapp. For example, the may be used as a push server API request parameter or request body element for specific push systems. As a URI, the endpoint of a PushRegistration provides a flexible means for push systems to deliver webapp-specific registration and/or push server API parameters to the webapp server, through the webapp. Push systems that are compatible with the Push API will be expected to clarify how these data are used in the push server APIs of the specific system, e.g. through their developer programs. Examples of considerations include: The URI used by the webapp server to issue push server API requests, which may be based upon the endpoint , and for a particular push server API request require additional parameters e.g. the registrationId .

, and for a particular push server API request require additional parameters e.g. the . The push server API request body, which may require that the endpoint or registrationId be present in some body element.

or be present in some body element. The pushRegistration attributes may only be used by the webapp server to associate the webapp to a specific push service registration, with the details of the push server API relying upon other pre-configured data. The Push API does not provide any pushRegistration attributes that normatively identify the particular push system that applies to the registration. Webapps that are designed to work with a single push system are assumed to know inherently how to use the push server API of that system. For such webapps, a key consideration is ensuring that if the webapp is used on a device or browser that does not support the necessary push system, that either the user is informed that the push-dependent webapp functions will not work, or the webapp must use alternate methods e.g. [ websockets ] or [ SSE ] to deliver the server-initiated data. Prior to use of a push server API, webapp servers that are designed to work with multiple push systems may need to determine the applicable system by parsing the endpoint to detect the push system from the URI domain.

6. Extensions to the ServiceWorkerRegistration interface The Service Worker specification defines a ServiceWorkerRegistration interface [ SERVICE-WORKERS ], which this specification extends. ServiceWorkerRegistration { PushRegistrationManager pushRegistrationManager readonly attribute partial interface}; The pushRegistrationManager attribute exposes the PushRegistrationManager for the Service Worker identified by the ServiceWorkerRegistration .

10. Enumerations PushPermissionStatus { " enum{ " granted ", " denied ", " default " }; Enumeration description granted The webapp has permission to use Push API. denied The webapp has been denied permission to use Push API. default The webapp needs to ask for permission in order to use Push API.