The Push API enables sending of a push message to a web application via a push service. An application server can send a push message at any time, even when a web application 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 web application, 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.

Introduction

The Push API allows a web application to communicate with a user agent asynchronously. This allows an application server to provide the user agent with time-sensitive information whenever that information becomes known, rather than waiting for a user to open the web application.

As defined here, push services support delivery of push messages at any time.

In particular, a push message will be delivered to the web application even if that web application is not currently active in a browser window: this relates to use cases in which the user may close the web application, but still benefits from the web application being able to be restarted when a push message is received. For example, a push message might be used to inform the user of an incoming WebRTC call.

A push message can also be sent when the user agent is temporarily offline. In support of this, the push service stores messages for the user agent until the user agent becomes available. This supports use cases where a web application learns of changes that occur while a user is offline and ensures that the user agent can be provided with relevant information in a timely fashion. Push messages are stored by the push service until the user agent becomes reachable and the message can be delivered.

The Push API will also ensure reliable delivery of push messages while a user agent is actively using a web application, for instance if a user is actively using the web application or the web application is in active communication with an application server through an active worker, frame, or background window. This is not the primary use case for the Push API. A web application might choose to use the Push API for infrequent messages to avoid having to maintain constant communications with the application server.

Push messaging is best suited to occasions where there is not already an active communications channel established between user agent and web application. Sending push messages requires considerably more resources when compared with more direct methods of communication such as the [[Fetch|Fetch API]] or [[Websockets|Web Sockets]]. Push messages usually have higher latency than direct communications and they can also be subject to restrictions on use. Most push services limit the size and quantity of push messages that can be sent.

Dependencies

The web push protocol [[RFC8030]] 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.

The Content-Encoding HTTP header, described in Section 3.1.2.2 of [[RFC7231]], indicates the content coding applied to the payload of a push message.

Concepts

Application server

The term application server refers to server-side components of a web application.

Push message

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

A push message is delivered to the [=service worker registration/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.

Push subscription

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

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.

A push subscription MAY have an associated subscription expiration time. When set, it MUST be the time, in milliseconds since 00:00:00 UTC on 1 January 1970, at which the subscription will be deactivated. The user agent SHOULD attempt to refresh the push subscription before the subscription expires.

A push subscription has internal slots for a P-256 ECDH key pair and an authentication secret in accordance with [[RFC8291]]. These slots MUST be populated when creating the push subscription.

If the user agent has to change the keys for any reason, it MUST fire the "`pushsubscriptionchange`" event with the service worker registration associated with the push subscription as |registration|, a {{PushSubscription}} instance representing the push subscription having the old keys as |oldSubscription| and a {{PushSubscription}} instance representing the push subscription having the new keys as |newSubscription|.

To create a push subscription, given an {{PushSubscriptionOptionsInit}} |optionsDictionary:PushSubscriptionOptionsInit|:

  1. Let |subscription:PushSubscription| be a new {{PushSubscription}}.
  2. Let |options:PushSubscriptionOptions| be a newly created {{PushSubscriptionOptions}} object, initializing its attributes with the corresponding members and values of |optionsDictionary|.
  3. Set |subscription|'s {{PushSubscription/options}} attribute to |options|.
  4. Generate a new P-256 ECDH key pair [[ANSI-X9-62]]. Store the private key in an internal slot on |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 {{PushSubscription/getKey()}} method of the {{PushSubscription}} with an argument of {{PushEncryptionKeyName/"p256dh"}}.
  5. Generate a new authentication secret, which is a sequence of octets as defined in [[RFC8291]]. Store the authentication secret in an internal slot on |subscription|. This key can be retrieved by calling the {{PushSubscription/getKey()}} method of the {{PushSubscription}} with an argument of {{PushEncryptionKeyName/"auth"}}.
  6. Request a new push subscription. Include the {{PushSubscriptionOptions/applicationServerKey}} attribute of |options| when it has been set. Rethrow any [=exceptions=].
  7. When the push subscription request has completed successfully:
    1. Set |subscription|'s {{PushSubscription/endpoint}} attribute to the [=URL=] provided by the push subscription.
    2. If provided by the push subscription, set |subscription|'s {{PushSubscription/expirationTime}}.
  8. Return |subscription|.

Subscription Refreshes

A user agent or push service MAY choose to refresh a push subscription at any time, for example because it has reached a certain age.

When this happens, the user agent MUST run the steps to create a push subscription given the PushSubscriptionOptions that were provided for creating the current push subscription. The new push subscription MUST have a key pair that's different from the original subscription.

When successful, user agent then MUST fire the "`pushsubscriptionchange`" event with the service worker registration associated with the push subscription as |registration|, a {{PushSubscription}} instance representing the initial push subscription as |oldSubscription| and a {{PushSubscription}} instance representing the new push subscription as |newSubscription|.

To allow for time to propagate changes to application servers, a user agent MAY continue to accept messages for an old push subscription for a brief time after a refresh. Once messages have been received for a refreshed push subscription, any old push subscriptions MUST be deactivated.

If the user agent is not able to refresh the push subscription, it SHOULD periodically retry the refresh. When the push subscription can no longer be used, for example because it has expired, the user agent MUST fire the "`pushsubscriptionchange`" event with the service worker registration associated with the push subscription as |registration|, a {{PushSubscription}} instance representing the deactivating push subscription as |oldSubscription| and `null` as the |newSubscription|.

Subscription Deactivation

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 is removed when service worker registration is cleared.

Push service

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

The user agent connects to the push service used to create push subscriptions. User agents MAY limit the choice of push services available. Reasons for doing so include performance-related concerns such as service availability (including whether services are blocked by firewalls in specific countries, or networks at workplaces and the like), reliability, impact on battery lifetime, and agreements to steer metadata to, or away from, specific push services.

Permission

The Push API is a [=powerful feature=] identified by the [=powerful feature/name=] "push".

For integration with the [[[Permissions]]] specification, this specification defines the {{PushPermissionDescriptor}} [=powerful feature/permission descriptor type=].

          dictionary PushPermissionDescriptor : PermissionDescriptor {
            boolean userVisibleOnly = false;
          };
        

The userVisibleOnly has the same semantics as {{PushSubscriptionOptionsInit/userVisibleOnly}}.

`{name: "push", userVisibleOnly: false}` is [=PermissionDescriptor/stronger than=] `{name: "push", userVisibleOnly: true}`.

Security and privacy considerations

The contents of a push message are encrypted [[RFC8291]]. However, the push service is still exposed to the metadata of messages sent by an application server to a user agent over a push subscription. This includes the timing, frequency and size of messages. Other than changing push services, which user agents may disallow, the only known mitigation is to increase the apparent message size by padding.

There is no guarantee that a push message was sent by an application server having the same origin as the web application. The application server is able to share the details necessary to use a push subscription with a third party at its own discretion.

The following requirements are intended to protect the privacy and security of the user as far as possible, and subject to meeting that goal, to protect the integrity of the application server's communication with the user.

User agents MUST NOT provide Push API access to web applications 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 Push API may have to wake up the Service Worker associated with the service worker registration in order to run the developer-provided event handlers. This can cause resource usage, such as network traffic, that the user agent SHOULD attribute to the web application that created the push subscription.

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

When a permission is revoked, the user agent MAY fire the "`pushsubscriptionchange`" event for subscriptions created with that permission, with the service worker registration associated with the push subscription as |registration|, a {{PushSubscription}} instance representing the push subscription as |oldSubscription|, and `null` as |newSubscription|. The user agent MUST deactivate the affected subscriptions in parallel.

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

The push endpoint MUST NOT expose information about the user to be derived by actors other than the push service, such as the user's device, identity or location. See the Privacy Considerations in [[RFC8030]] for the exact requirements.

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 only be available in a [=secure context=]. This 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.

Push Framework

A push message is sent from an application server to a web application 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 web application 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.

Example

          // https://example.com/serviceworker.js
          this.onpush = 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
          // inside an async function...
          try {
            const serviceWorkerRegistration = await navigator.serviceWorker.register(
              "serviceworker.js"
            );
            const pushSubscription = await serviceWorkerRegistration.pushManager.subscribe();
            // The push subscription details needed by the application
            // server are now available, and can be sent to it using,
            // for example, an XMLHttpRequest.
            console.log(pushSubscription.endpoint);
            console.log(pushSubscription.getKey("p256dh"));
            console.log(pushSubscription.getKey("auth"));
          } catch (err) {
            // In a production environment it might make sense to
            // also report information about errors back to the
            // application server.
            console.log(error);
          }
      

Sequence diagram

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

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:

Extensions to the `ServiceWorkerRegistration` Interface

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

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

PushManager interface

The {{PushManager}} interface defines the operations to access push services.

        [Exposed=(Window,Worker), SecureContext]
        interface PushManager {
          [SameObject] static readonly attribute FrozenArray<DOMString> supportedContentEncodings;

          Promise<PushSubscription> subscribe(optional PushSubscriptionOptionsInit options = {});
          Promise<PushSubscription?> getSubscription();
          Promise<PermissionState> permissionState(optional PushSubscriptionOptionsInit options = {});
        };
      

The supportedContentEncodings attribute exposes the sequence of supported content codings that can be used to encrypt the payload of a push message. A content coding is indicated using the Content-Encoding header field when requesting the sending of a push message from the push service.

User agents MUST support the `aes128gcm` content coding defined in [[RFC8291]], and MAY support content codings defined in previous versions of the draft for compatibility reasons.

`subscribe()` method

The subscribe() method when invoked MUST run the following steps:

  1. Let |promise| be [=a new promise=].
  2. Let |global| be [=this=]' [=relevant global object=].
  3. Return |promise| and continue [=in parallel=].
  4. If the |options| argument has a {{PushSubscriptionOptionsInit/userVisibleOnly}} value set to `false` and the user agent requires it to be `true`, [=queue a global task=] on the [=networking task source=] using |global| to [=reject=] |promise| {{"NotAllowedError"}} {{DOMException}}
  5. If the |options| argument does not include a non-null value for the {{PushSubscriptionOptionsInit/applicationServerKey}} member, and the push service requires one to be given, [=queue a global task=] on the [=networking task source=] using |global| to [=reject=] |promise| with a {{"NotSupportedError"}} {{DOMException}}.
  6. If the |options| argument includes a non-null value for the {{PushSubscriptionOptions/applicationServerKey}} attribute, run the following sub-steps:
    1. If |options|'s {{PushSubscriptionOptionsInit/applicationServerKey}} is a {{DOMString}}, set its value to an {{ArrayBuffer}} containing the sequence of octets that result from decoding |options|'s {{PushSubscriptionOptionsInit/applicationServerKey}} using the base64url encoding [[RFC7515]].
    2. If decoding fails, [=queue a global task=] on the [=networking task source=] using |global| to [=reject=] |promise| with an {{"InvalidCharacterError"}} {{DOMException}} and terminate these steps.
    3. Ensure that |options|'s {{PushSubscriptionOptionsInit/applicationServerKey}} describes a valid point on the P-256 curve. If its value is invalid, [=queue a global task=] on the [=networking task source=] using |global| to [=reject=] |promise| with an {{"InvalidAccessError"}} {{DOMException}} and terminate these steps.
  7. Let |registration:ServiceWorkerRegistration| be [=this=]'s associated service worker registration.
  8. If |registration|'s [=service worker registration/active worker=] is null, [=queue a global task=] on the [=networking task source=] using |global| to [=reject=] |promise| with an {{"InvalidStateError"}} {{DOMException}} and terminate these steps.
  9. Let |sw| be |registration|'s [=service worker registration/active worker=].
  10. Let |permission| be [=request permission to use=] "push".
  11. If |permission| is {{PermissionState/"denied"}}, [=queue a global task=] on the [=user interaction task source=] using |global| to [=reject=] |promise| with a {{"NotAllowedError"}} {{DOMException}} and terminate these steps.
  12. If |sw| is already subscribed, run the following sub-steps:
    1. Try to retrieve the push subscription associated with the |sw|. If there is an error, [=queue a global task=] on the [=networking task source=] using |global| to [=reject=] |promise| with an {{"AbortError"}} {{DOMException}} and terminate these steps.
    2. Let |subscription| be the push subscription associated with |sw|.
    3. Compare the |options| argument with the `options` attribute of |subscription|. The contents of {{BufferSource}} values are compared for equality rather than [=ECMAScript/reference record|reference=].
    4. If any attribute on |options| contains a different value to that stored for |subscription|, then [=queue a global task=] on the [=networking task source=] using |global| to [=reject=] |promise| with an {{"InvalidStateError"}} {{DOMException}} and terminate these steps.
    5. When the request has been completed, [=queue a global task=] on the [=networking task source=] using |global| to [=resolve=] |promise| with |subscription| and terminate these steps.
  13. Let |subscription| be the result of trying to [=create a push subscription=] with |options|. If creating the subscription [=exception/throws=] an [=exception=], [=queue a global task=] on the [=networking task source=] using |global| to [=reject=] |promise| with a that [=exception=] and terminate these these steps.
  14. Otherwise, [=queue a global task=] on the [=networking task source=] using |global| to [=resolve=] |promise| with a {{PushSubscription}} providing the details of the new |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. Let |descriptor| be a new {{PermissionDescriptor}} with the {{PermissionDescriptor/name}}} initialized to "push".
  4. let |state| be the [=permission state=] of |descriptor| and the result.
  5. Resolve |promise| with |state|.

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 {{PushManager/subscribe()}} method.

PushSubscriptionOptions Interface

          [Exposed=(Window,Worker), SecureContext]
          interface PushSubscriptionOptions {
            readonly attribute boolean userVisibleOnly;
            [SameObject] readonly attribute ArrayBuffer? applicationServerKey;
          };
        

The userVisibleOnly attribute, when getting, returns the value it was initialized with.

The applicationServerKey attribute, when getting, returns the value it was initialized with.

If present, the value of {{PushSubscriptionOptions/applicationServerKey}} MUST include a point on the P-256 elliptic curve [[DSS]], encoded in the uncompressed form described in [[ANSI-X9-62]] Annex A (that is, 65 octets, starting with an 0x04 octet). When provided as a {{DOMString}}, the value MUST be encoded using the base64url encoding [[RFC7515]].

User agents MAY reject a subscription attempt when {{PushSubscriptionOptions/applicationServerKey}} is not present and the push service requires one for operational reasons.

The {{PushSubscriptionOptions/applicationServerKey}} MUST be a different value to the one used for message encryption [[RFC8291]].

PushSubscriptionOptionsInit dictionary

          dictionary PushSubscriptionOptionsInit {
            boolean userVisibleOnly = false;
            (BufferSource or DOMString)? applicationServerKey = null;
          };
        

The userVisibleOnly member, 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]]

A PushSubscriptionOptionsInit 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.

These options are optional, and user agents MAY choose to support only a subset of them. A user agent MUST NOT expose options that it does not support.

Once set, options for a push subscription cannot change. A pre-existing push subscription can be unsubscribed, via {{PushSubscription/unsubscribe}}, to create a push subscription with new options.

The applicationServerKey member is used by the user agent when establishing a push subscription with a push service. The {{PushSubscriptionOptions/applicationServerKey}} option includes an elliptic curve public key for an application server. This is the key that the application server will use to authenticate itself when sending push messages to this push subscription as defined in [[RFC8292]]; the push service will reject any push message unless the corresponding private key is used to generate an authentication token.

PushSubscription interface

A {{PushSubscription}} object represents a push subscription.

        [Exposed=(Window,Worker), SecureContext]
        interface PushSubscription {
          readonly attribute USVString endpoint;
          readonly attribute EpochTimeStamp? expirationTime;
          [SameObject] readonly attribute PushSubscriptionOptions options;
          ArrayBuffer? getKey(PushEncryptionKeyName name);
          Promise<boolean> unsubscribe();

          PushSubscriptionJSON toJSON();
        };

        dictionary PushSubscriptionJSON {
          USVString endpoint;
          EpochTimeStamp? expirationTime = null;
          record<DOMString, USVString> keys;
        };
      

When getting the `endpoint` attribute, the user agent MUST return the push endpoint associated with the push subscription. The user agent MUST use a serialization method that does not contain input-dependent branches (that is, one that is constant time).

When getting the `expirationTime` attribute, the user agent MUST return the subscription expiration time associated with the push subscription if there is one, or `null` otherwise.

When getting the options attribute, the user agent MUST return a PushSubscriptionOptions object representing the options associated with the push subscription.

The getKey() method retrieves keying material that can be used for encrypting and authenticating messages. When {{PushSubscription/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, [[RFC8291]] specifies that the {{PushEncryptionKeyName/"p256dh"}} public key is encoded using the uncompressed format defined in [[ANSI-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 {{PushEncryptionKeyName/"p256dh"}} and {{PushEncryptionKeyName/"auth"}} MUST be supported, and their values MUST correspond to those necessary for the user agent to decrypt received push messages in accordance with [[RFC8291]].

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. Run the following step in parallel:
    1. Deactivate the push subscription. The user agent MUST NOT deliver any further push messages for the push subscription.

      If the user agent failed to request the push service to deactivate the push subscription, for example because of network failures, it SHOULD retry the request to the push service for a reasonable amount of time.

  5. Resolve |promise| with `true`.

The toJSON() method when invoked MUST run the following steps:

  1. Let |json:PushSubscriptionJSON| be a new {{PushSubscriptionJSON}} dictionary.
  2. Set |json|["endpoint"] to the result of [=getting the `endpoint` attribute=] of [=this=].
  3. Set |json|["expirationTime"] to the result of [=getting the `expirationTime` attribute=] of [=this=].
  4. Let |keys| be a new empty instance of `record<DOMString, USVString>` .
  5. 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 {{PushSubscription/getKey()}}).
    2. Otherwise, let |b| be the value as returned by {{PushSubscription/getKey}}.
    3. Let |s| be the URL-safe base64 encoding without padding [[RFC4648]] of |b| as a {{USVString}}. The user agent MUST use a serialization method that does not branch based on the value of |b|.
    4. Set |keys|[|i|] to |s|.
  6. Set |json|["keys"] to |keys|.
  7. Return |json|.

A PushSubscriptionJSON dictionary represents the JSON type of a {{PushSubscription}}. In ECMAScript this can be converted into a JSON string through the `JSON`.{{JSON/stringify()}} function.

The keys record contains an entry for each of the supported {{PushEncryptionKeyName}} entries to the URL-safe base64 encoded representation [[RFC4648]] of its value.

Note that the options to a {{PushSubscription}} are not serialized.

PushEncryptionKeyName enumeration

Encryption keys used for push message encryption are provided to a web application through the {{PushSubscription/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 [[RFC8291]].

The auth value is used to retrieve the authentication secret described in [[RFC8291]].

PushMessageData interface

        [Exposed=ServiceWorker, SecureContext]
        interface PushMessageData {
          ArrayBuffer arrayBuffer();
          Blob blob();
          any json();
          USVString text();
        };
      

PushMessageData objects have an associated [=byte sequence=] set on creation, which is `null` if there was no data in the push message.

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`.{{JSON/parse()}} with the result of running utf-8 decode on |bytes| as argument. Re-throw any exceptions thrown by `JSON`.{{JSON/parse()}}.

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

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

Events

Extensions to the `ServiceWorkerGlobalScope` interface

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

          [Exposed=ServiceWorker, SecureContext]
          partial interface ServiceWorkerGlobalScope {
            attribute EventHandler onpush;
            attribute EventHandler onpushsubscriptionchange;
          };
        

The onpush attribute is an event handler IDL attribute whose corresponding event handler event type is "`push`". The "`push`" event indicates that a push message has been received for a push subscription.

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

PushEvent Interface

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

When a constructor of the PushEvent interface, or of an interface that inherits from the PushEvent interface, is invoked, the usual event constructing steps are extended to include the following steps:

  1. If |eventInitDict|'s `data` member is not present, set the `data` attribute of the event to `null` and terminate these steps.
  2. Set |b| to the result of extracting a byte sequence from the "`data`" member of |eventInitDict|.
  3. Set the `data` attribute of the event to a new PushMessageData instance with `bytes` set to |b|.

The data, when getting, returns the value it was initialized with.

PushEventInit dictionary

            typedef (BufferSource or USVString) PushMessageDataInit;

            dictionary PushEventInit : ExtendableEventInit {
              PushMessageDataInit data;
            };
          

The data member contains the data included in the push message when included and the user agent verified its authenticity. The value will be set to `null` in all other cases.

Receiving a Push Message

When the user agent receives a push message from the push service, it 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. Let |subscription| be the active push subscription for |registration|.
  4. Initialize |data| to a value of `null`.
  5. If the push message contains a payload, perform the following steps:
    1. Decrypt the push message using the private key from the key pair associated with |subscription| and the process described in [[RFC8291]]. This produces the plain text of the message.
    2. If the push message could not be decrypted for any reason, perform the following steps:
      1. Acknowledge the receipt of the push message according to [[RFC8030]]. Though the message was not successfully received and processed, this prevents the push service from attempting to retransmit the message; a badly encrypted message is not recoverable.
      2. Discard the push message.
      3. Terminate this process.
      A `push` event MUST NOT be fired for a push message that was not successfully decrypted using the key pair associated with the push subscription.
    3. Let |data| be a new PushMessageData instance with the decrypted plain text of the push message.
  6. Fire a functional event named "`push`" using PushEvent on |registration| with the following properties:

    `data`
    |data|

    Then run the following steps in parallel, with |dispatchedEvent|:

    1. Wait for all of the promises in the [=ExtendableEvent/extend lifetime promises=] of |dispatchedEvent| to resolve.
    2. If all the promises resolve successfully, acknowledge the receipt of the push message according to [[RFC8030]] and abort these steps.
    3. If the same push message has been delivered to a service worker registration multiple times unsuccessfully, acknowledge the receipt of the push message according to [[RFC8030]].

      Acknowledging the push message causes the push service to stop delivering the message and to report success to the application server. This prevents the same push message from being retried by the push service indefinitely.

      Acknowledging also means that an application server could incorrectly receive a delivery receipt indicating successful delivery of the push message. Therefore, multiple rejections SHOULD be permitted before acknowledging; allowing at least three attempts is recommended.

The pushsubscriptionchange Event

The pushsubscriptionchange event indicates a change in a push subscription that was triggered outside of the application's control, for example because it has been refreshed, revoked or lost.

To fire the "`pushsubscriptionchange`" event given a service worker registration of |registration|, |newSubscription| and |oldSubscription|, the user agent must fire a functional event named "`pushsubscriptionchange`" using PushSubscriptionChangeEvent on |registration| with the following properties:

`newSubscription`
|newSubscription|
`oldSubscription`
|oldSubscription|

Consider using a more reliable synchronization mechanism such as [[WEB-BACKGROUND-SYNC]] when sending the details of the new push subscription to your application server. The user might be subject to unreliable network conditions that could cause a fetch to fail.

PushSubscriptionChangeEvent Interface

            [Exposed=ServiceWorker, SecureContext]
            interface PushSubscriptionChangeEvent : ExtendableEvent {
              constructor(DOMString type, optional PushSubscriptionChangeEventInit eventInitDict = {});
              readonly attribute PushSubscription? newSubscription;
              readonly attribute PushSubscription? oldSubscription;
            };
          

The newSubscription attribute, when getting, returns the value it was initialized to.

The oldSubscription attribute, when getting, returns the value it was initialized to.

PushSubscriptionChangeEventInit Interface

              dictionary PushSubscriptionChangeEventInit : ExtendableEventInit {
                PushSubscription newSubscription = null;
                PushSubscription oldSubscription = null;
              };
            

The newSubscription member details the push subscription that is valid per invocation of the pushsubscriptionchange event. The value will be `null` when no new push subscription could be established, for example because the web application has lost express permission.

The oldSubscription member details the push subscription that SHOULD NOT be used anymore. The value will be `null` when the user agent is not able to provide the full set of details, for example because of partial database corruption.

Accessibility

The Push API does not provide any means itself to present data it receives from a [=push service=]. Instead, the Push API relies on other APIs – primarily the [[[NOTIFICATIONS]]] – to present received information to an end user. As such, there are no accessibility requirements for the Push API itself. However, specifications such as [[NOTIFICATIONS]] provide guidance how to present notifications in an accessible manner.

Further, presenting an accessible interface might depend on transferring more information than a push message can convey. Push messages are best suited to carrying small amounts of content or identifiers. Any larger resources need to be fetched from servers.

This specification defines conformance criteria that apply to a single product: the user agent that implements the interfaces that it contains.

Acknowledgements

The editors would like to express their gratitude to the Mozilla and Telefónica Digital teams implementing the Firefox OS Push message solution, as well as to the following people who provided significant technical input to this document: Antonio Amaya, Miguel García Arribas, Ben Bangert, Kit Cambridge, José Manuel Cantera, JR Conlin, Albert Crespell, Matt Gaunt, Phil Jenvey, Guillermo López, Nikhil Marathe, John Mellor, Pınar Özlen, Fernando R. Sela, Shijun Sun and Doug Turner.