Table of Contents

• 1. Introduction
• 2. Conformance
• 3. Terminology
• 4. Security and privacy considerations
• 5. Push Framework
  • 5.1 Example
  • 5.2 Sequence diagram
  • 5.3 Push Server Discovery and API Use
• 6. Extensions to the ServiceWorkerRegistration interface
• 7. PushRegistrationManager interface
  • 7.1 Push Registration Persistence
  • 7.2 Push Registration Uniqueness
• 8. PushRegistration interface
• 9. Events
  • 9.1 The push event
  • 9.2 The pushregistrationlost event
• 10. Enumerations
• A. Acknowledgements
• B. References
  • B.1 Normative references
  • B.2 Informative references

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].

3. Terminology

The terms event handler, event handler event type, queue a task, and fire a simple event are defined in [HTML5].

Promise is defined in [ECMASCRIPT].

EventInit, DOMException, AbortError, NotFoundError, and SecurityError are defined in [DOM].

Service Worker, ServiceWorkerRegistration, ServiceWorkerGlobalScope, and ExtendableEvent are defined in [SERVICE-WORKERS].

The term webapp refers to a Web application, i.e. an application implemented using Web technologies, and executing within the context of a Web user agent, e.g. a Web browser or other Web runtime environment.

The term webapp server refers to server-side components of a webapp.

The term push message refers to an indication to a webapp that there is new information for it from the webapp server, all or part of which MAY be contained in the push message itself.

The term push registration refers to each logical channel aimed at delivering push messages from an webapp server to a webapp, which is created by a distinct registration of such webapp via this Push API.

The term push service refers to an overall end-to-end system that allows webapp servers to send push messages to a webapp.

The term push server refers to the push service access point via which webapp-servers can initiate push message delivery. Push servers typically expose APIs specific to the push service, e.g. for push message delivery initiation.

The term express permission refers to an act by the user, e.g. via user interface or host device platform features, via which the user approves the permission of a webapp to access the Push API.

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.

6. Extensions to the ServiceWorkerRegistration interface

The Service Worker specification defines a ServiceWorkerRegistration interface [SERVICE-WORKERS], which this specification extends.

partial interface ServiceWorkerRegistration {
    readonly    attribute PushRegistrationManager pushRegistrationManager;
};

The pushRegistrationManager attribute exposes the PushRegistrationManager for the Service Worker identified by the ServiceWorkerRegistration.

7. PushRegistrationManager interface

The PushRegistrationManager interface defines the operations that enable webapps to establish access to push services. Note that just a single push registration is allowed per webapp.

interface PushRegistrationManager {
    Promise<PushRegistration>     register ();
    Promise<PushRegistration>     unregister ();
    Promise<PushRegistration>     getRegistration ();
    Promise<PushPermissionStatus> hasPermission ();
};

The register method when invoked MUST run the following steps:

1. Let promise be a new Promise.
2. Return promise and continue the following steps asynchronously.
3. If the scheme of the document url is not https, reject promise with a DOMException whose name is "SecurityError" and terminate these steps.
4. Ask the user whether they allow the webapp to receive push messages, unless a prearranged trust relationship applies or the user has already granted or denied permission explicitly for this webapp.
5. If not granted, reject promise with a DOMException whose name is "PermissionDeniedError" and terminate these steps.
6. If the webapp is already registered, run the following substeps:
   1. Retrieve the push registration associated with the webapp.
   2. If there is an error, reject promise with a DOMException whose name is "AbortError" and terminate these steps.
   3. When the request has been completed, resolve promise with a PushRegistration providing the details of the retrieved push registration.
7. Make a request to the system to create a new push registration for the webapp.
8. If there is an error, reject promise with a DOMException whose name is "AbortError" and terminate these steps.
9. When the request has been completed, resolve promise with a PushRegistration providing the details of the new push registration.

The unregister method when invoked MUST run the following steps:

1. Let promise be a new Promise.
2. Return promise and continue the following steps asynchronously.
3. If the webapp is not registered, reject promise with a DOMException whose name is "NotFoundError" and terminate these steps.
4. Make a request to the system to deactivate the push registration associated with the webapp.
5. If there is an error, reject promise with a DOMException whose name is "AbortError" and terminate these steps.
6. When the request has been completed, resolve promise with a PushRegistration providing the details of the push registration which has been unregistered.

The getRegistration method when invoked MUST run the following steps:

1. Let promise be a new Promise.
2. Return promise and continue the following steps asynchronously.
3. If the webapp is not registered, reject promise with a DOMException whose name is "NotFoundError" and terminate these steps.
4. Retrieve the push registration associated with the webapp.
5. If there is an error, reject promise with a DOMException whose name is "AbortError" and terminate these steps.
6. When the request has been completed, resolve promise with a PushRegistration providing the details of the retrieved push registration.

The hasPermission method when invoked MUST run the following steps:

1. Let promise be a new Promise.
2. Return promise and continue the following steps asynchronously.
3. Retrieve the push permission status (PushPermissionStatus) of the requesting webapp
4. If there is an error, reject promise with no arguments and terminate these steps.
5. When the request has been completed, resolve promise with PushPermissionStatus providing the push permission status.

Permission to use the push service can be persistent, that is, it does not need to be reconfirmed for subsequent registrations if a valid permission exists.

If there is a need to ask for permission, it needs to be done by invoking the register method.

8. PushRegistration interface

The PushRegistration interface contains information about a specific channel used by a webapp to receive push messages.

interface PushRegistration {
    readonly    attribute DOMString endpoint;
    readonly    attribute DOMString registrationId;
};

When getting the endpoint attribute, the user agent MUST return the absolute URL exposed by the push server where the webapp server can send push messages to this webapp. The value of endpoint may be the same for multiple webapps / webapp instances running on multiple devices.

When getting the registrationId attribute, the user agent MUST return a univocal identifier of this push registration in the push server. It is used by the webapp server to indicate the target of the push messages that it submits to the push server. Each pair of registrationId and endpoint is expected to be unique and specific to a particular webapp instance running on a specific device.

9. Events

The Service Worker specification defines a ServiceWorkerGlobalScope interface [SERVICE-WORKERS], which this specification extends.

partial interface ServiceWorkerGlobalScope {
                attribute EventHandler onpush;
                attribute EventHandler onpushregistrationlost;
};

The onpush attribute is an event handler whose corresponding event handler event type is push.

The onpushregistrationlost attribute is an event handler whose corresponding event handler event type is pushregistrationlost.

dictionary PushEventInit : EventInit {
    DOMString? data;
};

[Constructor(DOMString type, optional PushEventInit eventInitDict), Exposed=ServiceWorker]
interface PushEvent : ExtendableEvent {
    readonly    attribute DOMString? data;
};

10. Enumerations

enum PushPermissionStatus {
    "granted",
    "denied",
    "default"
};