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/

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

关于 registerProtocolHandler() 方法的背景信息

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

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

该架构必须是 安全名单中的架构 之一（例如 mailto、bitcoin 或 magnet），或者以 web+ 开头，后跟至少一个或 多个小写 ASCII 字母（在 web+ 前缀之后），例如 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 注册为协议处理程序后，当用户从浏览器或平台专用应用点击具有特定架构（例如 mailto、bitcoin 或 web+music）的超链接时，注册的 PWA 将打开并接收该网址。请务必注意，建议的基于清单的注册和传统的 registerProtocolHandler() 在实践中发挥着非常相似的作用，同时仍允许提供补充用户体验的可能性：

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

使用场景

  • 在字处理 PWA 中，用户在文档中遇到指向演示文稿的链接，例如 web+presentations://deck2378465。当用户点击该链接时，演示文稿 PWA 会在正确的范围内自动打开并显示幻灯片。
  • 在平台专用聊天应用中，用户在聊天消息中收到指向 magnet 网址的链接。 点击该链接后，已安装的 Torrent 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 协议）的处理程序，操作系统将向用户显示选择器，并让用户决定使用哪个注册的处理程序。

同一应用注册多个协议

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

应用更新和处理程序注册

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

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

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

使用应用 > 清单 面板导航到 Protocol Handlers （协议处理程序）部分。您可以在此处查看和测试所有可用的协议。

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

安全注意事项

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

非用户发起的导航尝试

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

协议许可名单

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

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

反馈

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

向我们介绍 API 设计

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

报告实现方面的问题

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

表示对 API 的支持

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

在 WICG Discourse 帖子中分享您打算如何使用它。使用主题标签 #ProtocolHandler 向 @ChromiumDev发送推文，让我们了解您在何处以及如何使用它。

致谢

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