安装中的平台
Trusted Web Activity
发布于 更新于
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 和存储。
浏览器在应用启动时验证信任:
- 网站在
/.well-known/assetlinks.json中以关系delegate_permission/common.handle_all_urls列出应用的包名与签名证书的 SHA-256 指纹。 - APK 在
asset_statements字符串资源中声明同一个源。 - 启动时浏览器检查 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 专属功能时才有用。
发布 Digital Asset Links 声明
链接到“发布 Digital Asset Links 声明”一节文件位于该源的 /.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 生成并构建外壳
链接到“用 Bubblewrap 生成并构建外壳”一节Bubblewrap 读取 web 应用 manifest,生成一个已填好包名、图标、颜色与 asset_statements 的 Android 项目。
npm i -g @bubblewrap/clibubblewrap init --manifest https://example.com/manifest.webmanifestbubblewrap build # 产出 app-release-signed.apk 与 app-release-bundle.aabbubblewrap 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 签名密钥的指纹。
检测页面是否运行在 TWA 内
链接到“检测页面是否运行在 TWA 内”一节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 Activities overview(developer.chrome.com)
- Verify Android App Links(developer.android.com)
- Bubblewrap(github.com)
- Trusted Web Activity 浏览器支持
- WebAPK
- getInstalledRelatedApps()
- 分发与商店政策
规范
| 规范 | 状态 |
|---|---|
| Trusted Web Activity 可用性 | 厂商文档 |