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 declarative push message is a push message whose data is a JSON document that is understood by the user agent. A user agent opportunistically parses each incoming push message to determine if it is a declarative push message using the declarative push message parser .

A declarative push message allows for the creation and display of a notification without the involvement of a service worker. Nevertheless, a service worker can still be involved if desired by the application server . In such a scenario the declarative nature of the push message serves as a backup in case the service worker was evicted due to storage pressure, for instance. And also provides a more object-oriented approach to transmitting notification data.

{  "web_push": 8030,  "notification": {    "title": "Ada emailed ‘London’",    "lang": "en-US",    "dir": "ltr",    "body": "Did you hear about the tube strikes?",    "navigate": "https://email.example/message/12"  }
}

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 push subscription 's push endpoint .
   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 be a new promise .
2. Let global be this ' relevant global object .
3. Return promise and continue in parallel .
   Note : Validation order can vary across user agents
4. 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
5. 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 .
6. 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.
7. Let registration be this 's associated service worker registration .
8. 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.
9. Let permission be request permission to use "push".
10. 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.
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 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 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 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
};

  readonly attribute PushMessageData? data;
  readonly attribute Notification? notification;
  readonly attribute unsigned long long? appBadge;
};
dictionary PushEventInit : ExtendableEventInit {
  PushMessageDataInit? data = null;  Notification? notification = null;  unsigned long long? appBadge = null;
};
typedef

(

BufferSource

or

USVString

)

PushMessageDataInit

;

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 whose bytes set to is b .

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

The PushEventInit notification dictionary dictionary }; attribute must return the value it was initialized with.

The data appBadge member contains the data included in the push message when included and attribute must return the user agent verified its authenticity. The value will be set to null in all other cases. it was initialized with.

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. Let bytes be null.
5. If the push message contains a payload:
   1. Decrypt the push message 's payload using the private key from the key pair associated with subscription and the process described in [ RFC8291 ]. Set bytes to the resulting byte sequence .

   2. If the push message payload could not be decrypted for any reason: Acknowledge the receipt of reason, then acknowledge 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. Abort abort these steps.

      Note

      A push event will is not be fired for a push message that was not successfully decrypted using the key pair associated with the push subscription .

6. If bytes is non-null:

   1. Let baseURL be registration 's scope URL .

   2. Let origin be baseURL 's origin .

   3. Let fallbackTimestamp be current coarsened wall time .

   4. Let declarativeResult be the result of running the declarative push message parser given bytes , origin , baseURL , and fallbackTimestamp .

   5. If declarativeResult is not failure:

      1. Let notification be declarativeResult 's notification .

      2. Set notification 's service worker registration to registration .

      3. Let notificationShown be false.

      4. Let appBadgeSet be false.

      5. If declarativeResult 's mutable is true:

         1. Let result be the result of firing a push event given registration , null, a new Notification object representing notification , and declarativeResult 's app badge .

         2. If result is not failure, then set notificationShown to result 's notification shown and appBadgeSet to result 's app badge set .

      6. If notificationShown is false, then run the notification show steps given notification .

      7. If appBadgeSet is false, then w3c/badging #111 ...

      8. Acknowledge the push message and abort these steps.

7. Let data be a new PushMessageData object whose bytes is bytes if bytes is non-null; otherwise null.

8. Let result be the result of firing a push event given registration , data , null, and null.

9. If result is failure and the same push message has been delivered to a service worker registration multiple times unsuccessfully, then acknowledge the push message .

10. If result is not failure, then acknowledge the push message .

A push event result is a tuple consisting of a notification shown (a boolean ) and a app badge set (a boolean ).

To fire a push event given a service worker registration registration , PushMessageData object or null data , a notification or null notification , and an integer or null appBadge , run these steps. They return failure or a push event result .

1. Let notificationResult be null.

2. Let appBadgeResult be null.

3. Fire a functional event named " push " using PushEvent on registration with the following properties:

   data

   A new data

   PushMessageData notification object whose bytes

   notification

   appBadge is

   bytes . appBadge

   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 they do not resolve successfully, acknowledge the receipt of the push message according then set notificationResult and appBadgeResult to [ RFC8030 ] failure and abort these steps.

   3. If the same push message Set notificationResult to true if showNotification () has been delivered invoked; otherwise false.

   4. Set appBadgeResult to true if setAppBadge () has been invoked; otherwise false.

4. Wait for notificationResult and appBadgeResult to be non-null.

5. If notificationResult is failure, then return failure.

6. Assert : notificationResult and appBadgeResult are booleans .

7. Return ( notificationResult , appBadgeResult ).

To acknowledge a service worker registration push message given a push message multiple times unsuccessfully, pushMessage means to acknowledge the receipt of the push message pushMessage 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;
};