如果您是刚开始接触 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 的形式将其分发给用户。因此,APK 的签名也需要由 Google Play 完成。因此,默认情况下,如果您将应用以 AAB 文件的形式上传到 Play 管理中心,您需要使用 Play 应用签名功能。
- APK:利用 APK,您可以选择加入 Play 应用签名计划。强烈建议您选择加入 Play 应用签名计划,因为这样可以提高签名密钥的安全性。如前所述,Google Play 很快会要求所有新应用都以 AAB 格式上传,因此我们建议您采用 AAB 格式,而不是上传 APK 格式。
- 管理您自己的签名密钥:如果您选择自行管理自己的密钥,并且不选择加入 Play 应用签名计划,则您对应用的签名密钥承担全部责任。与 Play 应用签名功能不同,如果您丢失了密钥,则无法重置应用签名。因此,如果丢失应用的签名密钥,您也会失去更新应用的权限。
在 bubblewrap init
设置过程中,当您进入“签名密钥信息 (5/5)”部分时,系统会提示您输入“密钥库位置”和“密钥名称”,或使用默认值。默认密钥库位置是项目目录中的 android.keystore
文件,默认密钥名为 android
。如果 Bubblewrap 没有在相应位置找到具有该密钥名称的现有密钥库,则会为您创建一个密钥库,并且还会提示您输入密码。请记下您输入的密码,以便在构建流程 (bubblewrap build
) 中用到这些密码,以便使用此密钥为您的应用签名。如果您选择加入 Play 应用签名计划,则 Bubblewrap 生成并用于为您的应用签名的签名密钥将成为“上传密钥”。无论您选择将气泡外框生成的密钥用作签名密钥还是上传密钥,您都应保护该密钥并确保其私密性。我们不建议将其提交到版本控制中。而应限制有访问权限的人员数量。
Digital Asset Links
您需要使用 Digital Asset Links 来声明网站和 Android 应用之间的关系。为了确保由 Bubblewrap 生成的 Android 应用经过正确验证并作为 Trusted Web Activity(而不是 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 气泡封装相关联的 SHA 256 指纹。请注意,此指纹用于本地签名密钥,如果您将应用上传到 Play 并选择加入 Play 应用签名计划,则此密钥会成为“上传密钥”。
keytool -printcert -jarfile [path to APK or AAB] | grep SHA256
通过资源链接工具
获取应用的正确 Digital Asset Links 文件的另一种方法是使用 Asset Link Tool:
- 从 Play 商店安装 Asset Link 工具。
- 在同一设备上,从 Google Play 商店下载您的应用或在本地安装您的应用。
- 打开 Asset Link Tool 应用,您会看到按软件包名称列出设备上安装的所有应用的列表。按您之前在
bubblewrap init
期间选择的应用 ID 过滤列表,然后点击该条目。 - 您将看到一个列出您应用的签名和生成的 Digital Asset Link 的页面。点击底部的“复制”或“分享”按钮,即可随心所欲地导出内容(例如,保存到 Google Keep,通过电子邮件发送给自己)。
这与之前使用签名密钥或上传密钥时的方式相同。如果您是从 Google Play 商店安装的应用,Asset Link 工具会为您提供应用签名密钥的指纹。如果您是直接从本地计算机安装应用的,那么指纹就针对的是生成的密钥气泡框。
确保素材资源链接文件可供访问
上传素材资源后,请确保您可以在浏览器中访问相应的素材资源链接文件。
检查 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]
添加更多密钥
一个 Digital Asset Links 文件可以包含多个应用,对于每个应用,它也可以包含多个密钥。 例如,如需添加第二个键,只需使用 Asset Link Tool 确定键,然后将其添加为第二个条目。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 验证失败的原因,您可以使用 adb logcat
在 Android 设备上查看这些日志。如果您在 Linux/Mac 上开发,可以使用以下命令查看已连接设备上的相关日志:
> adb logcat -v brief | grep -e OriginVerifier -e digital_asset_links
例如,如果您看到 Statement failure matching fingerprint.
消息,则应使用 Asset Link 工具查看应用的签名,并确保它与 assetlinks.json
文件中的签名相匹配。