PWA 的网址协议处理程序注册

让已安装的 PWA 处理使用特定协议的链接，以获得更集成的体验。

Thomas Steiner

关于架构（也称为协议）的背景信息

统一资源标识符 (URI) 是标识抽象或物理资源的紧凑字符序列。每个 URI 都以一个方案名称开头，该名称是指用于在该方案中分配标识符的规范。因此，URI 语法是一个联合且可扩展的命名系统，其中每个方案的规范可能会进一步限制使用该方案的标识符的语法和语义。架构也称为协议。您可以查看一些架构示例。

tel:+1-816-555-1212
mailto:Jane.Doe@example.com
news:comp.infosystems.www.servers.unix
https://web.dev/

统一资源定位符 (URL) 一词是指 URI 的子集，除了标识资源之外，还通过描述其主要访问机制（例如其网络位置）来提供定位资源的方法。

registerProtocolHandler() 方法的背景信息

仅限安全内容的 Navigator 方法 registerProtocolHandler() 可让网站注册其打开或处理特定网址协议的能力。因此，网站需要按如下方式调用该方法：navigator.registerProtocolHandler(scheme, url)。这两个参数的定义如下：

  • scheme：一个字符串，包含网站希望处理的协议。
  • url：包含处理程序网址的字符串。此网址必须包含 %s，作为占位符，它将被替换为要处理的转义网址。

该架构必须是列入许可名单的架构之一（例如 mailto、bitcoin 或 magnet），或者以 web+ 开头，后跟 web+ 前缀后至少一个或多个小写 ASCII 字母，例如 web+coffee。

为了更清楚地了解这一点，下面提供了一个具体流程示例：

  1. 用户访问 https://coffeeshop.example.com/ 处的网站，该网站会发出以下调用：navigator.registerProtocolHandler('web+coffee', 'coffee?type=%s')。
  2. 稍后，在访问 https://randomsite.example.com/ 时，用户点击了 <a href="web+coffee:latte-macchiato">All about latte macchiato</a> 等链接。
  3. 这会导致浏览器转到以下网址：https://coffeeshop.example.com/coffee?type=web%2Bcoffee%3A%2F%2Flatte-macchiato。经过网址解码的搜索字符串随后会显示为 ?type=web+coffee://latte-macchiato。

协议处理的用途

目前的 PWA 的网址协议处理程序注册机制旨在通过 PWA 的清单提供协议处理程序注册，作为 PWA 安装的一部分。将 PWA 注册为协议处理程序后，当用户在浏览器或特定于平台的应用中点击具有特定架构（例如 mailto、bitcoin 或 web+music）的超链接时，已注册的 PWA 将打开并接收网址。请务必注意，在实践中，建议的基于清单的注册和传统的 registerProtocolHandler() 扮演着非常相似的角色，同时仍有可能提供互补的用户体验：

  • 相似之处包括：允许注册的架构列表、参数的名称和格式等方面的要求。
  • 基于清单的注册方式存在细微差异，但可能有助于提升 PWA 用户的体验。例如，基于清单的 PWA 注册可能不需要用户执行额外操作，只需用户发起 PWA 安装即可。

使用场景

  • 在文字处理 PWA 中，用户在文档中遇到了一个指向演示文稿的链接，例如 web+presentations://deck2378465。当用户点击该链接时，演示文稿 PWA 会自动在正确的范围内打开并显示幻灯片。
  • 在特定于平台的 Chat 应用中，聊天消息中的用户会收到一个指向 magnet 网址的链接。 点击该链接后，已安装的种子 PWA 会启动并开始下载。
  • 用户安装了音乐在线播放 PWA。当朋友分享歌曲链接（例如 web+music://songid=1234&time=0:13）且用户点击该链接时，音乐在线播放 PWA 将自动在独立窗口中启动。

如何为 PWA 使用网址协议处理程序注册

网址协议处理程序注册 API 与 navigator.registerProtocolHandler() 非常相似。只是这次，信息是通过 Web 应用清单以声明方式传递的，该清单包含一个名为 "protocol_handlers" 的新属性，该属性接受一个对象数组，其中包含两个必需的键 "protocol" 和 "url"。以下代码段展示了如何注册 web+tea 和 web+coffee。这些值是包含处理程序网址的字符串，其中包含转义网址所需的 %s 占位符。

{
  "protocol_handlers": [
    {
      "protocol": "web+tea",
      "url": "/tea?type=%s"
    },
    {
      "protocol";: "web+coffee",
      "url": "/coffee?type=%s"
    }
  ]
}

多个应用注册同一协议

如果多个应用将自身注册为同一架构（例如 mailto 协议）的处理程序，操作系统会向用户显示一个选择器，让用户决定使用哪个已注册的处理程序。

同一应用注册多个协议

如代码示例所示，同一应用可以针对多个协议进行注册。

应用更新和处理程序注册

处理程序注册会与应用提供的最新清单版本同步。有两种情况：

  • 添加新处理程序的更新会触发处理程序注册（与应用安装分开）。
  • 移除处理程序的更新会触发处理程序取消注册（与应用卸载分开）。

开发者工具中的协议处理程序调试

使用应用 > 清单窗格前往协议处理程序部分。您可以在此处查看和测试所有可用的协议。

“清单”窗格中的协议处理程序

安全注意事项

由于 PWA 安装要求上下文安全，因此协议处理会继承此限制。已注册的协议处理程序列表不会以任何方式向网络公开，因此无法用作指纹向量。

非用户发起的导航尝试

非用户发起而是通过程序化方式发起的导航尝试可能无法打开应用。自定义协议网址只能在顶级浏览上下文中使用，而不能用作 iframe 的网址。

协议许可清单

与 registerProtocolHandler() 一样，应用可以注册处理的协议也有许可清单。

由于调用的协议，PWA 首次启动时，系统会向用户显示一个权限对话框。此对话框会显示应用的名称和来源，并询问用户是否允许该应用处理来自该协议的链接。如果用户拒绝权限对话框，操作系统将忽略已注册的协议处理程序。如需取消注册协议处理程序，用户需要卸载注册该协议处理程序的 PWA。如果用户选择“记住我的选择”并选择“不允许”，浏览器也会取消注册协议处理程序。

反馈

Chromium 团队希望了解您对 PWA 的网址协议处理程序注册的体验。

请向我们介绍 API 设计

API 是否有某些方面未按预期运行？或者，是否缺少实现您的想法所需的方法或属性？对安全模型有疑问或意见？在相应的 GitHub 代码库中提交规范问题，或将您的想法添加到现有问题中。

报告实现方面的问题

您是否发现了 Chromium 实现中的 bug？还是实现与规范不同？ 在 new.crbug.com 上提交 bug。请务必尽可能多地提供详细信息和重现说明，并在组件框中输入 UI>Browser>WebAppInstalls。

显示对 API 的支持

您是否打算为 PWA 使用网址协议处理程序注册？您的公开支持有助于 Chromium 团队确定功能的优先级，并向其他浏览器供应商展示支持这些功能的重要性。

在 WICG Discourse 讨论帖中分享您打算如何使用该 API。使用 #ProtocolHandler 标签向 @ChromiumDev 发送推文，让我们知道您在何处以及如何使用它。

致谢

PWA 的网址协议处理程序注册由 Microsoft Edge 团队的 Fabio Rocha、Diego González、Connor Moody 和 Samuel Tang 实现和指定。本文档由 Joe Medley 和 Fabio Rocha 审核。