Push API

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

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

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 :

1. Let subscription be a new PushSubscription .
2. Let options be a newly created PushSubscriptionOptions object, initializing its attributes with the corresponding members and values of optionsDictionary .
3. Set subscription 's 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 getKey () method of the PushSubscription with an argument of " 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 getKey () method of the PushSubscription with an argument of " auth ".
6. Request a new push subscription . Include the 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 endpoint attribute to the URL provided by the push subscription .
   2. If provided by the push subscription , set subscription 's expirationTime .
8. Return subscription .

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 .

The Push API is a powerful feature identified by the name "push" .

For integration with the Permissions specification, this specification defines the PushPermissionDescriptor permission descriptor type .

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

The userVisibleOnly has the same semantics as userVisibleOnly .

{name: "push", userVisibleOnly: false} is stronger than {name: "push", userVisibleOnly: true} .

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

1. Let promise global be the relevant global object of this .
2. If global is a Window object:
   1. If global does not have transient activation , return a new promise rejected with with a " NotAllowedError " DOMException .
   2. Let Consume user activation of global .
3. Let promise be this ' relevant global object a new promise .
4. Return promise and continue in parallel .
   Note : Validation order can vary across user agents
5. If the options argument has a 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
6. If the options argument does not include a non-null value for the 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 .
7. If the options argument includes a non-null value for the applicationServerKey attribute, run the following sub-steps:
   1. If options 's applicationServerKey is a DOMString , set its value to an ArrayBuffer containing the sequence of octets that result from decoding options 's 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 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.
8. Let registration be this 's associated service worker registration .
9. If registration 's 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.
10. Let sw be registration 's active worker .
11. Let permission be request permission to use "push".
12. If permission is " denied ", queue a global task on the user interaction task source using global to reject promise with a " NotAllowedError " DOMException and terminate these steps.
13. 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 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.
14. Let subscription be the result of trying to create a push subscription with options . If creating the subscription 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.
15. 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 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 subscribe () method.

WebIDL[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 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 applicationServerKey is not present and the push service requires one for operational reasons.

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

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

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

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

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

WebIDL[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 ".

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

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

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

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

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