Movatterモバイル変換

ThePush API enables sending of apush message to a web application via apush service. Anapplication server can send apush message at any time, even when a web application oruser agent is inactive. Thepush service ensures reliable and efficient delivery to theuser agent.Push messages are delivered to aService 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 theweb push protocol, which describes how anapplication server oruser agent interacts with apush service.

Introduction

The Push API allows a web application to communicate with auser agent asynchronously. This allows anapplication server to provide theuser 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 ofpush messages at any time.

In particular, apush 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 apush message is received. For example, apush message might be used to inform the user of an incoming WebRTC call.

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

The Push API will also ensure reliable delivery of push messages while auser 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 anapplication 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 theapplication server.

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

Dependencies

Theweb push protocol [[RFC8030]] describes a protocol that enables communication between auser agent orapplication server and apush 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.

TheContent-Encoding HTTP header, described in Section 8.4 of [[RFC9110]], indicates the content coding applied to the payload of apush message.

Concepts

          {            "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"            }          }

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

Security and privacy considerations

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

There is no guarantee that apush message was sent by anapplication server having the same origin as the web application. Theapplication server is able to share the details necessary to use apush 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 theapplication server's communication with the user.

The Push API may have to wake up the Service Worker associated with theservice worker registration in order to run the developer-provided event handlers. This can cause resource usage, such as network traffic, that theuser agent SHOULD attribute to the web application that created thepush subscription.

Theuser agent MAY consider thePushSubscriptionOptions when acquiring permission or determining the permission status.

When a permission is revoked, theuser agent MAYfire the "`pushsubscriptionchange`" event for subscriptions created with that permission, with theservice worker registration associated with thepush subscription as |registration|, a {{PushSubscription}} instance representing thepush subscription as |oldSubscription|, and `null` as |newSubscription|. Theuser agent MUSTdeactivate the affected subscriptions in parallel.

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

Thepush endpoint of adeactivatedpush subscription MUST NOT be reused for a newpush subscription. This prevents the creation of a persistent identifier that the user cannot remove. This also prevents reuse of the details of onepush subscription to sendpush messages to anotherpush subscription.

Push Framework

Apush message is sent from anapplication server to a web application as follows:

• theapplication server requests that thepush service deliver apush message using the [[RFC8030]]. This request uses thepush endpoint included in thepush subscription;
• thepush service delivers the message to a specificuser agent, identifying thepush endpoint in the message;
• theuser agent identifies the intendedService Worker and activates it as necessary, and delivers thepush message to theService Worker.

This overall framework allowsapplication servers to activate aService Worker in response to events at theapplication server. Information about those events can be included in thepush 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.

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

`PushManagerAttribute` mixin

This specifications extends the {{Window}} and {{ServiceWorkerRegistration}} objects through the {{PushManagerAttribute}} mixin. [[HTML]] [[SERVICE-WORKERS]]

        [SecureContext]        interface mixin PushManagerAttribute {          readonly attribute PushManager pushManager;        };        Window includes PushManagerAttribute;        ServiceWorkerRegistration includes PushManagerAttribute;

{{Window}} and {{ServiceWorkerRegistration}} objects have an associated {{PushManager}} object.

ThepushManager getter steps are to return [=this=]'s associated {{PushManager}} object.

On a {{Window}} object the {{PushManager}}'s [=PushManager/service worker registration=] is null.

On a {{ServiceWorkerRegistration}} object the {{PushManager}}'s [=PushManager/service worker registration=] is theservice worker registration represented by the {{ServiceWorkerRegistration}} object.

PushManager interface

The {{PushManager}} interface defines the operations to accesspush 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 = {});        };

A {{PushManager}} has an associatedservice worker registration which is null or aservice worker registration.

ThesupportedContentEncodings attribute exposes the sequence of supported content codings that can be used to encrypt the payload of apush message. A content coding is indicated using theContent-Encoding header field when requesting the sending of apush message from thepush 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

Thesubscribe() method steps are:

1. Let |promise| be [=a new promise=].
2. Let |global| be [=this=]'s [=relevant global object=].
3. Let |scope| be null.
4. Let |registration| be null.
5. If [=this=]'s [=PushManager/service worker registration=] is null:
   1. Set |scope| to the result of running the [=basic URL parser=] given "`/`" and |global|'sassociatedDocument's [=Document/URL=].
6. Otherwise:
   1. [=/Assert=]: [=this=]'s [=PushManager/service worker registration=] is a [=service worker registration=].
   2. Set |registration| to [=this=]'s [=PushManager/service worker registration=].
7. If |scope| is failure or is a [=/URL=] whose [=url/scheme=] is not "`https`", then [=queue a global task=] on the [=networking task source=] using |global| to [=reject=] |promise| with a {{"NotAllowedError"}} {{DOMException}} and terminate these steps.
8. If |options|["{{PushSubscriptionOptionsInit/userVisibleOnly}}"] is false and the user agent requires it to be true, then [=queue a global task=] on the [=networking task source=] using |global| to [=reject=] |promise| with a {{"NotAllowedError"}} {{DOMException}} and terminate these steps.
9. If |options|["{{PushSubscriptionOptionsInit/applicationServerKey}}"] is null and thepush service requires it to be non-null, then [=queue a global task=] on the [=networking task source=] using |global| to [=reject=] |promise| with a {{"NotSupportedError"}} {{DOMException}} and terminate these steps.
10. If |options|["{{PushSubscriptionOptions/applicationServerKey}}"] is non-null:
    1. If |options|["{{PushSubscriptionOptions/applicationServerKey}}"] is a string, then set its value to an {{ArrayBuffer}} containing the sequence of octets that result from decoding |options|["{{PushSubscriptionOptions/applicationServerKey}}"] using the base64url encoding [[RFC7515]].
    2. If decoding fails, then [=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|["{{PushSubscriptionOptions/applicationServerKey}}"] describes a valid point on the P-256 curve. If its value is invalid, then [=queue a global task=] on the [=networking task source=] using |global| to [=reject=] |promise| with an {{"InvalidAccessError"}} {{DOMException}} and terminate these steps.
11. Run these steps [=in parallel=]:
    1. Let |subscription| be null.
    2. If |scope| is non-null:
       1. If there is a [=push subscription=] with a [=push subscription/window-accessible scope=] whose [=push subscription/scope=] [=URL/equals=] |scope|, then set |subscription| to that [=push subscription=].
    3. Otherwise:
       1. [=/Assert=]: |registration| is non-null.
       2. If |registration|'s [=service worker registration/active worker=] is null, then [=queue a global task=] on the [=networking task source=] using |global| to [=reject=] |promise| with an {{"InvalidStateError"}} {{DOMException}} and terminate these steps.
       3. If |registration|'s [=associated push subscription=] is non-null, then set |subscription| to |registration|'s [=associated push subscription=].
       4. Set |scope| to |registration|'s [=service worker registration/scope URL=].
    4. Let |permission| be [=request permission to use=] "push".
    5. 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.
    6. If |subscription| is non-null:
       1. If there is an error with |subscription|, then [=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. [=Queue a global task=] on the [=networking task source=] using |global| to [=resolve=] |promise| with |subscription| and terminate these steps.
    7. [=/Assert=]: |subscription| is null and |scope| is a [=/URL=].
    8. Set |subscription| to 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 steps.
    9. Set |subscription|'s [=push subscription/scope=] to |scope|.
    10. [=Queue a global task=] on the [=networking task source=] using |global| to [=resolve=] |promise| with a {{PushSubscription}} corresponding to |subscription|.
12. Return |promise|.

ThegetSubscription() method steps are:

1. Let |promise| bea new promise.
2. Let |global| be [=this=]'s [=relevant global object=].
3. Let |windowScope| be null.
4. Let |registration| be null.
5. If [=this=]'s [=PushManager/service worker registration=] is null, then set |windowScope| to the result of running the [=basic URL parser=] given "`/`" and |global|'sassociatedDocument's [=Document/URL=].
6. Otherwise:
   1. [=/Assert=]: [=this=]'s [=PushManager/service worker registration=] is a [=service worker registration=].
   2. Set |registration| to [=this=]'s [=PushManager/service worker registration=].
7. Run these steps [=/in parallel=]:
   1. Let |subscription| be null.
   2. If |windowScope| is non-null:
      1. If there is a [=push subscription=] whose [=push subscription/scope=] is |windowScope|, then set |subscription| to that [=push subscription=].
   3. Otherwise:
      1. [=/Assert=]: |registration| is non-null.
      2. If |registration|'s [=associated push subscription=] is non-null, then set |subscription| to |registration|'s [=associated push subscription=].
   4. If |subscription| is null, then resolve |promise| with null.
   5. If there is an error with |subscription|, reject |promise| with a {{DOMException}} whose name is {{"AbortError"}} and terminate these steps.
   6. Resolve |promise| with a {{PushSubscription}} corresponding to |subscription|.
8. Return |promise|.

ThepermissionState() method when invoked MUST run the following steps:

1. Let |promise| bea 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 apush 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;        };

Whengetting the `endpoint` attribute, theuser agent MUST return thepush endpoint associated with thepush subscription. Theuser agent MUST use a serialization method that does not contain input-dependent branches (that is, one that is constant time).

Whengetting the `expirationTime` attribute, theuser agent MUST return thesubscription expiration time associated with thepush subscription if there is one, or `null` otherwise.

When getting theoptions attribute, theuser agent MUST return aPushSubscriptionOptions object representing the options associated with thepush subscription.

ThegetKey() 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 theuser agent to authenticate messages sent by anapplication 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]].

Theunsubscribe() method when invoked MUST run the following steps:

1. Let |promise| bea new promise.
2. Return |promise| and continue the following steps asynchronously.
3. If thepush subscription has already beendeactivated, resolve |promise| with `false` and terminate these steps.
4. Run the following step in parallel:
   1. Deactivate thepush subscription. Theuser agent MUST NOT deliver any furtherpush messages for thepush subscription.

      If theuser agent failed to request thepush service todeactivate thepush subscription, for example because of network failures, it SHOULD retry the request to thepush service for a reasonable amount of time.

5. Resolve |promise| with `true`.

ThetoJSON() 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}}. Theuser 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|.

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

Thekeys 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 associatedbytes (a [=byte sequence=]), which is set on creation.

ThearrayBuffer() 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.

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

Thebytes() 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.

Thejson() 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=].

Thetext() method steps are to return the result of runningUTF-8 decode on [=this=]'s [=bytes=].

Toextract 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 runningutf-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;              readonly attribute Notification? notification;            };            dictionary PushEventInit : ExtendableEventInit {              PushMessageDataInit? data = null;              Notification? notification = null;            };            typedef (BufferSource or USVString) PushMessageDataInit;

            [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

ThePush API does not provide any means itself to present data it receives from a [=push service=]. Instead, thePush API relies on other APIs – primarily the [[[NOTIFICATIONS]]] – to present received information to an end user. As such, there are no accessibility requirements for thePush 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: theuser 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.