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.

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

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

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.

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 |permission| be [=request permission to use=] "push".
10. 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.
11. If |registration| has a push subscription:
    1. Let |subscription| be the result of obtaining |registration|'s push subscription. 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. 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=].
    3. 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.
    4. 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.
12. 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.
13. 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.

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

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

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.

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

PushMessageData interface

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

{{PushMessageData}} objects have an associated bytes (a [=byte sequence=]), which is set on creation.

The arrayBuffer() method steps are to return an {{ArrayBuffer}} whose contents are [=this=]'s [=bytes=]. Exceptions thrown during the creation of the {{ArrayBuffer}} object are re-thrown.

The blob() method steps are to return a new {{Blob}} object whose contents are [=this=]'s [=bytes=].

The bytes() method steps are to return a new {{Uint8Array}} backed by a {{ArrayBuffer}} whose contents are [=this=]'s [=bytes=]. Exceptions thrown during the creation of the {{ArrayBuffer}} object are re-thrown.

The json() method steps are to return the result of [=parse JSON bytes to a JavaScript value|parsing JSON bytes to a JavaScript value=] given [=this=]'s [=bytes=].

The text() method steps are to return the result of running UTF-8 decode on [=this=]'s [=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

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

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

            typedef (BufferSource or USVString) PushMessageDataInit;

            dictionary PushEventInit : ExtendableEventInit {
              PushMessageDataInit data;
            };
          

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

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

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.