快速入门指南

Peter Conn
Peter Conn

Trusted Web Activity 的设置可能有点棘手,尤其是当您只想显示自己的网站时。本指南将引导您创建一个使用 Trusted Web Activity 的基本项目,并介绍所有注意事项。

在本指南结束后,您将能够:

  • 使用 Bubblewrap 构建了使用 Trusted Web Activity 且通过验证的应用。
  • 了解您的签名密钥何时会被使用。
  • 能够确定 Android 应用的构建签名。
  • 了解如何创建基本数字资产关联文件。

若要按照本指南操作,您需要:

  • 开发计算机上安装了 Node.js 10 或更高版本。
  • 已连接并设置为开发环境的 Android 手机或模拟器(如果您使用的是实体手机,请启用 USB 调试)。
  • 开发手机上支持 Trusted Web Activity 的浏览器。 请使用 Chrome 72 或更高版本。我们正在为其他浏览器提供支持。
  • 您希望在 Trusted Web Activity 中查看的网站。

借助 Trusted Web Activity,您的 Android 应用无需任何浏览器界面即可启动全屏浏览器标签页。此功能仅适用于您拥有的网站,您可以通过设置 Digital Asset Links 来证明这一点。我们稍后会详细介绍这些功能

当您启动可信 Web 活动时,浏览器会检查 Digital Asset Links 是否已通过检查,这称为验证。如果验证失败,浏览器将改为以自定义标签页的形式显示您的网站。

安装和配置 Bubblewrap

Bubblewrap 是一组库和一个适用于 Node.js 的命令行工具 (CLI),可帮助开发者使用可信 Web 活动在 Android 应用中生成、构建和运行渐进式 Web 应用。

您可以使用以下命令安装该 CLI:

npm i -g @bubblewrap/cli

设置环境

首次运行 Bubblewrap 时,它会提供自动下载和安装所需外部依赖项的选项。我们建议您允许该工具执行此操作,因为这可确保依赖项配置正确无误。请参阅 Bubblewrap 文档,了解如何使用现有的 Java 开发套件 (JDK) 或 Android 命令行工具安装。

初始化和构建项目

如需初始化封装 PWA 的 Android 项目,请运行 init 命令:

bubblewrap init --manifest=https://my-twa.com/manifest.json

Bubblewrap 会读取 Web 清单,要求开发者确认要在 Android 项目中使用的值,并使用这些值生成项目。生成项目后,请运行以下命令生成 APK:

bubblewrap build

运行

构建步骤将输出一个名为 app-release-signed.apk 的文件。此文件可安装在开发设备上以进行测试,也可上传到 Play 商店以进行发布。

Bubblewrap 提供了用于在本地设备上安装和测试应用的命令。将开发设备连接到计算机,然后运行以下命令:

bubblewrap install

或者,您也可以使用 adb 工具。

adb install app-release-signed.apk

该应用现在应该会显示在设备启动器中。打开应用后,您会发现您的网站会以自定义标签页的形式启动,而不是以可信网站活动的形式启动,这是因为我们尚未设置数字资产关联验证,但首先...

Bubblewrap 的图形界面 (GUI) 替代方案

PWA Builder 提供了一个 GUI 界面,该界面使用 Bubblewrap 库来生成 Trusted Web Activity 项目。如需详细了解如何使用 PWA Builder 创建用于打开 PWA 的 Android 应用,请参阅这篇博文

关于签名密钥的说明

Digital Asset Links 会考虑 APK 的签名密钥,而验证失败的常见原因是使用了错误的签名。(请注意,如果验证失败,您的网站将以自定义标签页的形式启动,网页顶部会显示浏览器界面。)当 Bubblewrap 构建应用时,系统会在 init 步骤期间创建一个具有密钥设置的 APK。不过,当您在 Google Play 中发布应用时,系统可能会为您创建另一个密钥,具体取决于您选择如何处理签名密钥。详细了解签名密钥及其与 Bubblewrap 和 Google Play 的关系

Digital Asset Links 本质上由以下两部分组成:指向您应用的网站上的文件,以及指向您网站的应用中的部分元数据。

创建 assetlinks.json 文件后,将其上传到您的网站(相对于根目录为 .well-known/assetlinks.json),以便浏览器能够正确验证您的应用。如需详细了解数字资产链接与签名密钥之间的关系,请参阅深入了解数字资产链接

检查您的浏览器

Trusted Web Activity 会尝试遵循用户的默认浏览器选择。如果用户的默认浏览器支持 Trusted Web Activity,系统会启动该浏览器。如果没有,系统会选择任何已安装的浏览器(如果有)来支持 Trusted Web Activity。 最后,默认行为是回退到自定义标签页模式。

这意味着,如果您要调试与 Trusted Web Activity 相关的问题,则应确保您使用的是您认为自己在使用的浏览器。您可以使用以下命令检查正在使用的浏览器:

> adb logcat -v brief | grep -e TWAProviderPicker
D/TWAProviderPicker(17168): Found TWA provider, finishing search: com.google.android.apps.chrome

后续步骤

如果您按照本指南操作,应该可以获得正常运行的可信 Web 活动,并且拥有足够的知识来调试验证失败时发生的情况。如果没有,请参阅更多面向 Web 开发者的 Android 概念,或针对这些文档在 GitHub 上提交问题。

接下来,建议您先为应用创建图标。完成后,您可以考虑将应用部署到 Play 商店。