PWA 用作网址处理程序

允许已安装的 PWA 处理网址，以实现更完整的体验。

Thomas Steiner

警告：作为网址处理程序的 PWA 是功能项目的一部分，对实验性 url_handlers 清单成员（如下所述）的支持将被逐步停用。url_handlers 清单成员即将被新的 handle_links 清单成员取代，后者目前正在进行标准化和实现。请参阅 handle_links 说明文档。

什么是 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 标志。

注意：对于将 PWA 用作网址处理程序功能的支持，仅限于默认浏览器（根据操作系统的设置）。例如，可以按照这些instructions将 Chrome 设为默认浏览器。

"url_handlers" Web 应用清单成员

如需将已安装的 PWA 与网址格式相关联，您需要在 Web 应用清单中指定这些格式。这通过 "url_handlers" 成员来实现。它接受具有 origin 属性的对象数组，该属性是必需的 string，这是匹配源站的模式。这些格式可以使用通配符 (*) 前缀，以便包含多个子网域（例如 https://*.example.com）。与这些来源匹配的网址可由此 Web 应用处理。系统始终假定架构为 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"
    }
  ]
}

注意：在使用在线场景中时，来自 https://🎵.example.com 的短链接通常会重定向到 https://music.example.com。对于离线场景，此类导航重定向不是理想的替代方案。因此，应用需要针对这两个源进行注册。

web-app-origin-association 文件

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

注意：如果应用想要处理与 PWA 位于同一来源的网址，也需要在托管在该来源上的 web-app-origin-association 文件中指定处理规则。

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

字段	说明	类型	默认
"manifest"	（必需）关联 PWA 的 Web 应用清单的网址字符串	string	不适用
"details"	（可选）一个对象，其中包含由包含和排除的网址格式数组	object	不适用

每个 "details" 对象包含：

字段	说明	类型	默认
"paths"	（可选）允许的路径字符串数组	string[]	[]
"exclude_paths"	（可选）不允许使用的路径字符串数组	string[]	[]

上述音乐 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/*"]
      }
    }
  ]
}

注意：web-app-origin-association 文件类似于 Apple 的关联网域文件、Android 的 assetlinks.json 文件和 Windows 的 windows-app-web-link 文件。不同之处在于 web-app-origin-association 文件不使用平台专用应用 ID 来引用 PWA，而是通过其 Web 应用清单网址来引用 PWA。

何时匹配网址？

如果同时满足以下两个条件，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 文件进行。

如需测试它是否确实能正常运行，请使用您选择的即时通讯应用或在非基于 Web 的电子邮件客户端（如 macOS 上的“邮件”）中查看电子邮件，向自己发送一封测试邮件。电子邮件或短信应包含 https://mandymsft.github.io 或 https://luhuangmsft.github.io 链接之一。这两者都应在已安装的 PWA 中打开。

安全与权限

Chromium 团队按照控制对强大网络平台功能的访问权限（包括用户控制、透明度和工效学设计）中定义的核心原则，设计并将 PWA 作为网址处理程序。

用户控制

如果有多个 PWA 注册为给定网址格式的网址处理程序，则系统会提示用户选择要使用哪个 PWA 处理该格式（如果有）。此方案不会处理在浏览器标签页中启动的导航，它专门针对在浏览器外部启动的导航。

透明度

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

特定于平台的应用已经可以使用操作系统 API 枚举用户系统上已安装的应用。例如，Windows 上的应用可以使用 FindAppUriHandlersAsync API 枚举网址处理程序。如果 PWA 在 Windows 中注册为操作系统级网址处理程序，则其存在对其他应用可见。

权限保留

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

反馈

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

向我们介绍 API 设计

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

报告实施方面的问题

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

显示对该 API 的支持

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

请使用 # 标签 #URLHandlers 向 @ChromiumDev 发送一条推文，告诉我们您使用该推文的位置和方式。

实用链接

• 公开解说
• 演示 | 演示源代码
• Chromium 跟踪错误
• ChromeStatus.com 条目
• Blink 组件：UI>Browser>WebAppInstalls
• 代码审核
• Microsoft 文档

致谢

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