Abstract

The Push API enables sending of a push message to a webapp via a push service. An application server can send a push message at any time, even when a webapp or user agent is inactive. The push service ensures reliable and efficient delivery to the user agent. Push messages are delivered to a Service Worker that runs in the origin of the webapp, which can use the information in the message to update local state or display a notification to the user.

This specification is designed for use with the web push protocol, which describes how an application server or user agent interacts with a push service.

Status of This Document

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 Platform Working Group as an Working Draft. If you wish to make comments regarding this document, please send them to public-webapps@w3.org (subscribe, archives) with [Push API] at the start of your email's subject. All comments are 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 document is governed by the 1 September 2015 W3C Process Document.

Table of Contents

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:

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, trusted event, and fire a simple event are defined in [HTML5].

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

EventInit, DOMException, AbortError, InvalidStateError, SecurityError, NetworkError, event listener, 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, ExtendableEventInit, extend lifetime promises and the Handle Functional Event algorithm 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 [WEBPUSH-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.

4. Concepts

4.1 Webapp

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 application server refers to server-side components of a webapp.

4.2 Push message

A push message is data sent to a webapp from an application server.

A push message is delivered to the active worker associated with the push subscription to which the message was submitted. If the service worker is not currently running, the worker is started to enable delivery.

4.3 Push subscription

A push subscription is a message delivery context established between the user agent and the push service on behalf of a webapp. Each push subscription is associated with a service worker registration and a service worker registration has at most one push subscription.

When a push subscription is deactivated, both the user agent and the push service MUST delete any stored copies of its details. Subsequent push messages for this push subscription MUST NOT be delivered.

A push subscription is deactivated when its associated service worker registration is unregistered, though a push subscription MAY be deactivated earlier.

A push subscription has an associated push endpoint. It MUST be the absolute URL exposed by the push service where the application server can send push messages to. A push endpoint MUST uniquely identify the push subscription.

4.4 Push service

The term push service refers to a system that allows application servers to send push messages to a webapp. A push service serves the push endpoint or endpoints for the push subscriptions it serves.

4.5 Permission

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 use of the Push API by the webapp.

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

6. Push Framework

This section is non-normative.

A push message is sent from an application server to a webapp as follows:

This overall framework allows application servers to activate a Service Worker in response to events at the application server. Information about those events can be included in the push message, which allows the webapp to react appropriately to those events, potentially without needing to initiate network requests.

The following code and diagram illustrate a hypothetical use of the push API.

6.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.register('serviceworker.js').then(
  function(serviceWorkerRegistration) {
    serviceWorkerRegistration.pushManager.subscribe().then(
      function(pushSubscription) {
        console.log(pushSubscription.endpoint);
        console.log(pushSubscription.getKey('p256dh'));
        console.log(pushSubscription.getKey('auth'));
        // The push subscription details needed by the application
        // server are now available, and can be sent to it 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);
      }
    );
  });

6.2 Sequence diagram

This section is non-normative.

Example flow of events for subscription, push message delivery, and unsubscription
Fig. 1 Example flow of events for subscription, push message delivery, and unsubscription

6.3 Push service use

The fields included in the PushSubscription is all the information needed for an application server to send a push message. Push services that are compatible with the Push API provide a push endpoint that conforms to the web push protocol. These parameters and attributes include:

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 Service Worker is already subscribed, run the following substeps:
    1. Retrieve the push subscription associated with the Service Worker.
    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 Service Worker.
  10. If there is an error, reject promise with a DOMException whose name is "AbortError" and terminate these steps.
  11. Generate a new P-256 ECDH key pair. Store the private key in an internal slot associated with the subscription; this value MUST NOT be made available to applications. The public key is also stored in an internal slot and can be retrieved by calling the getKey method of the PushSubscription with an argument of p256dh.
  12. Generate a new authentication secret, which is a sequence of octets as defined in [WEBPUSH-ENCRYPTION]. Store the authentication secret in an internal slot associated with the subscription. This key can be retrieved by calling the getKey method of the PushSubscription with an argument of auth.
  13. 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 Service Worker is not subscribed, resolve promise with null.
  4. Retrieve the push subscription associated with the Service Worker.
  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.

8.1 PushSubscriptionOptions dictionary

A PushSubscriptionOptions object represents additional options associated with a push subscription. The user agent MAY consider these options when requesting express permission from the user. When an option is considered, the user agent SHOULD enforce it on incoming push messages.

dictionary PushSubscriptionOptions {
             boolean userVisibleOnly = false;
};

The userVisibleOnly option, when set to true, indicates that the push subscription will only be used for push messages whose effect is made visible to the user, for example by displaying a Web Notification. [NOTIFICATIONS]

9. PushSubscription interface

A PushSubscription object represents a push subscription.

interface PushSubscription {
    readonly        attribute USVString endpoint;
    ArrayBuffer?     getKey (PushEncryptionKeyName name);
    Promise<boolean> unsubscribe ();
    serializer;
};

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

The getKey method retrieves keying material that can be used for encrypting and authenticating messages. When getKey is invoked the following process is followed:

  1. Find the internal slot corresponding to the key named by the name argument.
  2. If a slot was not found, return null.
  3. Initialize a variable key with a newly instantiated ArrayBuffer instance.
  4. If the internal slot contains an asymmetric key pair, set the contents of key to the serialized value of the public key from the key pair. This uses the serialization format described in the specification that defines the name. For example, [WEBPUSH-ENCRYPTION] specifies that the p256dh public key is encoded using the uncompressed format defined in [X9.62] Annex A (that is, a 65 octet sequence that starts with a 0x04 octet).
  5. Otherwise, if the internal slot contains a symmetric key, set the contents of key to a copy of the value from the internal slot. For example, the auth parameter contains an octet sequence used by the user agent to authenticate messages sent by an application server.
  6. Return key.

Keys named p256dh and auth MUST be supported.

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.

The serializer for a PushSubscription invokes the following steps:

  1. Let map be an empty map.
  2. Add an entry to map whose key name is endpoint and whose value is the result of converting the endpoint attribute of the PushSubscription to a serialized value. The user agent MUST use a serialization method that does not contain input-dependent branchs (that is, one that is constant time). Note that a URL - as ASCII text - will not ordinarily require special treatment.
  3. Let keys be an empty map.
  4. For each identifier i corresponding to keys in internal slots on the PushSubscription, ordered by the name of the key:
    1. If the internal slot corresponds to an asymmetric key pair, let b be the encoded value of the public key corresponding to the key name i, using the encoding defined for the key name (see getKey).
    2. Otherwise, let b be the value as returned by getKey.
    3. Let s be the URL-safe base64 encoding of b as a USVString. The user agent MUST use a serialization method that does not branch based on the value of b.
    4. Add an entry to keys whose key name is the name of i and whose value is s.
  5. Add an entry to map whose key name is keys and whose value is keys.
  6. Return map.

9.1 PushEncryptionKeyName enumeration

Encryption keys used for push message encryption are provided to a webapp through the getKey method or the serializer of PushSubscription. Each key is named using a value from the PushEncryptionKeyName enumeration.

enum PushEncryptionKeyName {
    "p256dh",
    "auth"
};

The p256dh value is used to retrieve the P-256 ECDH Diffie-Hellman public key described in [WEBPUSH-ENCRYPTION].

The auth value is used to retrieve the authentication secret described in [WEBPUSH-ENCRYPTION].

10. PushMessageData interface

typedef object JSON;

[Exposed=ServiceWorker] interface PushMessageData { ArrayBuffer arrayBuffer (); Blob blob (); JSON 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. Exceptions thrown during the creation of the ArrayBuffer object are re-thrown.

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 (BufferSource or 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:
    BufferSource
    Set bytes to a copy of object's contents.
    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.

11.1 The push event

The PushEvent interface represents a received push message.

dictionary PushEventInit : ExtendableEventInit {
             PushMessageDataInit data;
};

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

Upon receiving a push message for a push subscription from the push service the user agent MUST run the following steps:

  1. Identify the Service Worker for the push subscription.
  2. If the Service Worker is not running, start it.
  3. Let scope be the ServiceWorkerGlobalScope of the Service Worker.
  4. Let subscription be the active push subscription for the Service Worker.
  5. Decrypt the push message using the private key from the key pair associated with subscription and the process described in [WEBPUSH-ENCRYPTION]. This produces the plain text of the message.
  6. If the push message could not be decrypted for any reason, or if it is not encrypted and contains any payload, discard the message and terminate this process. A push message MAY be empty if it contains no content, but otherwise push event MUST NOT be fired for a push message that was not successfully decrypted using the key pair associated with the push subscription.
  7. Let pushdata be the decrypted plain text of the push message.
  8. Let event be a new PushEvent, whose data attribute is a new PushMessageData with bytes set to the value of pushdata.
  9. Queue a task to fire event as a simple event named push at scope.

When a constructor of the PushEvent interface, or of an interface that inherits from the PushEvent interface, is invoked, the usual steps for constructing events MUST be modified as follows: instead of setting the data attribute of the event to the value of the eventInitDict's "data" member, set the data attribute to a new PushMessageData with bytes set to the result of extracting a byte sequence from that dictionary member, or an empty byte sequence if the "data" member is not provided.

11.2 The pushsubscriptionchange event

The pushsubscriptionchange event indicates that a push subscription has been invalidated, or will soon be invalidated. For example, the push service MAY set an expiration time. A Service Worker SHOULD attempt to resubscribe while handling this event, in order to continue receiving push messages.

When new push subscription information becomes available, the user agent MUST run the following steps:

  1. Let registration be the service worker registration corresponding to the push message.
  2. If registration is not found, abort these steps.
  3. Invoke the Handle Functional Event algorithm with a service worker registration of registration and callbackSteps set to the following steps:
    1. Set global to the global object that was provided as an argument.
    2. Create a trusted event, e, that uses the ExtendableEvent interface, with the event type pushsubscriptionchange, which does not bubble, is not cancelable, and has no default action.
    3. Dispatch e to global.
    4. If the previous push subscription is still active, perform the following steps in parallel:
      1. Set oldSubscription to the previous push subscription.
      2. Wait for all of the promises in the extend lifetime promises of e to either resolve or reject.
      3. Unsubscribe oldSubscription.

This algorithm ensures that the Service Worker is able to react to any non-destructive change in a push subscription, such as an automatic refresh, without causing any active push subscription to be terminated prematurely. A Service Worker can request a new push subscription during this process and ensure that no push messages are lost.

12. Enumerations

enum PushPermissionState {
    "granted",
    "denied",
    "prompt"
};
Enumeration Description
granted The webapp has permission to use the Push API.
denied The webapp has been denied permission to use the Push API.
prompt The webapp needs to ask for permission in order to use the Push API.

13. Exceptions

The Push API uses the following new DOMException names.

Name Description
PermissionDeniedError The operation failed because the user denied permission to use the API.

A. Acknowledgements

The editors would like to express their gratitude to the Mozilla and Telefónica Digital teams implementing the Firefox OS Push message solution and specially to Doug Turner, Nikhil Marathe, Fernando R. Sela, Guillermo López, Antonio Amaya, José Manuel Cantera and Albert Crespell, for their technical guidance, implementation work and support.

B. References

B.1 Normative references

[DOM]
Anne van Kesteren; Aryeh Gregor; Ms2ger; Alex Russell; Robin Berjon. W3C DOM4. 19 November 2015. W3C Recommendation. URL: http://www.w3.org/TR/dom/
[ECMASCRIPT]
ECMAScript Language Specification. URL: https://tc39.github.io/ecma262/
[ENCODING]
Anne van Kesteren; Joshua Bell; Addison Phillips. Encoding. 20 October 2015. W3C Candidate Recommendation. URL: http://www.w3.org/TR/encoding/
[FILEAPI]
Arun Ranganathan; Jonas Sicking. File API. 21 April 2015. W3C Working Draft. URL: http://www.w3.org/TR/FileAPI/
[HTML5]
Ian Hickson; Robin Berjon; Steve Faulkner; Travis Leithead; Erika Doyle Navara; Edward O'Connor; Silvia Pfeiffer. HTML5. 28 October 2014. W3C Recommendation. URL: http://www.w3.org/TR/html5/
[RFC2119]
S. Bradner. Key words for use in RFCs to Indicate Requirement Levels. March 1997. Best Current Practice. URL: https://tools.ietf.org/html/rfc2119
[SERVICE-WORKERS]
Alex Russell; Jungkee Song; Jake Archibald. Service Workers. 25 June 2015. W3C Working Draft. URL: http://www.w3.org/TR/service-workers/
[WEBIDL]
Cameron McCormack; Boris Zbarsky. WebIDL Level 1. 4 August 2015. W3C Working Draft. URL: http://www.w3.org/TR/WebIDL-1/
[WEBPUSH-ENCRYPTION]
Martin Thomson. Message Encryption for Web Push. Internet-Draft. URL: https://tools.ietf.org/html/draft-ietf-webpush-encryption
[WEBPUSH-PROTOCOL]
Martin Thomson; Brian Raymor. The Web Push Protocol. Internet-Draft. URL: https://tools.ietf.org/html/draft-ietf-webpush-protocol

B.2 Informative references

[NOTIFICATIONS]
Anne van Kesteren. Notifications API. Living Standard. URL: https://notifications.spec.whatwg.org/
[X9.62]
Public Key Cryptography for the Financial Services Industry, The Elliptic Curve Digital Signature Algorithm (ECDSA). ANS X9.62–2005.