HTML怎么做安卓TWA应用_HTML Trusted Web Activity应用示例

作者：袖梨 2026-07-22

TWA无需修改前端代码，但需严格满足Google校验规则：PWA须配置standalone/minimal-ui显示模式、HTTPS全站加密、Service Worker激活；Android侧须用TrustedWebActivityIntentBuilder构建Intent，正确设置颜色、签名及Digital Asset Links验证。

直接用 HTML + PWA 就能跑 TWA，不需要改一行前端代码，但 Android 侧的配置和签名必须严格满足 Google 的校验规则——否则 TrustedWebActivityIntentBuilder 会静默失败，或降级为 Custom Tab。

确认你的 PWA 已通过 TWA 基础校验

TWA 不是“换个 Intent 就行”，它依赖 Web 端的可信声明。必须同时满足：

manifest.json 中 "display": "standalone" 或 "minimal-ui"（不能是 browser）
主页面响应头或 <meta> 包含 theme-color，且与 Android setToolbarColor() 一致（颜色不匹配会导致启动闪退）
站点已部署在 HTTPS 下，且所有子资源（图标、JS、SW）也走 HTTPS；HTTP 重定向到 HTTPS 不算数
service-worker.js 已注册并激活，且 navigator.serviceWorker.ready 能 resolve（TWA 启动时会检查 SW 是否可用）

Android 侧用 `TrustedWebActivityIntentBuilder` 构建 Intent

别用 WebView 或普通 CustomTabsIntent，TWA 必须走专用 builder。关键点：

构造时传入的 URL 必须和 manifest.json 中 start_url 同源，且路径可被 Service Worker 拦截（例如 start_url: "/"，你就不能传 https://a.com/login）
setNavigationBarColor() 和 setToolbarColor() 必须是不透明色值（0xFF000000 格式），带 alpha 会崩溃
如果需要 splash screen，必须提前调用 setSplashScreenStrategy() 并传入实现 SplashScreenStrategy 的对象，不能只靠 AndroidManifest 的 android:windowBackground
启动前务必检查浏览器支持：TrustedWebActivityServiceConnectionPool.isAvailable(context)，返回 false 说明设备没装 Chrome 或版本太低（

示例片段：

立即学习“前端免费学习笔记（深入）”；

TrustedWebActivityIntentBuilder twaBuilder = new TrustedWebActivityIntentBuilder("https://your-pwa.com/")    .setToolbarColor(0xFF2196F3)    .setNavigationBarColor(0xFF000000)    .setSplashScreenStrategy(new SplashScreenStrategy() { /* 实现 onShow / onDismiss */ });mTwaLauncher.launch(twaBuilder, mSplashScreenStrategy, () -> {/* 成功回调 */});

签名与 Digital Asset Links 是最容易卡住的环节

Google Play 安装包签名后，必须在域名根目录部署 .well-known/assetlinks.json，且内容需与 APK 签名证书 SHA256 指纹、包名、TWA Activity 名完全匹配。常见坑：

assetlinks.json 必须可被 https://your-pwa.com/.well-known/assetlinks.json 直接 GET 访问，返回 Content-Type: application/json，不能有 301/302 重定向
SHA256 指纹必须来自你最终上传到 Play Console 的那个签名密钥（不是 debug keystore），可用 keytool -list -v -keystore your-release-key.jks -alias alias_name -storepass password -keypass password 提取
Activity 名默认是 .MainActivity，但如果你改过 android:name，assetlinks.json 里 intent_filter 的 name 字段必须同步更新
验证是否生效：用 adb shell pm verify-link --re-verify your.package.name，再 adb shell pm get-links your.package.name 查状态

调试时别只看 Logcat，重点抓 `TrustedWebActivityService` 连接状态

TWA 启动失败往往不抛异常，而是静默 fallback 到 Custom Tab。真正线索在服务连接过程：

启动前确保 TrustedWebActivityServiceConnectionPool 已初始化，且 bindService() 成功（否则 mTwaLauncher.launch() 会直接回调失败）
监听 TrustedWebActivityCallback 的 onConnectionFailed()，里面会带具体错误码，比如 ERROR_BROWSER_NOT_FOUND 或 ERROR_ASSET_LINKS_VERIFICATION_FAILED
Chrome DevTools 远程调试地址是 chrome://inspect → 选中对应 TWA 进程，但注意：只有成功进入 TWA 页面后才可见；若卡在白屏，大概率是 Asset Links 或 SW 加载失败