48 lines
2.5 KiB
Markdown
48 lines
2.5 KiB
Markdown
# TWA 构建说明
|
||
|
||
本目录是 `gao.imyeyu.com` 的 Trusted Web Activity 工程。APK 只包含 Android 启动壳，业务页面始终从 `https://gao.imyeyu.com/` 加载，不把前端 `dist` 打进 APK。
|
||
|
||
## 构建环境
|
||
|
||
- JDK 17
|
||
- Android SDK
|
||
- Bubblewrap CLI 1.25.0
|
||
|
||
在本机首次使用 Bubblewrap 时执行：
|
||
|
||
```powershell
|
||
pnpm --config.registry=https://registry.npmjs.org dlx @bubblewrap/cli@1.25.0 doctor
|
||
```
|
||
|
||
## 构建 APK
|
||
|
||
首次构建正式版本时，先在本目录生成并妥善备份 release keystore：
|
||
|
||
```powershell
|
||
keytool -genkeypair -v -keystore .\android.keystore -alias gao-customer -keyalg RSA -keysize 2048 -validity 10000
|
||
```
|
||
|
||
```powershell
|
||
pnpm --config.registry=https://registry.npmjs.org dlx @bubblewrap/cli@1.25.0 build
|
||
```
|
||
|
||
构建前请准备长期保存的 release keystore，并确认 `twa-manifest.json` 中的 `signingKey` 指向它。当前目录的 `signingKey` 是可提交的相对路径模板；本次验证 APK 使用的是本机调试签名，不能作为正式发布签名。
|
||
|
||
构建完成后，用 release keystore 的 SHA-256 证书指纹更新 `../public/.well-known/assetlinks.json`，再发布前端 `dist`。TWA 只有在网站的 `/.well-known/assetlinks.json` 与 APK 包名、签名一致时，才会进入无地址栏的全屏模式。
|
||
|
||
当前 `assetlinks.json` 中登记的是本机调试证书指纹，只能配合本次验证 APK 使用。正式发布前必须替换为 release 证书指纹；如果使用 Google Play，还要把 Play App Signing 证书指纹一并登记。
|
||
|
||
## TWA 媒体桥接
|
||
|
||
TWA 通过 `postMessage` 接收网页直接拍摄的照片和视频，Android 10 及以上使用 `MediaStore` 分块写入系统相册，照片保存到“图片/糕店管理”，视频保存到“视频/糕店管理”。普通浏览器和从相册选择的文件不会触发该桥接。
|
||
|
||
桥接依赖 `assetlinks.json` 中的 `delegate_permission/common.use_as_origin` 关系。发布 APK 前必须使用实际 release 签名证书的 SHA-256 指纹更新该文件，否则来源验证失败，桥接不会启用。
|
||
|
||
## 前端发布顺序
|
||
|
||
1. 先上传新版本 `dist/assets`。
|
||
2. 再上传新的 `index.html`、Manifest 和其他静态文件。
|
||
3. 最后检查 `https://gao.imyeyu.com/`、`/manifest.webmanifest` 和 `/.well-known/assetlinks.json`。
|
||
|
||
`index.html` 不缓存，带哈希的 `/assets/` 长缓存。不要给前端资源增加 Service Worker 缓存，除非同时实现版本更新和回滚，否则会阻止 TWA 获取最新页面。
|