Android 概念（面向 Web 开发者）

Peter Conn
Peter Conn
X GitHub
Joyce Toh
Joyce Toh
GitHub

如果您是刚开始接触 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 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 指纹，请执行以下操作：

  1. 前往 Play 管理中心
  2. 选择您感兴趣的应用
  3. 在左侧的导航菜单中，点击“版本”下方的设置 -> 应用完整性。
  4. 复制相应密钥的 SHA256：

为您的签名或上传密钥检索相应的 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 文件，您还可以使用素材资源关联工具：

  1. 从 Play 商店安装素材资源关联工具。
  2. 在同一设备上，从 Google Play 商店下载您的应用，或在本地安装您的应用。
  3. 打开 Asset Link Tool 应用，您会看到设备上安装的所有应用的列表（按软件包名称排序）。按您在 bubblewrap init 期间选择的应用 ID 过滤列表，然后点击相应条目。
  4. 您将看到一个列出您应用的签名和生成的 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 文件中的签名一致。