Table of Contents

• 1. Introduction
• 2. Conformance
• 3. Dependencies
• 4. Concepts
  • 4.1 Webapp
  • 4.2 Push message
  • 4.3 Push subscription
  • 4.4 Push service
  • 4.5 Permission
• 5. Security and privacy considerations
• 6. Push Framework
  • 6.1 Example
  • 6.2 Sequence diagram
  • 6.3 Push service use
• 7. Extensions to the ServiceWorkerRegistration interface
• 8. PushManager interface
  • 8.1 PushSubscriptionOptions dictionary
• 9. PushSubscription interface
• 10. PushMessageData interface
• 11. Events
  • 11.1 The push event
  • 11.2 The pushsubscriptionchange event
• 12. Enumerations
• 13. Exceptions
• 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 MAY, MUST, MUST NOT, and SHOULD 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. Dependencies

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

Promise, and JSON.parse are defined in [ECMASCRIPT].

EventInit, DOMException, AbortError, InvalidStateError, SecurityError, NetworkError, and steps for constructing events are defined in [DOM].

The terms service worker, service worker registration, installing worker, waiting worker, and active worker, and the types ServiceWorkerRegistration, ServiceWorkerGlobalScope, ExtendableEvent, and ExtendableEventInit are defined in [SERVICE-WORKERS].

The algorithms utf-8 encode, and utf-8 decode are defined in [ENCODING].

Blob is defined in [FILEAPI].

Any, ArrayBuffer, BufferSource, and USVString are defined in [WEBIDL].

The web push protocol describes a protocol that enables communication between a user agent or application server and a push service. Alternative protocols could be used in place of this protocol, but this specification assumes the use of this protocol; alternative protocols are expected to provide compatible semantics. Note: this is currently only a proposed protocol.

4. Concepts

5. 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 subscribe() method, unless a previous permission grant has been persisted, or a prearranged trust relationship applies. Permissions that are preserved beyond the current browsing session MUST be revocable.

The user agent MAY consider the PushSubscriptionOptions when acquiring permission or determining the permission status.

When a permission is revoked, all push subscriptions created with that permission MUST be deactivated.

When a service worker registration is unregistered, any associated push subscription MUST be deactivated.

The endpoint of a deactivated push subscription MUST NOT be reused for a new push subscription. This prevents the creation of a persistent identifier that the user cannot remove. This also prevents reuse of the details of one push subscription to send push messages to another push subscription.

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 subscription data. Browsers may ignore this rule for development purposes only.

7. Extensions to the ServiceWorkerRegistration interface

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

partial interface ServiceWorkerRegistration {
    readonly    attribute PushManager pushManager;
};

The pushManager attribute exposes a PushManager, which has an associated service worker registration represented by the ServiceWorkerRegistration on which the attribute is exposed.

8. PushManager interface

The PushManager interface defines the operations to access push services.

interface PushManager {
    Promise<PushSubscription>    subscribe (optional PushSubscriptionOptions options);
    Promise<PushSubscription?>   getSubscription ();
    Promise<PushPermissionState> permissionState (optional PushSubscriptionOptions options);
};

The subscribe 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. Let registration be the PushManager's associated service worker registration.
5. If registration has no active worker, run the following substeps:
   1. If registration has no installing worker and no waiting worker, reject promise with a DOMException whose name is "InvalidStateError" and terminate these steps.
   2. Wait for the installing worker or waiting worker of registration to become its active worker.
   3. If registration fails to activate either worker, reject promise with a DOMException whose name is "InvalidStateError" and terminate these steps.
   4. Once registration has an active worker, proceed with the steps below.
6. 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.
7. If not granted, reject promise with a DOMException whose name is "PermissionDeniedError" and terminate these steps.
8. If the webapp is already subscribed, run the following substeps:
   1. Retrieve the push subscription 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 PushSubscription providing the details of the retrieved push subscription.
9. Make a request to the push service to create a new push subscription for the webapp.
10. If there is an error, reject promise with a DOMException whose name is "AbortError" and terminate these steps.
11. When the request has been completed, resolve promise with a PushSubscription providing the details of the new push subscription.

The getSubscription 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 subscribed, resolve promise with null.
4. Retrieve the push subscription 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 PushSubscription providing the details of the retrieved push subscription.

The permissionState 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 (PushPermissionState) 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 PushPermissionState 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 subscriptions if a valid permission exists.

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

dictionary PushSubscriptionOptions {
    boolean userVisibleOnly = false;
};

9. PushSubscription interface

A PushSubscription object represents a push subscription.

interface PushSubscription {
    readonly    attribute USVString endpoint;
    Promise<boolean> unsubscribe ();
    serializer = {attribute};
};

When getting the endpoint attribute, the user agent MUST return the endpoint associated with the push subscription.

The unsubscribe 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 push subscription has already been deactivated, resolve promise with false and terminate these steps.
4. Make a request to the push service to deactivate the push subscription.
5. If it was not possible to access the push service, reject promise with a "NetworkError" exception and terminate these steps.
6. When the request has been completed, resolve promise with true.

10. PushMessageData interface

interface PushMessageData {
    ArrayBuffer arrayBuffer ();
    Blob        blob ();
    Any         json ();
    USVString   text ();
};

PushMessageData objects have an associated bytes (a byte sequence) set on creation.

The arrayBuffer() method, when invoked, MUST return an ArrayBuffer whose contents are bytes.

The blob() method, when invoked, MUST return a Blob whose contents are bytes and type is not provided.

The json() method, when invoked, MUST return the result of invoking the initial value of JSON.parse with the result of running utf-8 decode on bytes as argument. Re-throw any exceptions thrown by JSON.parse.

The text() method, when invoked, MUST return the result of running utf-8 decode on bytes.

typedef USVString PushMessageDataInit;

To extract a byte sequence from object, run these steps:

1. Let bytes be an empty byte sequence.
2. Switch on object's type:

   USVString

   Set bytes to the result of running utf-8 encode on object.

3. Return bytes.

11. Events

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

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

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

The onpushsubscriptionchange attribute is an event handler whose corresponding event handler event type is pushsubscriptionchange.

dictionary PushEventInit : ExtendableEventInit {
    PushMessageDataInit data;
};

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

12. Enumerations

enum PushPermissionState {
    "granted",
    "denied",
    "prompt"
};

13. Exceptions

The Push API uses the following new DOMException names.