Trusted Web Activity（TWA）：PWA 进入 Play 商店

一句话： Trusted Web Activity（TWA）是一个通过数字资产链接（Digital Asset Links） 加密来源验证的全屏 Chrome 自定义标签页，让你可以将 PWA 作为真正的 Android 应用上架 Google Play 商店，且无需显示地址栏。

TWA 是什么

TWA 是一个 Android 活动（com.google.androidbrowserhelper.trusted.TwaLauncher）， 在全屏 Chrome 自定义标签页中打开 URL。与普通自定义标签页或 WebView 的关键区别在于 数字资产链接（DAL）验证：

1. 你的网站在 /.well-known/assetlinks.json 处托管一个 JSON 文件，声明 Android 签名证书的 SHA-256 指纹。
2. Chrome 在启动时验证指纹。如果匹配，Chrome 不显示地址栏——用户看到的是原生感十足的应用。
3. 如果验证失败，Chrome 回退到带有地址栏的普通自定义标签页，这是一条安全的优雅降级路径。

这与 WebAPK 有本质区别：WebAPK 由 Chrome 在安装时 从设备生成，无需 Play 商店参与；TWA 是你自己构建、签名并提交到 Play 商店的 Android 应用。

TWA vs WebAPK：如何选择

	TWA	WebAPK（Chrome 安装）
分发渠道	Google Play 商店	Chrome 浏览器安装提示
需要 Android 应用项目	是（Kotlin/Java 或 Bubblewrap）	否
需要数字资产链接	是	否
验证失败时显示地址栏	是（优雅回退）	不适用
Play 内购 / Play 完整性	可通过 postMessage 桥接访问	不可访问
更新机制	Play 商店 APK 更新	清单重新铸造（约 24 小时）
适用场景	Play 商店上架、变现、企业 MDM	快速“添加到主屏幕”安装

配置 TWA

1. 创建 assetlinks.json

[{
  "relation": ["delegate_permission/common.handle_all_urls"],
  "target": {
    "namespace": "android_app",
    "package_name": "com.example.myapp",
    "sha256_cert_fingerprints": [
      "AB:CD:EF:..."
    ]
  }
}]

将此文件托管在 https://yourdomain.com/.well-known/assetlinks.json， 使用 Content-Type: application/json 响应头。 文件必须不经重定向即可访问；否则验证会静默失败并显示地址栏。

2. 构建 Android 包装器

推荐路径是 Bubblewrap CLI（@bubblewrap/cli），这是 Google 的开源工具， 可生成预配置 TWA 的 Android Studio 项目：

npm i -g @bubblewrap/cli
bubblewrap init --manifest https://yourdomain.com/manifest.json
bubblewrap build

Bubblewrap 读取你的 Web 应用清单并生成 Android 项目。 你提供签名密钥；Bubblewrap 生成可直接提交 Play 商店的已签名 APK 和 AAB。

3. 通过 Play 商店审核

TWA 须通过 Play 的标准政策审核。你的 PWA 网页内容可通过 URL 访问， 因此 Play 可能会进行额外审查。常见要求：可用的隐私政策 URL、正常运行的离线功能， 以及不违反 Play 政策的内容。

数字资产链接验证详解

• Chrome 在 TWA 启动时获取 assetlinks.json（有较短的网络超时）。
• 指纹与 APK 签名证书进行比对。
• 验证结果缓存长达 5 分钟；错误的缓存条目可能导致重新部署后延迟生效。
• 可通过 Android 资产链接 API 工具或以下命令测试验证：

  adb shell am start -a android.intent.action.VIEW \
    -d https://yourdomain.com com.example.myapp

iOS

TWA 是仅限 Android 的技术。iOS 上的 Chrome for iOS 不支持 TWA。 iOS 上的 PWA 分发通过 Safari 的“添加到主屏幕”机制进行； 没有使用 Web 标准的等效 App Store 路径（使用 WKWebView 的原生 iOS 包装器是 PWA/TWA 模型以外的独立方法）。

桌面端

TWA 仅限 Android。ChromeOS 也支持 TWA（因为 ChromeOS 基于 Android）， 允许 Play 商店 PWA 应用在 Chromebook 上运行。桌面端 Windows、macOS 和 Linux 没有 TWA 的等效物；类似的桌面路径是直接通过 Chrome 安装，使用类似 WebAPK 风格的隔离窗口。

Play 内购集成

TWA 可通过数字商品 API 访问 Google Play 内购，这是 Chrome 的专属扩展，将 Play 的支付基础设施公开给在经验证 TWA 中运行的网页内容。普通浏览器 PWA 无法使用此 API。

兼容性

分发和浏览器支持数据，请查看 /compatibility/ 和 /ecosystem/distribution/。

实践检查清单

• assetlinks.json 托管在 /.well-known/assetlinks.json，无重定向，正确的 content-type。
• 文件中使用发布签名证书的 SHA-256 指纹（不是调试签名）。
• 使用 Bubblewrap（或等效工具）生成 Android 项目。
• build.gradle 中的 applicationId 与 assetlinks.json 中的 package_name 匹配。
• 在 Play 提交前用 adb 或资产链接检查器验证 TWA。
• 隐私政策 URL 已上线并在 Play 商品页中链接。
• 测试优雅的地址栏回退（暂时破坏指纹以确认 Chrome 能够干净降级）。