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

> Trusted Web Activity 是什么、与 WebAPK 有何不同、数字资产链接（Digital Asset Links）验证如何工作，以及何时使用 TWA 而非其他安装方式。

**一句话：** 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](/zh/reference/installation/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

```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 项目：

```bash
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](https://developer.chrome.com/docs/android/trusted-web-activity/play-billing)
访问 Google Play 内购，这是 Chrome 的专属扩展，将 Play 的支付基础设施公开给在经验证
TWA 中运行的网页内容。普通浏览器 PWA 无法使用此 API。

## 兼容性

分发和浏览器支持数据，请查看 [/compatibility/](/zh/compatibility/) 和
[/ecosystem/distribution/](/zh/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 能够干净降级）。