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 的形式将其分发给用户。因此，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 来声明网站和 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 指纹，请执行以下操作：

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

检索签名或上传密钥的相应 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：

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