推送 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]。

如果用户代理出于任何原因必须更改某个推送订阅的密钥 且该推送订阅的关联的服务工作线程注册 非 null， 则它必须刷新该推送 订阅。

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

1. 令subscription为一个新的PushSubscription。
2. 令options为一个新创建的PushSubscriptionOptions 对象，并使用 optionsDictionary中对应的成员和值初始化其属性。
3. 将subscription的options属性设置为options。
4. 将subscription的P-256 ECDH 密钥对设置为生成一个新的 P-256 ECDH 密钥对的结果 [ANSI-X9-62]。
5. 将subscription的身份验证秘密设置为生成一个 新的 身份验证秘密的结果，该秘密是 [RFC8291] 第 3.2 节中定义的八位字节序列。
6. 请求一个新的推送订阅。当其已被 设置时，包括options的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 的服务工作线程注册为 null：
   1. 将 scope 设置为运行基本 URL 解析器的结果，给定 "/" 和 global 的关联的 Document 的URL。
6. 否则：
   1. 断言：this 的服务工作线程 注册是一个服务 工作线程注册。
   2. 将 registration 设置为this 的服务工作线程 注册。
7. 如果 scope 为失败或为一个URL，且其方案不是 "https"， 则 将一个全局 任务排入队列，在网络 任务源上使用 global 来拒绝 promise，并带有一个 "NotAllowedError" DOMException，然后 终止这些步骤。
8. 如果 options["userVisibleOnly"] 为 false 且用户 代理要求其为 true，则将一个全局 任务排入队列，在网络 任务源上使用 global 来拒绝 promise，并带有一个 "NotAllowedError" DOMException，然后 终止这些步骤。
9. 如果 options["applicationServerKey"] 为 null 且 推送服务要求其非 null，则将一个全局 任务排入队列，在 网络 任务源上使用 global 来拒绝 promise，并带有一个 "NotSupportedError" DOMException，然后 终止这些步骤。
10. 如果 options["applicationServerKey"] 非 null：
    1. 如果 options["applicationServerKey"] 是字符串，则 将其值设置为一个ArrayBuffer， 其中包含通过 使用 base64url 编码 [RFC7515] 解码 options["applicationServerKey"] 所得到的八位字节序列。
    2. 如果解码失败，则将 一个全局任务排入队列，在网络 任务源上 使用 global 来拒绝 promise，并带有一个 "InvalidCharacterError" DOMException ，然后终止这些步骤。
    3. 确保 options["applicationServerKey"] 描述 P-256 曲线上的一个有效点。如果其值无效，则将 一个全局任务排入队列 到网络 任务源上，使用 global 来拒绝 promise，并带有一个 "InvalidAccessError" DOMException ，然后终止这些步骤。
11. 并行运行这些步骤：
    1. 令 subscription 为 null。
    2. 如果 scope 非 null：
       1. 如果存在一个推送订阅， 它具有一个窗口可访问 作用域，且其作用域 等于 scope，则将 subscription 设置为该推送订阅。
    3. 否则：
       1. 断言： registration 非 null。
       2. 如果 registration 的活动 工作线程为 null，则 将 一个全局任务排入队列，在网络 任务源上使用 global 来 拒绝 promise，并带有一个 "InvalidStateError" DOMException ，然后终止 这些步骤。
       3. 如果 registration 的关联的推送订阅 非 null，则将 subscription 设置为 registration 的关联的 推送订阅。
       4. 将 scope 设置为 registration 的作用域 URL。
    4. 令 permission 为请求 使用权限 "push" 的结果。
    5. 如果 permission 为 "denied"， 则将 一个全局任务排入队列，在 用户 交互任务源上使用 global 来拒绝 promise，并带有一个 "NotAllowedError" DOMException ，然后终止这些步骤。
    6. 如果 subscription 非 null：
       1. 如果 subscription 存在错误，则将 一个全局任务排入队列，在 网络 任务源上使用 global 来拒绝 promise，并带有 一个 "AbortError" DOMException ，然后终止这些步骤。
       2. 将 options 参数与 subscription 的 options 属性进行比较。 BufferSource 值的内容按相等性进行比较，而不是按 引用进行比较。
       3. 如果 options 上的任何属性所包含的值与为 subscription 存储的值不同，则将 一个全局任务排入队列，在网络 任务源上 使用 global 来拒绝 promise，并带有 一个 "InvalidStateError" DOMException ，然后终止这些步骤。
       4. 将 一个全局任务排入队列，在网络 任务源上使用 global 来 兑现 promise，其值为 subscription，然后终止这些步骤。
    7. 断言： subscription 为 null，且 scope 是一个URL。
    8. 将 subscription 设置为尝试使用 options 创建推送订阅的结果。如果创建订阅抛出一个异常，则将 一个全局任务排入队列，在网络 任务源上使用 global 来拒绝 promise，并带有该异常，然后终止这些 步骤。
    9. 将 subscription 的作用域设置为 scope。
    10. 将 一个全局任务排入队列，在网络 任务源上使用 global 来 兑现 promise，其值为与 subscription 对应的PushSubscription。
12. 返回 promise。

getSubscription() 方法的步骤如下：

1. 令 promise 为一个新 promise。
2. 令 global 为this 的相关 全局对象。
3. 令 windowScope 为 null。
4. 令 registration 为 null。
5. 如果this 的服务工作线程注册为 null，则将 windowScope 设置为运行基本 URL 解析器的结果，给定 "/" 和 global 的 关联的 Document 的URL。
6. 否则：
   1. 断言：this 的服务工作线程 注册是一个服务 工作线程注册。
   2. 将 registration 设置为this 的服务工作线程 注册。
7. 并行运行这些步骤：
   1. 令 subscription 为 null。
   2. 如果 windowScope 非 null：
      1. 如果存在一个推送订阅， 其作用域是 windowScope，则将 subscription 设置为该推送订阅。
   3. 否则：
      1. 断言： registration 非 null。
      2. 如果 registration 的关联的推送订阅 非 null，则将 subscription 设置为 registration 的关联的 推送订阅。
   4. 如果 subscription 为 null，则以 null 兑现 promise。
   5. 如果 subscription 存在错误，则拒绝 promise，并带有一个DOMException， 其名称为 "AbortError"，然后 终止这些步骤。
   6. 以与 subscription 对应的PushSubscription兑现 promise。
8. 返回 promise。

permissionState() 方法的步骤如下：

1. 令 promise 为一个新的 promise。

2. 令 global 为this的相关全局对象。

3. 并行执行：

   1. 令 state 为 "push" 的权限状态。

   2. 在 网络任务源上，使用 global 排队一个全局任务，以 state 解决 promise。

4. 返回 promise。

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

如果需要申请权限，应通过调用 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 提供， 该值 必须 使用 base64url 编码 [RFC7515]。

当 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 接口或继承自 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 和 null。

         注

         由于不存在环境 设置对象，因此传入 null。这也 确保 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" 事件，给定一个服务工作线程 注册 registration、newSubscription 和 oldSubscription，用户 代理必须触发一个功能事件 ，名称为 "pushsubscriptionchange"，并使用 PushSubscriptionChangeEvent 在 registration 上设置以下属性：

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