Push API_link管理

link管理

链接快照平台

输入网页链接，自动生成快照
标签化管理网页链接

Status of This Document

This section describes the status of this document at the time of its publication. A list of current W3C publications and the latest revision of this technical report can be found in the W3C technical reports index at https://www.w3.org/TR/.

This document was published by the Web Applications Working Group as a Working Draft using the Recommendation track .

Publication as a Working Draft does not imply endorsement by W3C and its Members.

This is a draft document and may be updated, replaced or obsoleted by other documents at any time. It is inappropriate to cite this document as other than work in progress. This document was produced by a group operating under the W3C Patent Policy . W3C maintains a public list of any patent disclosures made in connection with the deliverables of the group; that page also includes instructions for disclosing a patent. An individual who has actual knowledge of a patent which the individual believes contains Essential Claim(s) must disclose the information in accordance with section 6 of the W3C Patent Policy . This document is governed by the 03 November 2023 W3C Process Document .

Introduction

This section is non-normative.

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 the user agent and the web application. Sending push messages requires considerably more resources when compared with more direct methods of communication such as the Fetch API or [ WebSockets ]. 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 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 :

Let subscription be a new


      PushSubscription

Let options be a newly created


      PushSubscriptionOptions

object, initializing its attributes with the corresponding members and values of optionsDictionary .

Set subscription 's


      options

attribute to options .

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

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

Request a new push subscription . Include the


      applicationServerKey

attribute of options when it has been set. Rethrow any exceptions .

When the push subscription request has completed successfully:

Set subscription 's


      endpoint

attribute to the push subscription 's push endpoint .

If provided by the push subscription , set subscription 's


      expirationTime

Return subscription .

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

3.3.2 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 name "push" . For integration with the Permissions specification, this specification defines the


            PushPermissionDescriptor

permission descriptor type .

WebIDL




    
dictionary PushPermissionDescriptor : PermissionDescriptor {
  boolean userVisibleOnly = false;
          The userVisibleOnly has the same semantics as
          userVisibleOnly.
          {name: "push", userVisibleOnly: false} is 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

This section is non-normative.


         
          A
         
         
          push message
         
         is sent from an
         
          application server
         
         to a web application as
        follows:
         
          the
          
           application server
          
          requests that the
          
           push service
          
          deliver a
          
           push
        message
          
          using the [
          
           
            RFC8030
           
          
          ]. This request uses the
          
           push endpoint
          
          included in
        the
          
           push subscription
          
          ;
         
         
          the
          
           push service
          
          delivers the message to a specific
          
           user agent
          
          ,
        identifying the
          
           push endpoint
          
          in the message;
         
         
          the
          
           user agent
          
          identifies the intended
          
           Service Worker
          
          and activates it as
        necessary, and delivers the
          
           push message
          
          to the
          
           Service Worker
          
          .
        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

This section is non-normative.


      
      
      
       Example
       
        1
       
      
      // 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
        This section is non-normative.
          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:
          The push endpoint of a PushSubscription is a URL that allows an
          application server to request delivery of a push message to a web
          application.
          
The getKey() method on a PushSubscription is used to
          retrieve keying material used to encrypt and authenticate push messages. Each
          invocation of the function returns a new ArrayBuffer that contains the value of the
          corresponding key, or null if the identified key doesn't exist. Passing a value of
          "p256dh" retrieves a elliptic curve
          Diffie-Hellman (ECDH) public key associated with the push subscription. Passing a
          value of auth returns an authentication secret that an application server uses in
          authentication of its messages. These keys are used by the application server to
          encrypt and authenticate messages for the push subscription, as described in
          [RFC8291].
        The Service Worker specification defines a ServiceWorkerRegistration interface
        [SERVICE-WORKERS], which this specification extends.
      WebIDL[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.
      WebIDL[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:
        Let promise be a new promise.
        
Let global be this' relevant global object.
        
Return promise and continue in parallel.
          Note: Validation order can vary across user agents

              Because of implementation-specific reasons, user agents are known to do some of the
              following checks in different order (e.g., some check if
              userVisibleOnly is allowed after validating the
              applicationServerKey, and vice versa). However, we
              don't believe this affects interoperability of implementations or web applications.
        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
        
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.
        
If the options argument includes a non-null value for the
        applicationServerKey attribute, run the following sub-steps:
            
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].
            
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.
            
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.
        
Let registration be this's associated service worker
        registration.
        
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.
        
Let permission be request permission to use "push".
        
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.
        
If registration has a push subscription:
            
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.
            
Compare the options argument with the options attribute of subscription. The
            contents of BufferSource values are compared for equality rather than
            reference.
            
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.
            
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.
        
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.
        
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:
        
Let promise be a new promise.
        
Return promise and continue the following steps asynchronously.
        
If the Service Worker is not subscribed, resolve promise with null.
        
Retrieve the push subscription associated with the Service Worker.
        
If there is an error, reject promise with a DOMException whose name is
        "AbortError" and terminate these steps.
        
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:
        
Let promise be a new promise.
        
Return promise and continue the following steps asynchronously.
        
Let descriptor be a new PermissionDescriptor with the
        name initialized to "push".
        
let state be the permission state of descriptor and the result.
        
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.
          PushSubscriptionOptions Interface
        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].
          PushSubscriptionOptionsInit dictionary
        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.
        PushSubscription interface
        A PushSubscription object represents a push subscription.
      WebIDL[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 getKey() is invoked the following
        process is followed:
        Find the internal slot corresponding to the key named by the name argument.
        
If a slot was not found, return null.
        
Initialize a variable key with a newly instantiated ArrayBuffer instance.
        
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 "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).
        
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.
        
Return key.
        Keys named "p256dh" and "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:
        
Let promise be a new promise.
        
Return promise and continue the following steps asynchronously.
        
If the push subscription has already been deactivated, resolve promise
        with false and terminate these steps.
        
Run the following step in parallel:
              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.
        
Let json be a new PushSubscriptionJSON dictionary.
        
Set json["endpoint"] to the result of getting the endpoint attribute of
        this.
        
Set json["expirationTime"] to the result of getting the expirationTime attribute of this.
        
Let keys be a new empty instance of record<DOMString, USVString> .
        
For each identifier i corresponding to keys in internal slots on the
        PushSubscription, ordered by the name of the key:
            
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 getKey()).
            
Otherwise, let b be the value as returned by getKey.
            
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.
            
Set keys[i] to s.
        
Set json["keys"] to keys.
        
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.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 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].
        PushMessageData interface
      WebIDL[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 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:
        Let bytes be an empty byte sequence.
        
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.
        
Return bytes.
        Events
          Extensions to the ServiceWorkerGlobalScope interface
          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".
          PushEvent Interface
        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:
          If eventInitDict's data member is not present, set the data attribute of the
          event to null and terminate these steps.
          
Set b to the result of extracting a byte
          sequence from the "data" member of eventInitDict.
          
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
        WebIDL




    
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.
          Let registration be the service worker registration corresponding to the 
            push message.
          
If registration is not found, abort these steps.
          
Let subscription be the active push subscription for registration.
          
Let bytes be null.
          
If the push message contains a payload:
              
Decrypt the push message 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.
              
If the push message payload could not be decrypted for any reason:
                  
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.
                  
Abort these steps.
                  A push event will not be fired for a push message that was not
                  successfully decrypted using the key pair associated with the push
                  subscription.
              
Wait for all of the promises in the extend lifetime promises
              of dispatchedEvent to resolve.
              
If all the promises resolve successfully, acknowledge the receipt of the push
              message according to [RFC8030] and abort these steps.
                  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
          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.
        10.5.1 
            PushSubscriptionChangeEvent Interface
          WebIDL[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.
        10.5.2 
            PushSubscriptionChangeEventInit Interface
          WebIDLdictionary 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.
        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 API Standard – 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.
    12. Conformance





    
As well as sections marked as non-normative, all authoring guidelines, diagrams, examples, and notes in this specification are non-normative. Everything else in this specification is normative.

        The key words MAY, MUST, MUST NOT, SHOULD, and SHOULD NOT in this document
        are to be interpreted as described in
        BCP 14
        [RFC2119] [RFC8174]
        when, and only when, they appear in all capitals, as shown here.
        This specification defines conformance criteria that apply to a single product: the
        user agent that implements the interfaces that it contains.
    
A. IDL Index
WebIDLdictionary PushPermissionDescriptor : PermissionDescriptor {
  boolean userVisibleOnly = false;
[SecureContext]
partial interface ServiceWorkerRegistration {
  readonly attribute PushManager pushManager;
[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 = {});
[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;
[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;
enum PushEncryptionKeyName {
  "p256dh",
  "auth"
[Exposed=ServiceWorker, SecureContext]
interface PushMessageData {
  ArrayBuffer




    
 arrayBuffer();
  Blob blob();
  Uint8Array bytes();
  any json();
  USVString text();
[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;
        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.
    [ANSI-X9-62]

      Public Key Cryptography for the Financial Services Industry, The Elliptic Curve Digital Signature Algorithm (ECDSA).  ANSI. 2005. URL: https://webstore.ansi.org/RecordDetail.aspx?sku=ANSI+X9.62%3a2005
    
[dom]

      DOM Standard. Anne van Kesteren.  WHATWG. Living Standard. URL: https://dom.spec.whatwg.org/
    
[DSS]

      FIPS PUB 186-5: Digital Signature Standard (DSS).  U.S. Department of Commerce/National Institute of Standards and Technology. 3 February 2023. National Standard. URL: https://nvlpubs.nist.gov/nistpubs/FIPS/NIST.FIPS.186-5.pdf
    
[ecmascript]

      ECMAScript Language Specification.  Ecma International. URL: https://tc39.es/ecma262/multipage/
    
[encoding]

      Encoding Standard. Anne van Kesteren.  WHATWG. Living Standard. URL: https://encoding.spec.whatwg.org/
    
[fileapi]

      File API. Marijn Kruisselbrink.  W3C. 24 May 2024. W3C Working Draft. URL: https://www.w3.org/TR/FileAPI/
    
[hr-time]

      High Resolution Time. Yoav Weiss.  W3C. 19 July 2023. W3C Working Draft. URL: https://www.w3.org/TR/hr-time-3/
    
[html]

      HTML Standard. Anne van Kesteren; Domenic Denicola; Ian Hickson; Philip Jägenstedt; Simon Pieters.  WHATWG. Living Standard. URL: https://html.spec.whatwg.org/multipage/
    
[infra]

      Infra Standard. Anne van Kesteren; Domenic Denicola.  WHATWG. Living Standard. URL: https://infra.spec.whatwg.org/
    
[NOTIFICATIONS]

      Notifications API Standard. Anne van Kesteren.  WHATWG. Living Standard. URL: https://notifications.spec.whatwg.org/
    
[Permissions]

      Permissions. Marcos Caceres; Mike Taylor.  W3C. 19 March 2024. W3C Working Draft. URL: https://www.w3.org/TR/permissions/
    
[RFC2119]

      Key words for use in RFCs to Indicate Requirement Levels. S. Bradner.  IETF. March 1997. Best Current Practice. URL: https://www.rfc-editor.org/rfc/rfc2119
    
[RFC4648]

      The Base16, Base32, and Base64 Data Encodings. S. Josefsson.  IETF. October 2006. Proposed Standard. URL: https://www.rfc-editor.org/rfc/rfc4648
    
[RFC7231]

      Hypertext Transfer Protocol (HTTP/1.1): Semantics and Content. R. Fielding, Ed.; J. Reschke, Ed..  IETF. June 2014. Proposed Standard. URL: https://httpwg.org/specs/rfc7231.html
    
[RFC7515]

      JSON Web Signature (JWS). M. Jones; J. Bradley; N. Sakimura.  IETF. May 2015. Proposed Standard. URL: https://www.rfc-editor.org/rfc/rfc7515
    
[RFC8030]

      Generic Event Delivery Using HTTP Push. M. Thomson; E. Damaggio; B. Raymor, Ed..  IETF. December 2016. Proposed Standard. URL: https://www.rfc-editor.org/rfc/rfc8030
    
[RFC8174]

      Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words. B. Leiba.  IETF. May 2017. Best Current Practice. URL: https://www.rfc-editor.org/rfc/rfc8174
    
[RFC8291]

      Message Encryption for Web Push. M. Thomson.  IETF. November 2017. Proposed Standard. URL: https://www.rfc-editor.org/rfc/rfc8291
    
[RFC8292]

      Voluntary Application Server Identification (VAPID) for Web Push. M. Thomson; P. Beverloo.  IETF. November 2017. Proposed Standard. URL: https://www.rfc-editor.org/rfc/rfc8292
    
[SERVICE-WORKERS]

      Service Workers. Jake Archibald; Marijn Kruisselbrink.  W3C. 12 July 2022. W3C Candidate Recommendation. URL: https://www.w3.org/TR/service-workers/
    
[WEBIDL]

      Web IDL Standard. Edgar Chen; Timothy Gu.  WHATWG. Living Standard. URL: https://webidl.spec.whatwg.org/
  
C.2 Informative references

    [Fetch]
      Fetch Standard. Anne van Kesteren.  WHATWG. Living Standard. URL: https://fetch.spec.whatwg.org/
    
[WEB-BACKGROUND-SYNC]

      Web Background Synchronization.  WICG. cg-draft. URL: https://wicg.github.io/background-sync/spec/
    
[WebSockets]

      WebSockets Standard. Adam Rice.  WHATWG. Living Standard. URL: https://websockets.spec.whatwg.org/
        Permalink
      Referenced in:
      § Abstract 
      § 5.3 Push service use 
      § 4. Security and privacy considerations (2) (3) (4) 
      § 5. Push Framework (2) (3) (4) 
      § 5.3 Push service use (2) (3) 
      § 7.3 PushSubscriptionOptionsInit dictionary (2) 
      § 8. PushSubscription interface 
      § 10.4 Receiving a Push Message (2) 
      § 10.5 The pushsubscriptionchange Event 
      § 7. PushManager interface (2) 
      § 7.3 PushSubscriptionOptionsInit dictionary (2) (3) (4) 
      § 8. PushSubscription interface 
      § 8.1 PushEncryptionKeyName enumeration 
      § 10.1 Extensions to the ServiceWorkerGlobalScope interface 
      § 10.3 PushEventInit dictionary 
      § 10.4 Receiving a Push Message (2) (3) (4) (5) (6) (7) (8) (9) (10) (11) (12) (13) (14) 
      § 3.2 Push message 
      § 3.3 Push subscription (2) (3) (4) (5) (6) (7) (8) (9) (10) (11) (12) (13) (14) 
      § 3.3.1 Subscription Refreshes (2) (3) (4) (5) (6) (7) (8) (9) (10) (11) (12) (13) 
      § 3.3.2 Subscription Deactivation (2) (3) (4) (5) 
      § 3.4 Push service (2) 
      § 4. Security and privacy considerations (2) (3) (4) (5) (6) (7) (8) (9) (10) 
      § 5. Push Framework 
      § 5.3 Push service use (2) 
      § 7.1 subscribe() method (2) (3) (4) 
      § 7.3 PushSubscriptionOptionsInit dictionary (2) (3) (4) (5) (6) (7) 
      § 8. PushSubscription interface (2) (3) (4) (5) (6) (7) (8) 
      § 10.1 Extensions to the ServiceWorkerGlobalScope interface 
      § 10.4 Receiving a Push Message (2) 
      § 10.5 The pushsubscriptionchange Event (2) 
      § 10.5.2 PushSubscriptionChangeEventInit Interface (2) (3) 
      § 6. Extensions to the ServiceWorkerRegistration Interface (2) 
      § 7. PushManager interface (2) 
      § A. IDL Index (2) 
      § 7.2 PushSubscriptionOptions Interface (2) (3) (4) 
      § 7.3 PushSubscriptionOptionsInit dictionary 
      § A. IDL Index 
      § 8. PushSubscription interface (2) (3) (4) (5) 
      § 8.1 PushEncryptionKeyName enumeration 
      § 10.5.1 PushSubscriptionChangeEvent Interface (2) 
      § 10.5.2 PushSubscriptionChangeEventInit Interface (2) 
      § A. IDL Index (2) (3) (4) (5) (6) (7) 
      § 10.5.1 PushSubscriptionChangeEvent Interface 
      § 10.5.2 PushSubscriptionChangeEventInit Interface 
      § A. IDL Index (2) 
      § 3.4 Push service (2) 
      § 4. Security and privacy considerations (2) (3) (4) (5) (6) (7) (8) 
      § 5. Push Framework (2) 
      § 7. PushManager interface 
      § 7.3 PushSubscriptionOptionsInit dictionary (2) (3) (4) (5) 
      § 8. PushSubscription interface (2) (3) (4) (5) (6) (7) (8) 
      § 10.3 PushEventInit dictionary 
      § 10.4 Receiving a Push Message