如果您是刚开始接触 Android 和 Google Play 的 Web 开发者,则应注意以下一些细节。目前已经有许多资源和文档介绍了此功能(感谢 Android 团队),但我们将在此重点介绍一些重要概念及其与 Bubblewrap 的关系。
上传密钥与签名密钥
如果您打算使用 Bubblewrap 生成 Android App Bundle (AAB)(注意:自 2021 年 8 月起,Google Play 将要求所有新应用都使用 Android App Bundle 格式),或使用 APK 上传并发布到 Google Play,则需要使用签名密钥为应用签名。Google Play 为您提供了两种处理方式:
- Play 应用签名(强烈建议):Google 会为您管理和保护应用的签名密钥。并使用此密钥为您的 APK 签名以进行分发。Play 应用签名功能使用两个密钥。“应用签名密钥”(由 Google 为您管理)和“上传密钥”(由您保留且应保持不公开)。您可以使用上传密钥为应用签名,以便将应用上传到 Play 管理中心。借助此系统,如果您的上传密钥丢失或遭到破解,您可以与 Play 支持团队联系来重置上传密钥。目前,Google Play 允许您以 AAB 或 APK 格式上传应用:
- Android App Bundle (AAB):将 AAB 上传到 Play 管理中心后,您可以将 APK 的构建和生成工作推迟到 Google Play 商店。当用户下载并安装您的应用时,Google Play 会以已签名的 APK 的形式向用户分发您的应用。因此,Google Play 还需要对 APK 进行签名。因此,默认情况下,如果您将应用作为 AAB 上传到 Play 管理中心,则需要使用 Play 应用签名功能。
- APK:对于 APK,您可以选择加入 Play 应用签名计划。强烈建议您选择加入 Play 应用签名计划,因为它可以提高签名密钥的安全性。如前所述,Google Play 即将要求所有新应用均采用 AAB 格式上传,因此我们建议您采用这种格式上传应用,而不是上传 APK。
- 自行管理签名密钥:如果您选择自行管理密钥,而不选择加入 Play 应用签名计划,则需对应用的签名密钥承担全部责任。与 Play 应用签名不同,如果您丢失密钥,则无法重置此密钥。因此,丢失应用的签名密钥意味着您也将无法更新应用。
在 bubblewrap init
设置过程中,当您看到“签名密钥信息 (5/5)”部分时,系统会提示您输入“密钥库位置”和“密钥名称”,或者使用默认值。默认密钥库位置为项目目录中的 android.keystore
文件,默认密钥名称为 android
。如果 Bubblewrap 在该位置未找到具有该键名的现有密钥库,则会为您创建一个密钥库,并提示您输入密码。请记下您输入的密码,因为您需要在构建过程中 (bubblewrap build
) 使用这些密码,系统会使用这些密钥为您的应用签名。如果您选择加入 Play 应用签名计划,则 Bubblewrap 生成并用于为您的应用签名的签名密钥将成为“上传密钥”。无论您选择将 Bubblewrap 生成的密钥用作签名密钥还是上传密钥,都应妥善保管该密钥并对其保密。我们不建议将其提交到版本控制系统。请限制有权访问该账号的人员数量。
Digital Asset Links
您需要使用 Digital Asset Link 声明网站与 Android 应用之间的关系。为确保由 Bubblewrap 生成的 Android 应用能够得到妥善验证并以可信 Web 活动(而非 Chrome 自定义标签页)的形式启动,您需要向 assetlinks.json
文件添加适当的键。然后将其上传到您网站的 .well-known/assetlinks.json
(相对于根目录)。您的 assetlinks.json
文件应采用以下格式:
[{
"relation": ["delegate_permission/common.handle_all_urls"],
"target": {
"namespace": "android_app",
"package_name": "com.your.package_name",
"sha256_cert_fingerprints": [
"XX:XX:XX:..."
]
}
}]
获取 SHA256 证书指纹
如需创建 assetlinks.json
文件,您需要与应用的签名密钥关联的 SHA 256 证书指纹。请务必注意,与签名密钥和上传密钥关联的指纹会不同。请务必注意这一区别,尤其是在您发现应用以 Chrome 自定义标签页(浏览器栏可见)的形式启动时。那么,您的 assetlinks.json
文件可能没有与相应密钥对应的指纹。
在 assetlinks.json 中同时包含签名证书和上传证书的指纹非常有用,这样您就可以更轻松地在本地调试应用。如需详细了解如何在 assetlinks.json
文件中同时使用这两把密钥,请参阅下文的添加更多密钥部分。
您可以通过几种不同的方式获取指纹,下一部分将对此进行详细介绍。 它们应该都会生成相同的指纹,因此请随意选择最方便的方法。
通过 Play 管理中心
根据您是否选择加入 Play 应用签名计划,您可能拥有一个或两个密钥。如需检索每个密钥的适当 SHA256 指纹,请执行以下操作:
- 前往 Play 管理中心
- 选择您感兴趣的应用
- 在左侧的导航菜单中,点击“版本”下方的设置 -> 应用完整性。
- 复制相应密钥的 SHA256:
签名密钥:复制“应用签名密钥证书”的 SHA256 指纹。如果您从 Google Play 商店下载应用,此指纹将与您的应用相对应,因为 Google Play 会分发使用签名密钥签名的应用。
上传密钥:复制“上传密钥证书”的 SHA256 指纹。如果您在本地安装应用(例如通过 USB 使用 ADB),此指纹将与您的应用相对应。该 APK(在您的本地机器上)是由 Bubblewrap 构建的,因此也由它在
init
设置期间为您创建的密钥进行了签名。请注意,这可能是本地安装的应用的签名密钥,但在您通过 Play 发布应用后,它实际上会成为“上传密钥”。
经由keytool
keytool 是一款密钥和证书管理工具。您可以使用 keytool 提取与生成的 APK 或 AAB Bubblewrap 关联的 SHA 256 指纹。请注意,此指纹适用于本地签名密钥。如果您将应用上传到 Play 并选择加入 Play 应用签名计划,此密钥将成为“上传密钥”。
keytool -printcert -jarfile [path to APK or AAB] | grep SHA256
通过资产链接工具
如需为应用获取正确的 Digital Asset Links 文件,您还可以使用素材资源关联工具:
- 从 Play 商店安装素材资源关联工具。
- 在同一设备上,从 Google Play 商店下载您的应用,或在本地安装您的应用。
- 打开 Asset Link Tool 应用,您会看到设备上安装的所有应用的列表(按软件包名称排序)。按您在
bubblewrap init
期间选择的应用 ID 过滤列表,然后点击相应条目。 - 您将看到一个列出您应用的签名和生成的 Digital Asset Link 的页面。点击底部的“复制”或“分享”按钮,以便按需要导出(例如,保存到 Google 记事、通过电子邮件发送给自己)。
与签名密钥或上传密钥一样,同样的做法也适用于该密钥。如果您是从 Google Play 商店安装的应用,Asset Link 工具会为您获取应用签名密钥的指纹。如果您直接从本地机器安装了应用,则指纹是指 Bubblewrap 生成的密钥。
确保您的素材资源链接文件可访问
上传完毕后,请确保您可以在浏览器中访问素材资源链接文件。
检查 https://example.com/.well-known/assetlinks.json
是否解析为您刚刚上传的文件。
基于 Jekyll 的网站
如果您的网站由 Jekyll 生成(例如 GitHub Pages),则需要添加一行配置,以使 .well-known
目录包含在输出中。如需详细了解此主题,请参阅 GitHub 帮助。在网站的根目录下创建一个名为 _config.yml
的文件(如果该文件已存在,请将代码添加到其中),然后输入以下内容:
# Folders with dotfiles are ignored by default.
include: [.well-known]
添加更多按键
一个数字资产关联文件可以包含多个应用,并且每个应用可以包含多个键。例如,如需添加第二个键,只需使用素材资源关联工具确定键,然后将其添加为第二个条目即可。Chrome 中用于解析此 JSON 的代码非常严格,因此请确保您不会在列表末尾不小心添加额外的英文逗号。
[{
"relation": ["delegate_permission/common.handle_all_urls"],
"target": {
"namespace": "android_app",
"package_name": "com.your.package_name",
"sha256_cert_fingerprints": [
"XX:XX:XX:..."
]
}
},{
"relation": ["delegate_permission/common.handle_all_urls"],
"target": {
"namespace": "android_app",
"package_name": "com.your.package_name",
"sha256_cert_fingerprints": [
"XX:XX:XX:..."
]
}
}]
问题排查
Chrome 会记录 Digital Asset Links 验证失败的原因,您可以在 Android 设备上使用 adb logcat
查看日志。如果您是在 Linux/Mac 上进行开发,可以通过以下命令查看已连接设备的相关日志:
> adb logcat -v brief | grep -e OriginVerifier -e digital_asset_links
例如,如果您看到消息 Statement failure matching fingerprint.
,则应使用资源关联工具查看应用的签名,并确保其与 assetlinks.json
文件中的签名一致。