PWA 用作网址处理程序

让已安装的 PWA 处理网址，以获得更集成的体验。

Thomas Steiner

什么是将 PWA 用作网址处理程序？

假设您在 macOS 上使用“信息”等即时通讯应用与好友聊天，并谈论音乐。再假设你们两人设备上都安装了 music.example.com PWA。如果您想分享自己喜爱的曲目，让好友也能欣赏，可以向对方发送 https://music.example.com/rick-astley/never-gonna-give-you-up 等深层链接。由于此链接非常长，music.example.com 的开发者可能决定为每个曲目额外添加一个短链接，例如 https://🎵.example.com/r-a/n-g-g-y-u。

借助 PWA 作为网址处理程序，music.example.com 等应用可以将自己注册为与 https://music.example.com、https://*.music.example.com 或 https://🎵.example.com 等模式匹配的网址的网址处理程序，以便来自 PWA 外部（例如来自即时通讯应用或电子邮件客户端）的链接在已安装的 PWA 中打开，而不是在浏览器标签页中打开。

PWA 作为网址处理程序由两项新增功能组成：

1. "url_handlers" Web 应用清单成员。
2. 用于验证范围内和范围外的网址关联的 web-app-origin-association 文件格式。

将 PWA 用作网址处理程序的建议用例

可能使用此 API 的网站示例包括：

• 音乐或视频在线播放网站，以跟踪在应用的播放器体验中打开的链接或播放列表链接。
• 新闻或 RSS 阅读器会在应用的阅读器模式下打开已关注或订阅的网站。

如何将 PWA 用作网址处理程序

通过 about://flags 启用

如需在没有源试用令牌的情况下在本地试用 PWA 作为网址处理程序，请在 about://flags 中启用 #enable-desktop-pwas-url-handling 标志。

"url_handlers" 网络应用清单成员

如需将已安装的 PWA 与网址格式相关联，需要在 Web 应用清单中指定这些格式。这通过 "url_handlers" 成员完成。它接受具有 origin 属性的对象数组，该属性是必需的 string，用于匹配来源。这些模式可以包含通配符 (*) 前缀，以便包含多个子网域（例如 https://*.example.com）。与这些来源匹配的网址可以由此 Web 应用处理。scheme 始终假定为 https://，但需要明确提及。

以下 Web 应用清单摘录展示了介绍段落中的音乐 PWA 示例如何进行此设置。使用通配符 ("https://*.music.example.com") 的第二个条目可确保应用也针对 https://www.music.example.com 或可能的其他示例（如 https://marketing-activity.music.example.com）激活。

{
  "url_handlers": [
    {
      "origin": "https://music.example.com"
    },
    {
      "origin": "https://*.music.example.com"
    },
    {
      "origin": "https://🎵.example.com"
    }
  ]
}

web-app-origin-association 文件

由于 PWA 位于其需要处理的某些网址（例如music.example.comhttps://🎵.example.com），则应用需要验证这些其他来源的所有权。这会发生在托管在其他源上的 web-app-origin-association 文件中。

此文件必须包含有效的 JSON。顶级结构是一个对象，其中包含一个名为 "web_apps" 的成员。此成员是一个对象数组，其中每个对象都代表一个唯一的 Web 应用的条目。每个对象都包含：

每个 "details" 对象都包含：

下面给出了上述音乐 PWA 示例的 web-app-origin-association 文件示例。该脚本将托管在来源 🎵.example.com 上，并与 music.example.com PWA 建立关联（通过其 Web 应用清单网址进行标识）。

{
  "web_apps": [
    {
      "manifest": "https://music.example.com/manifest.json",
      "details": {
        "paths": ["/*"],
        "exclude_paths": ["/internal/*"]
      }
    }
  ]
}

网址何时匹配？

如果同时满足以下两个条件，PWA 就会与要处理的网址匹配：

• 网址与 "url_handlers" 中的某个来源字符串匹配。
• 浏览器能够通过相应的 web-app-origin-association 文件验证每个来源是否同意让此应用处理此类网址。

关于 web-app-origin-association 文件发现

为了让浏览器发现 web-app-origin-association 文件，开发者需要将 web-app-origin-association 文件放置在应用根目录下的 /.well-known/ 文件夹中。为此，文件名必须完全为 web-app-origin-association。

演示

如需将 PWA 作为网址处理程序进行测试，请务必按照上文所述设置浏览器标志，然后在 https://mandymsft.github.io/pwa/ 安装 PWA。查看其 Web 应用清单后，您会发现该应用会处理采用以下网址格式的网址：https://mandymsft.github.io 和 https://luhuangmsft.github.io。由于后者与 PWA 位于不同的来源 (luhuangmsft.github.io)，因此 mandymsft.github.io 上的 PWA 需要证明其所有权，这通过托管在 https://luhuangmsft.github.io/.well-known/web-app-origin-association 的 web-app-origin-association 文件来实现。

如需测试它是否确实有效，请使用您选择的即时通讯应用或在非网络版电子邮件客户端（例如 macOS 上的“邮件”）中查看的电子邮件向自己发送测试消息。电子邮件或短信应包含 https://mandymsft.github.io 或 https://luhuangmsft.github.io 链接之一。这两项操作都应在已安装的 PWA 中打开。

安全与权限

Chromium 团队使用控制对强大 Web 平台功能的访问权限中定义的核心原则（包括用户控制、透明度和人体工学）设计和实现了将 PWA 用作网址处理程序的功能。

用户控制

如果有多个 PWA 注册为给定网址格式的网址处理程序，系统会提示用户选择要使用哪个 PWA 处理该网址格式（如果有）。此提案不处理在浏览器标签页中开始的导航，而是明确针对在浏览器之外开始的导航。

透明度

如果因任何原因而无法在 PWA 安装期间成功完成必要的关联验证，浏览器将不会将应用注册为受影响网址的有效网址处理程序。如果网址处理程序实现不当，可能会被用于盗用网站的流量。因此，应用关联机制是该方案的重要组成部分。

平台专用应用已经可以使用操作系统 API 枚举用户系统上安装的应用。例如，Windows 上的应用可以使用 FindAppUriHandlersAsync API 枚举网址处理程序。如果 PWA 在 Windows 中注册为操作系统级别的网址处理程序，其他应用将会看到它们。

权限持久性

来源可以随时修改与 PWA 的关联。浏览器将定期尝试重新验证已安装的 Web 应用的关联。如果网址处理程序注册因关联数据已更改或不再可用而无法重新验证，浏览器将移除注册。

反馈

Chromium 团队希望了解您使用 PWA 作为网址处理程序的体验。

请向我们说明 API 设计

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

报告实现方面的问题

您是否发现了 Chromium 实现中的 bug？或者实现方式是否与规范不同？ 请访问 new.crbug.com 提交 bug。请务必提供尽可能详细的信息、简单的重现说明，并在 Components 框中输入 UI>Browser>WebAppInstalls。故障非常适合分享快速简便的重现步骤。

表示对 API 的支持

您是否打算将 PWA 用作网址处理程序？您的公开支持可帮助 Chromium 团队确定各项功能的优先级，并向其他浏览器供应商展示支持这些功能的重要性。

使用 #URLHandlers 标签向 @ChromiumDev 发推文，告诉我们您在哪里以及如何使用该工具。

实用链接

• 公开铺垫消息
• 演示 | 演示源代码
• Chromium 跟踪错误
• ChromeStatus.com 条目
• 闪烁组件：UI>Browser>WebAppInstalls
• TAG 审核
• Microsoft 文档

致谢

将 PWA 作为网址处理程序由 Microsoft Edge 团队的 Lu Huang 和 Mandy Chen 指定并实现。本文由 Joe Medley 审核。主打图片由 Unsplash 用户 Bryson Hammer 提供。