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

让已安装的 PWA 处理使用特定协议的链接，以提供更完整的体验。

Thomas Steiner

关于 scheme（也称为协议）的背景

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

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

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

registerProtocolHandler() 方法的背景

仅包含安全内容的 Navigator 方法 registerProtocolHandler() 可让网站注册其打开或处理特定网址 scheme 的权限。因此，网站需要按如下方式调用该方法：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 会自动在正确的范围内打开并显示幻灯片。
  • 在平台专用聊天应用中，聊天消息中的用户会收到指向 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"
    }
  ]
}

多个应用注册同一协议

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

同一应用注册多个协议

同一个应用可自行注册多个协议，如上述代码示例所示。

应用更新和处理程序注册

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

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

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

通过 Application > Manifest 窗格前往 Protocol Handlers（协议处理程序）部分。您可以在此处查看和测试所有可用协议。

例如，安装此演示 PWA。在协议处理程序部分中，输入“americano”，然后点击测试协议，在 PWA 中打开 Coffee 页面。

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

演示

您可以在 Glitch 上观看 PWA 的网址协议处理程序注册演示。

  1. 转到 https://protocol-handler.glitch.me/，安装 PWA，并在安装后重新加载应用。现在，浏览器已在操作系统中将 PWA 注册为 web+coffee 协议的处理程序。
  2. 在“已安装的 PWA”窗口中，点击链接 https://protocol-handler-link.glitch.me/。系统随即会打开一个包含三个链接的新浏览器标签页。点击第一个或第二个（拿铁玛奇朵或美式咖啡）。浏览器现在将显示一条提示，并询问您是否同意该应用作为 web+coffee 协议的协议处理程序。如果您同意，PWA 将打开并显示所选的咖啡。
  3. 如需与使用 navigator.registerProtocolHandler() 的传统流程进行比较，请点击 PWA 中的注册协议处理程序按钮。然后在浏览器标签页中点击第三个链接 (chai)。同样，该 PWA 也会显示提示，但随后会在标签页中打开 PWA，而不是在浏览器窗口中打开。
  4. 在平台专用应用（例如 Windows 上的 Skype）上向自己发送消息（使用 <a href="web+coffee://americano">Americano</a> 之类的链接），然后点击该链接。同样地，打开已安装的 PWA。

网址协议处理程序演示，其中浏览器标签页左侧是链接，右侧是独立 PWA 窗口。

安全注意事项

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

非用户发起的导航尝试

并非由用户启动但属于程序化的导航尝试可能无法打开应用。自定义协议网址只能用于顶级浏览上下文，但不能用作 iframe 的网址等。

协议许可名单

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

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

反馈

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

向我们介绍 API 设计

是否存在 API 无法正常运行的某些问题？或者说，是否缺少某些方法或属性来实现您的想法？如果您对安全模型有疑问或意见，在相应的 GitHub 代码库中提交规范问题，或将您的想法添加到现有问题中。

报告实施方面的问题

您是否发现了 Chromium 实现中存在的错误？或者，实现方式是否不同于规范？ 请在 new.crbug.com 提交 bug。请务必提供尽可能多的详细信息和简单的重现说明，并在组件框中输入 UI>Browser>WebAppInstalls。Glitch 非常适合快速轻松地分享重现的视频。

显示对该 API 的支持

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

请在 WICG Discourse 会话中说明您打算如何使用该工具。请使用 # 标签 #ProtocolHandler 向 @ChromiumDev 发送一条推文，并告诉我们您使用该推文的位置和方式。

致谢

PWA 的网址协议处理程序注册由 Microsoft Edge 团队的 Fabio Rocha、Diego González、Connor Moody 和 Samuel Tang 实现和指定。本文由 Joe Medley 和 Fabio Rocha 审核。主打图片由 JJ Ying 在 Unsplash 用户发布。