推送 API

应用服务器一词指 Web 应用的服务端组件。

推送消息是从应用服务器发送到 Web 应用的数据。

推送消息会投递到与消息所提交的推送订阅相关联的活动 worker。如果 Service Worker 当前未运行，则会启动 worker 以进行消息投递。

声明式推送消息是一个推送消息，其数据为用户代理能够理解的 JSON 文档。用户代理会机会性地解析每个收到的 推送消息，以判断其是否为声明式推送消息，解析过程使用 声明式推送消息解析器。

声明式推送消息允许创建和显示通知，无需 Service Worker 的参与。当然，如果 应用服务器需要，Service Worker 仍可以参与。在这种情况下，推送消息的声明式属性可作为备用，例如 Service Worker 因存储压力被驱逐时。同时，这种方式为通知数据的传递提供了更面向对象的方案。

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

推送订阅是为 Web 应用在 用户代理与 推送服务之间建立的消息传递上下文。

推送订阅有一个关联的 scope（作用域），它是一个 URL。

当推送订阅的 scope的 path为 list，长度为 1，且 scope的 path[0]为空字符串时，认为其具有 窗口可访问作用域。

推送订阅有一个关联的 推送端点。 它必须是由 推送服务公开的绝对 URL， 应用服务器可向其发送 推送消息。 推送端点 必须唯一标识该 推送订阅。

推送订阅 可以有一个关联的 订阅过期时间。 设置时，它必须是自 1970 年 1 月 1 日 00:00:00 UTC 起的毫秒数，到该时间点订阅将被 停用。 用户代理 应当在订阅过期前尝试 刷新推送订阅。

推送订阅 有用于 P-256 ECDH 密钥对和认证密钥的内部槽，符合 [RFC8291]。 在创建推送订阅时，这些槽 必须被填充。

如果用户代理因任何原因需要更换 推送订阅的密钥， 且推送订阅的 关联 Service Worker 注册非空， 则必须 刷新 推送订阅。

要创建推送订阅，给定 PushSubscriptionOptionsInit optionsDictionary：

1. 令 subscription 为一个新建的 PushSubscription。
2. 令 options 为新建的 PushSubscriptionOptions 对象，属性由 optionsDictionary 的相应成员和值初始化。
3. 将 subscription 的 options 属性设置为 options。
4. 生成新的 P-256 ECDH 密钥对 [ANSI-X9-62]。 私钥存储在 subscription 的内部槽中，不得向应用公开。 公钥也存储于内部槽，可通过调用 getKey() 并传递参数 "p256dh" 获取。
5. 生成新的认证密钥，为一组八位字节序列，定义见 [RFC8291]。 认证密钥存储在 subscription 的内部槽中。 可通过调用 getKey() 并传递参数 "auth" 获取该密钥。
6. 请求新的 推送订阅。 如果设置了 applicationServerKey 属性，则一同发送。重新抛出任何 异常。
7. 当 推送订阅 请求成功完成时：
   1. 将 subscription 的 endpoint 属性设置为 推送订阅的 推送端点。
   2. 如果由 推送订阅提供，则设置 subscription 的 expirationTime。
8. 返回 subscription。

推送服务 指的是一种允许应用服务器向 Web 应用发送 推送消息的系统。 推送服务为其所服务的推送订阅 提供推送端点或 端点。

用户代理 会连接用于创建推送订阅的 推送服务。 用户代理 可以限制可用的推送服务的选择。 这样做的原因包括与性能相关的考虑，例如服务可用性（包括服务是否在特定国家或工作场所等网络被防火墙阻断）、可靠性、对电池寿命的影响，以及将元数据导向或避开特定 推送服务的协议等。

Push API 是一个被 强大功能识别的功能， 其名称为 "push"。

为了与Permissions规范集成， 本规范定义了 PushPermissionDescriptor 权限描述符类型。

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

userVisibleOnly 具有与 userVisibleOnly 相同的语义。

{name: "push", userVisibleOnly: false} 强于 {name: "push", userVisibleOnly: true}。

subscribe() 方法的步骤如下：

1. 令 promise 为 一个新的 promise。
2. 令 global 为 this 的 相关全局对象。
3. 令 scope 为 null。
4. 令 registration 为 null。
5. 如果 this 的 service worker 注册 为 null：
   1. 将 scope 设置为运行 基本 URL 解析器，参数为 "/" 和 global 的 关联 Document 的 URL 的结果。
6. 否则：
   1. 断言： this 的 service worker 注册 是一个 service worker 注册。
   2. 将 registration 设置为 this 的 service worker 注册。
7. 并行运行以下步骤：
   注意: 验证顺序在不同用户代理间可能不同
   1. 如果 scope 解析失败或其 URL 的 scheme 不是 "https"， 则在 networking task source 上， 使用 global 拒绝 promise，抛出 "NotAllowedError" DOMException。
   2. 如果 options 参数中的 userVisibleOnly 为 false，而用户代理要求必须为 true， 则拒绝 promise 并抛出 "NotAllowedError" DOMException。
   3. 如果 options 参数未包含 applicationServerKey 的非 null 值，且 推送服务 要求必须提供， 则拒绝 promise 并抛出 "NotSupportedError" DOMException。
   4. 如果 options 参数包含 applicationServerKey 属性：
      1. 如果 options 的 applicationServerKey 是 DOMString， 则其值为通过 base64url 解码得到的八位字节序列 [RFC7515]。
      2. 解码失败时，拒绝 promise 并抛出 "InvalidCharacterError" DOMException，终止后续步骤。
      3. 确保 options 的 applicationServerKey 描述的是 P-256 曲线上的有效点。无效则拒绝 promise 并抛出 "InvalidAccessError" DOMException，终止后续步骤。
   5. 令 subscription 为 null。
   6. 如果 scope 非 null：
      1. 如果存在一个 推送订阅， 且其 窗口可访问作用域 的 scope 等于 scope， 则将 subscription 设为该 推送订阅。
   7. 否则：
      1. 断言：registration 非 null。
      2. 如果 registration 的 active worker 为 null， 则拒绝 promise 并抛出 "InvalidStateError" DOMException，终止后续步骤。
      3. 如果 registration 的 关联推送订阅 非 null， 则将 subscription 设为 registration 的 关联推送订阅。
      4. 将 scope 设为 registration 的 scope URL。
   8. 令 permission 为 请求使用权限 "push"。
   9. 如果 permission 为 "denied"， 则拒绝 promise 并抛出 "NotAllowedError" DOMException，终止后续步骤。
   10. 如果 subscription 非 null：
       1. 如果 subscription 有错误，则拒绝 promise 并抛出 "AbortError" DOMException，终止后续步骤。
       2. 将 options 参数与 subscription 的 options 属性对比， BufferSource 的内容按值比较。
       3. 如果 options 的任一属性与 subscription 存储的不同， 则拒绝 promise 并抛出 "InvalidStateError" DOMException，终止后续步骤。
       4. 在 networking task source 上， 使用 global resolve promise，返回 subscription 并终止后续步骤。
   11. 断言：subscription 为 null，且 scope 是 URL。
   12. 将 subscription 设置为尝试用 options 创建推送订阅 的结果。如果抛出异常，则拒绝 promise 并抛出该异常，终止后续步骤。
   13. 将 subscription 的 scope 设为 scope。
   14. 在 networking task source 上， 使用 global resolve promise，返回一个与 subscription 对应的 PushSubscription。
8. 返回 promise。

getSubscription() 方法的步骤如下：

1. 令 promise 为 一个新的 promise。
2. 令 global 为 this 的 相关全局对象。
3. 令 windowScope 为 null。
4. 令 registration 为 null。
5. 如果 this 的 service worker 注册 为 null， 则将 windowScope 设置为运行 基本 URL 解析器， 参数为 "/" 和 global 的 关联 Document 的 URL 的结果。
6. 否则：
   1. 断言： this 的 service worker 注册 是一个 service worker 注册。
   2. 将 registration 设置为 this 的 service worker 注册。
7. 并行运行以下步骤：
   1. 令 subscription 为 null。
   2. 如果 windowScope 非 null：
      1. 如果存在一个 推送订阅， 且其 scope 为 windowScope， 则将 subscription 设为该 推送订阅。
   3. 否则：
      1. 断言： registration 非 null。
      2. 如果 registration 的 关联推送订阅 非 null， 则将 subscription 设为 registration 的 关联推送订阅。
   4. 如果 subscription 为 null，则 resolve promise 为 null。
   5. 如果 subscription 有错误，则 reject promise，抛出 DOMException， 名称为 "AbortError"，终止后续步骤。
   6. resolve promise，返回一个与 subscription 对应的 PushSubscription。
8. 返回 promise。

permissionState() 方法被调用时 必须运行以下步骤：

1. 令 promise 为 一个新的 promise。
2. 返回 promise，异步继续以下步骤。
3. 令 descriptor 为一个新的 PermissionDescriptor， 其 name 初始化为 "push"。
4. 令 state 为 descriptor 的 权限状态 及结果。
5. resolve promise 为 state。

使用推送服务的权限可以是持久的，即如果存在有效权限，则无需为后续订阅重新确认。

如果需要申请权限，应通过调用 subscribe() 方法完成。

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

userVisibleOnly 属性在获取时返回初始化值。

applicationServerKey 属性在获取时返回初始化值。

如果存在，applicationServerKey 的值必须包含一个 P-256 椭圆曲线上的点 [DSS]，采用 [ANSI-X9-62] 附录 A 描述的未压缩格式（即 65 字节，首字节为 0x04）。如以 DOMString 提供，则值必须用 [RFC7515] 的 base64url 编码。

当 applicationServerKey 不存在且 推送服务因运维需要要求时，用户代理可以拒绝订阅请求。

applicationServerKey 的值必须与用于消息加密的密钥不同 [RFC8291]。

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

userVisibleOnly 成员设置为 true 时，表示 推送订阅仅用于对用户可见效果的 推送消息，例如显示 Web 通知。[NOTIFICATIONS]

PushSubscriptionOptionsInit 表示与 推送订阅关联的附加选项。用户代理可以在向用户请求明确权限时考虑这些选项。如选项被考虑，用户代理应当在收到的 推送消息上强制执行相关约束。

这些选项是可选的，用户代理可以只支持其中一部分。用户代理不得暴露不支持的选项。

一旦设置，推送订阅的选项不可更改。已有的 推送订阅可通过 unsubscribe 退订，以创建带新选项的 推送订阅。

applicationServerKey 成员在与 推送服务建立 推送订阅时，由 用户代理使用。applicationServerKey 选项包含 应用服务器的椭圆曲线公钥。该密钥用于 应用服务器在向该 推送订阅发送 推送消息时进行身份验证，具体见 [RFC8292]；推送服务会拒绝未用对应私钥生成认证令牌的 推送消息。

用于 推送消息加密的密钥通过 getKey() 方法或 PushSubscription 的序列化器提供给 Web 应用。每个密钥都用 PushEncryptionKeyName 枚举中的值命名。

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

p256dh 用于获取 [RFC8291] 描述的 P-256 ECDH Diffie-Hellman 公钥。

auth 用于获取 [RFC8291] 中描述的认证密钥。

Service Worker 规范定义了 ServiceWorkerGlobalScope 接口 [SERVICE-WORKERS]，本规范对其进行了扩展。

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

onpush 属性是一个 事件处理器 IDL 属性， 其对应的 事件类型 为 "push"。"push" 事件表示 推送消息已被投递到 推送订阅。

onpushsubscriptionchange 属性是一个 事件处理器 IDL 属性， 对应的 事件类型为 "pushsubscriptionchange"。

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

当 PushEvent 接口或继承自该接口的接口的 constructor 被调用时，标准事件构造步骤会扩展如下：

1. 如果 eventInitDict 的 data 成员不存在，则将事件的 data 属性设为 null，结束步骤。
2. 令 b 为对 eventInitDict 的 "data" 成员 提取字节序列的结果。
3. 将事件的 data 属性设为新的 PushMessageData 实例，其 bytes 为 b。

data 属性必须返回初始化时的值。

notification 属性必须返回初始化时的值。

当用户代理从 推送服务 收到推送消息时， 必须执行以下步骤。

1. 令 subscription 为与该 推送消息 对应的活动推送订阅。

2. 令 registration 为 subscription 的 关联 Service Worker 注册。

3. 令 bytes 为 null。

4. 如果推送消息包含负载：

   1. 使用与 subscription 关联的密钥对中的私钥，并按照 [RFC8291] 所述过程， 解密推送消息的负载。 将 bytes 设为所得的字节序列。

   2. 如果由于任何原因无法解密推送消息的负载， 则确认该 推送消息，并中止后续步骤。

      注意

      未能通过与推送订阅关联的密钥对成功解密的 推送消息， 不会触发 push 事件。

5. 如果 bytes 非 null：

   1. 令 baseURL 为 subscription 的 scope。

   2. 令 origin 为 baseURL 的 origin。

   3. 令 fallbackTimestamp 为 当前粗粒度墙上时间。

   4. 令 declarativeResult 为运行 声明式推送消息解析器， 参数为 bytes、origin、baseURL 和 fallbackTimestamp 的结果。

   5. 如果 declarativeResult 非失败：

      1. 令 notification 为 declarativeResult 的 notification。

      2. 设置 notification 的 Service Worker 注册 为 registration。

      3. 令 notificationShown 为 false。

      4. 如果 declarativeResult 的 mutable 为 true 且 registration 非 null:

         1. 令 result 为 触发 push 事件的结果， 参数为 registration、null 和一个表示 notification 的新的 Notification 对象。

         2. 如果 result 非失败，则将 notificationShown 设为 result 的 notification shown。

      5. 如果 notificationShown 为 false，则按 通知显示步骤， 参数为 notification。

      6. 确认 推送消息，并中止后续步骤。

6. 如果 registration 为 null，则中止后续步骤。

7. 令 data 为一个新的 PushMessageData 对象， 其 bytes 为 bytes（如果 bytes 非 null），否则为 null。

8. 令 result 为 触发 push 事件的结果， 参数为 registration、data 和 null。

9. 如果 result 为失败，且同一个 推送消息 已多次投递给 Service Worker 注册且均未成功， 则确认 推送消息。

10. 如果 result 非失败，则确认 推送消息。

push 事件结果是一个元组，包含一个notification shown（一个 布尔值）。

触发 push 事件，参数为 Service Worker 注册 registration、 PushMessageData 对象或 null data， 以及 notification 或 null notification，步骤如下。返回失败或 push 事件结果。

1. 令 notificationResult 为 null。

2. 设置 registration 的 showNotification() 是否已成功调用 为 false。

3. 使用 PushEvent，在 registration 上 触发功能事件，事件名为 "push"，并设置如下属性：

   data

   data

   notification

   notification

   然后与 dispatchedEvent 并行执行：

   1. 等待 dispatchedEvent 的所有 延长生命周期 promise 都 resolve。

   2. 若未全部成功 resolve，则设置 notificationResult 为失败。

   3. 否则，设置 notificationResult 为 registration 的 showNotification() 是否已成功调用。

4. 等待 notificationResult 非 null。

5. 如果 notificationResult 为失败，则返回失败。

6. 断言：notificationResult 是 布尔值。

7. 返回 (notificationResult)。

确认推送消息，参数为 pushMessage 表示按照 [RFC8030] 确认收到 pushMessage。

确认 推送消息会让 推送服务停止投递该消息，并向 应用服务器报告成功。这能防止 推送消息被 推送服务无限重试投递。

确认意味着 应用服务器可能错误地收到投递成功的回执。因此，在确认前应当允许多次拒绝，建议至少允许三次尝试。

pushsubscriptionchange 事件表示 推送订阅发生了应用无法控制的变更，例如被刷新、撤销或丢失。

触发 "pushsubscriptionchange" 事件，参数为 Service Worker 注册 registration、newSubscription 和 oldSubscription，用户代理需要在 registration 上使用 PushSubscriptionChangeEvent 触发功能事件， 事件名为 "pushsubscriptionchange"，并设置如下属性：

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