跳转到内容

安装中的平台

Trusted Web Activity

发布于 更新于

自 2019-01 起广泛可用厂商文档

Trusted Web Activity(TWA)是 Android activity,可以用用户的浏览器(Chrome 72 起)全屏显示 Web 源,隐藏地址栏。前提是 Digital Asset Links 已确认 APK 签名密钥和网站属于同一方。它是 PWA 上架 Google Play 的途径;Chrome 72 在 Android 上引入了它,该协议对其他浏览器开放,但 Chrome 的文档只记录了 Chrome 自身的支持。

TWA 这一屏不显示打包进 APK 的 Web 内容。启动 activity 使用 android-browser-helper 库中的 com.google.androidbrowserhelper.trusted.LauncherActivity,经 Custom Tabs 服务绑定用户的默认浏览器(它支持 TWA 时),否则绑定另一个支持 TWA 的已安装浏览器,请求以受信任模式打开应用配置的启动 URL(Bubblewrap 会按 manifest 的 start_url 填写)。

浏览器渲染站点,沿用用户的 Cookie、service worker 和存储。

浏览器在应用启动时验证信任:

  1. 网站在 /.well-known/assetlinks.json 中以关系 delegate_permission/common.handle_all_urls 列出应用的包名与签名证书的 SHA-256 指纹。
  2. APK 在 asset_statements 字符串资源中声明同一个源。
  3. 启动时浏览器检查 assetlinks 文件(以 application/json 提供、不经重定向即可访问)并比对指纹。匹配则隐藏地址栏;不匹配、文件缺失或发生重定向则回退为带地址栏的普通 Custom Tab,这是设计好的回退。用户看不到任何错误,原因可以用 adb logcat | grep -e OriginVerifier -e digital_asset_links 查看。

由于 Play 在 Play App Signing 下用自己的密钥为上传的应用签名,assetlinks.json 中的指纹必须是 Play 托管的签名密钥,而不是本地的上传密钥;签名用错是验证失败的常见原因。

Android 安装方式在构建产物和可用能力上有以下区别。

TWA WebAPK(Chrome 安装) 主屏幕快捷方式
分发方 Google Play Chrome 在安装时生成 任意浏览器
需要自己构建 Android 项目 是(Bubblewrap 或 Android Studio) 否 否
Digital Asset Links 必需 不使用 不使用
Play Billing 是,通过 Digital Goods API 否 否
更新 web 内容随站点部署生效;外壳需发布 Play 新版本 由 Chrome 重新检查 manifest 无
运行于 支持 TWA 的浏览器,优先用户的默认浏览器 Chrome 执行安装的浏览器

Play Billing 由网页通过 Digital Goods API(window.getDigitalGoodsService('https://play.google.com/billing'))配合 Payment Request 访问。Chrome 的文档只针对 Trusted Web Activity 说明这一做法,Android 应用还需要接入 billing 扩展;Google Play 要求在其上架、销售数字商品的应用使用 Play Billing。

TWA 需要在站点发布 assetlinks 文件,并有一个 Android 外壳,Bubblewrap 可以根据 web manifest 生成它。页面内的检测不是必需的,只在要开启 Play 专属功能时才有用。

文件位于该源的 /.well-known/assetlinks.json。每个包名一条声明,其 sha256_cert_fingerprints 数组列出用到的每把签名密钥的指纹,调试密钥与发布密钥都要列入。

[{
"relation": ["delegate_permission/common.handle_all_urls"],
"target": {
"namespace": "android_app",
"package_name": "com.example.app",
"sha256_cert_fingerprints": [
"14:6D:E9:83:C5:73:06:50:D8:EE:B9:95:2F:34:FC:64:16:A0:83:42:E6:1D:BE:A8:8A:04:96:B2:3F:CF:44:E5"
]
}
}]

Play Console 在“发布 › 设置 › 应用签名 › 应用签名密钥证书”下显示正确的指纹;用 keytool 对上传密钥生成的声明在本地通过,在 Play 分发的构建上失败。

Bubblewrap 读取 web 应用 manifest,生成一个已填好包名、图标、颜色与 asset_statements 的 Android 项目。

Terminal window
npm i -g @bubblewrap/cli
bubblewrap init --manifest https://example.com/manifest.webmanifest
bubblewrap build # 产出 app-release-signed.apk 与 app-release-bundle.aab
bubblewrap validate --url https://example.com/ # 基于 Lighthouse 的 PWA 检查

生成的项目锁定了 android-browser-helper 的版本;web manifest 变化后,先用 bubblewrap merge 把它并入 twa-manifest.json,再用 bubblewrap update 据此重新生成 Android 项目。把 .aab 交给 Play 分发时,assetlinks.json 必须填写 Play 签名密钥的指纹。

Android 默认用启动包对应的 android-app:// URI 设置 activity 的 referrer,TWA 启动时 Chrome 会把它带给第一个页面。拿它当信号来开启 Play 专属功能、隐藏 web 安装提示很实用,不过 Chrome 的 TWA 文档没有记载这一点,只能当作经验做法。

const fromTwa = document.referrer.startsWith('android-app://com.example.app/');
if (fromTwa && 'getDigitalGoodsService' in window) {
enablePlayBilling(); // 此处可用 Digital Goods API
} else {
enableWebCheckout(); // 其他地方走常规 web 支付
}
installButton.hidden = fromTwa || matchMedia('(display-mode: standalone)').matches;

之后的导航带的是普通 web referrer,所以要在第一个页面就保存检测结果,例如写入 sessionStorage。

TWA 内的 display-mode: standalone 同样匹配(除非 Bubblewrap 配成了 fullscreen),WebAPK 也匹配,所以这条查询分不出两者。

规范

规范状态
Trusted Web Activity 可用性厂商文档
  • 图例
  • 支持
  • 部分支持
  • 需开启标志
  • 不支持
  • 未知
浏览器 / 平台支持版本置信度来源备注
Chrome (Android)#支持72中来源123
  1. 依据 Chrome 文档,Trusted Web Activity 自 Android 版 Chrome 72 起可用。
  2. 没有跨浏览器兼容性数据集(BCD / caniuse)收录 TWA;版本号依据 Chrome 自己的文档核对。
  3. 同一份文档提到其他浏览器可能实现相同协议,但没有记录任何其他浏览器对 TWA 的支持。

源数据: /compatibility/twa.json · 全球使用占比: 66 % (StatCounter 2026-09, CC BY-SA 4.0)

来源: 规范 · 最近核验 2026-09-09 · 置信度: 中 (由来源计算)