使用 Android 开发者管理中心 API 注册软件包名称

Android 开发者管理中心 API 是一种公共接口，旨在让应用分发商和个人开发者能够以编程方式在 Android 开发者管理中心内注册软件包名称。

您作为以下身份的服务器到服务器功能：

应用分销商 个人开发者
代表将应用发布到商店的开发者注册软件包名称 - 密钥。注册具有商店管理的密钥的软件包名称。证明与软件包名称关联的密钥的所有权。 注册软件包名称 - 持续部署工作流中的关键步骤。证明与软件包名称关联的密钥的所有权。

准备工作

在开始之前，您应该具备以下条件：

  1. 对 Google Cloud 项目的管理员访问权限。
  2. 对以下内容有基本的了解：

您还应熟悉以下术语：

术语 定义
开发者账号 表示一个 Android 开发者管理中心账号，该账号可以拥有一个或多个软件包名称。它包含验证状态（NOT_VERIFIED 或 VERIFIED）。
软件包名称 开发者账号中的特定 Android 软件包名称（例如 com.example.app），可与一个或多个密钥相关联。它包含注册状态（DRAFT、IN_REVIEW、REGISTERED 或 PENDING_TRANSFER）。
键 用于为 Android 软件包名称签名的特定公开证书/密钥。包括 SHA-256 哈希和当前注册状态（DRAFT、OWNERSHIP_VERIFIED、IN_REVIEW、REGISTERED 或 PENDING_TRANSFER）。

开始使用

如需访问 Android 开发者管理中心 API，请完成以下步骤：

创建 Google Cloud 项目

  1. 如果您还没有 Google Cloud 账号，请创建一个 Google Cloud 账号。
  2. 打开 Google Cloud Console。
  3. 创建 Google Cloud 项目。

在 Google Cloud 项目中启用 API

  1. 打开 Google Cloud Console。
  2. 在导航菜单 (☰) 中，依次选择 API 和服务 > 库。
  3. 从项目下拉菜单中选择要在其中启用 API 的 Google Cloud 项目。
  4. 使用 API 和服务搜索栏选择 Android 开发者管理中心 API。
  5. 启用 API：
    1. 从搜索结果中选择相应 API，前往其概览页面。
    2. 点击蓝色“启用”按钮。Google Cloud 会为所选项目启用该 API，这通常只需片刻时间。启用后，您就可以开始使用它了。

对 API 进行身份验证

如需调用 Android 开发者管理中心 API，您必须使用 OAuth 2.0 对请求进行身份验证。

使用 OAuth 2.0 进行身份验证

Android 开发者管理中心 API 需要 OAuth 2.0 身份验证来授权对开发者账号资源和软件包名称的访问权限。由于开发者账号数据与用户的 Google 账号（而非 Google Cloud 项目）相关联，因此无法使用服务账号、工作负载身份联合和 API 密钥来验证 API 请求的身份。

OAuth 2.0 范围

所有操作都需要以下范围：

OAuth 2.0 范围 说明
https://www.googleapis.com/auth/androiddeveloperconsole 查看和管理您的 Android 开发者管理中心账号名下的软件包名称及数据

实现 OAuth 2.0 Web 服务器流程

如需与 Android 开发者管理中心 API 集成，应用必须使用 OAuth 2.0 Web Server 流程。您可以根据应用类型和自动化需求，选择以下两种主要凭据管理策略之一：

选项 A（推荐）：离线 / 自动访问（CI/CD 和服务器集成） 选项 B：临时 / 互动访问
此策略允许自动化流程（如 CI/CD 流水线）在后台运行，无需人工干预：

一次性用户同意设置：在初始设置期间，开发者或账号所有者会在浏览器中完成一次性同意流程。您的应用会请求离线访问权限 (access_type=offline)，同时还会请求 API 范围。Google 会返回一个授权代码，您的应用会将其交换为初始访问令牌和长期刷新令牌。

后台执行：在部署环境或 Secret Manager（例如 GitHub Actions Secrets、Google Secret Manager）中安全地存储 refresh_token。对于后续的 API 调用，自动化工作流程会使用存储的刷新令牌按需获取新的短期有效的访问令牌，从而绕过任何手动登录或双重身份验证提示。 		如果您希望避免在环境中存储长期有效的刷新令牌，或者您的应用在交互式用户上下文中运行，请执行以下操作：

在执行时提示：不请求离线访问权限，也不存储刷新令牌。每次执行该工具或应用时，通过将用户重定向到浏览器中的 Google OAuth 同意页面，提示用户进行身份验证。

短期有效的访问令牌：用户登录并同意授权后，应用会直接（或通过授权代码交换）收到短期有效的访问令牌。此访问令牌用于进行 API 调用，并在执行后被舍弃。后续运行需要用户重新进行身份验证。

注册软件包名称

软件包名称注册是将密钥与软件包名称相关联的过程。 密钥的注册方式取决于您是在 Android 中为新软件包名称注册密钥，还是为现有软件包名称注册密钥。

注册新软件包名称

对于从未在 Android 上出现过的新软件包名称，您可以提供应用签名密钥对中的公钥证书。

注册现有软件包名称

如需注册现有软件包名称，您必须证明对已知签名私钥的所有权。与注册新名称的步骤不同，该 API 会返回符合注册条件的已知公共证书指纹列表。这些密钥可用于直接注册。

如果您要注册的密钥被列为“需要提供正当理由”，您仍然可以注册该密钥，但除了完成所有权证明之外，开发者还需要提交使用相应软件包名称的正当理由。

关键资格甄别规则

合格密钥列表取决于旨在最大限度减少软件包名称共用情况的软件包名称合格规则，该规则已被纳入 Android 开发者验证流程。

如果多位开发者使用了同一软件包名称或某个软件包名称具有多个签名密钥，则密钥是否合格按以下方式确定：

场景 针对直接注册的规则 针对其他开发者的规则
名称有多个密钥 占已知总安装量 50% 以上的密钥具有优先权。 所有其他开发者都必须提供正当理由。
安装量超过 50 次 如果没有任何一个密钥的安装量超过总安装量的 50%，则安装量达到或超过 50 次的所有密钥均合格。 如果开发者所持密钥的安装量少于 50 次，则必须提供正当理由。
安装量不足 50 次 如果所有密钥均未达到 50 次安装的门槛，则可以按“先到先得”原则使用任何密钥 一旦有开发者进行了注册，其他开发者就必须提供正当理由。

验证密钥所有权

如需完成现有软件包名称的验证，API 会提供验证字符串。此验证字符串需要包含在应用资源文件夹中名为 adi-registration.properties 的新文件中。然后，您必须使用与您要注册的公钥对应的私钥为 APK 签名并上传该 APK。

证明密钥注册的合理性

如果密钥注册需要提供理由，开发者必须提交详细的业务原理说明。Google 会审核此理由，软件包名称注册审批时间最长可能需要 24 小时。

用户体验最佳做法

建议使用 Android 开发者管理中心 API 的应用遵循以下模式，以确保无缝集成。

建立清晰的 OAuth 授权上下文

在请求 OAuth 授权之前提供明确的上下文有助于开发者了解为何需要账号访问权限。为了有效地引导用户，请在启动 OAuth 权限请求页面之前，清晰说明预期功能。

使用以下格式构建授权上下文：

  • 标题：“关联您的 Android 开发者管理中心账号”
  • 摘要：“在 [application-name] 中管理 Android 开发者验证的软件包名称注册”
  • 操作按钮：“使用 Google 账号继续”或“使用 Google 账号登录”按钮
对话框：说明了用于关联账号的 OAuth 授权上下文。
图 1. 清除 OAuth 授权上下文对话框布局。

确定开发者账号

  1. 与 ListDeveloperAccounts API 方法集成，以检索和列出已授权访问的所有开发者账号。
  2. 提供账号选择器，以便开发者选择其首选的开发者账号。
  3. 突出显示账号 displayName，使用 name 字段中的账号号码作为次要信息。
  4. 显示账号验证状态 (verificationState)：
    • VERIFIED：通过醒目的视觉提示（例如绿色对勾标记）确认经过验证的开发者身份。
    • NOT_VERIFIED：表示验证未完成，并限制相应账号的软件包注册。（可选）提供一个主要行动号召按钮，以便开发者在选择账号后前往 Android 开发者管理中心。
显示开发者账号名称和验证状态的账号选择器。
图 2. 显示开发者账号和验证状态的账号选择器。

如果因没有与 Google 账号关联的开发者账号而收到空响应，请使用主要行动号召按钮引导开发者前往 Android 开发者管理中心。

管理软件包名称

  1. 与 ListAndroidPackages API 端点集成，以检索与开发者账号关联的所有软件包名称。为开发者提供集中式界面（例如列表或表格），以便他们有效地监控软件包状态。
  2. 显示 packageName 以及其当前的注册状态（DRAFT、IN_REVIEW、REGISTERED 或 PENDING_TRANSFER），并为每种状态应用不同的视觉指示器。如果在创建期间提供并保存了“别名”，您可以选择将其包含在显示内容中。
显示已注册的软件包名称及其状态的界面。
图 3. 用于管理软件包名称和注册状态的接口。

管理密钥

  1. 调用 ListAndroidPackageKeys API 端点以提取与软件包名称关联的所有密钥，从而为开发者提供结构化概览（例如表格或列表）来监控其注册状态。
  2. 显示每个密钥的 certificateFingerprintSha256 以及其注册状态（DRAFT、OWNERSHIP_VERIFIED、IN_REVIEW、REGISTERED_ACTIVE 或 PENDING_TRANSFER），并使用不同的视觉指示器来区分状态。
证书指纹和密钥注册状态的列表。
图 4. 密钥及其注册状态的概览。
  1. 通过与 CreateAndroidPackageKey API 方法集成，使开发者能够注册现有软件包名称下的其他密钥。

注册软件包名称

  1. 使用基于表单的布局，让开发者在文本字段中输入其软件包名称，前提是您的应用尚未收集此信息（例如，通过之前的提示）。
  2. 调用 CreateAndroidPackage API 方法可在开发者账号下注册软件包名称，并调用 GetAndroidPackageRegistrationPolicy API 方法来确定适用的密钥资格规则。
  3. 根据为软件包名称指定的 keySelectionStrategy，提示开发者执行以下操作之一：
    • 如果 keySelectionStrategy 设置为 SELECT_KEY_FROM_LIST：让开发者从提供的 knownKeys 列表（包含 SHA-256 证书指纹）中选择一个密钥进行注册，例如使用单选按钮。此流程需要进行密钥所有权验证（请参阅下文中的验证密钥的所有权）。
    • 如果 keySelectionStrategy 设置为 USE_ANY_KEY：提示开发者直接提供密钥。在这种情况下，无需验证密钥所有权。
  4. 调用 CreateAndroidPackageKey API 方法，将所选密钥与新软件包名称相关联。
用于注册软件包名称和选择签名密钥的表单。
图 5. 注册软件包名称并选择密钥的流程。

或者，您的应用可以自动检测并直接从上传的应用中提取软件包名称或密钥。

验证密钥的所有权

当 keySelectionStrategy 设置为 SELECT_KEY_FROM_LIST 时，开发者必须证明其签名私钥的所有权。所有权证明需要提交包含 API 生成的 verificationToken 的已签名 APK。

为了支持密钥所有权验证，请集成 VerifyAndroidPackageKeyOwnership API 方法并构建以下界面组件：

  • 令牌显示组件：在代码段块中醒目地显示 verificationToken，并提供便捷的“复制到剪贴板”按钮。
  • 开发者设置说明：提供详细说明，指导开发者将包含 verificationToken 的 adi-registration.properties 文件放入应用的资源文件夹中。
  • APK 提交放置区：提供专门的文件上传放置区来接收已签名的 APK。
用于验证密钥所有权的放置区和令牌显示。
图 6. 用于通过上传已签名的 APK 来验证密钥所有权的界面组件。

说明注册密钥的理由

如果已知密钥的 justificationRequired 字段设置为 REQUIRED，则注册该密钥以及软件包名称需要开发者提交详尽的业务理由。

通过调用 JustifyAndroidPackageKeyRegistration API 方法提交此正当理由。确保您的应用界面包含一个专用文本输入区域，用于收集开发者的正当理由，并通知开发者在提交密钥注册请求之前必须提供正当理由。Google 会审核提交的正当理由，此流程最多可能需要 24 小时才能完成审批，然后才能完成软件包名称注册。

自动执行受管理密钥的密钥验证

如果您的应用管理开发者的签名密钥，则开发者无法手动为 APK 签名以进行所有权验证。您必须改为代表用户自动执行 VerifyAndroidPackageKeyOwnership API 调用。

通过自动处理令牌包含和 APK 上传流程，您的应用可移除这些手动步骤。请务必通知开发者，您的应用会使用存储在系统中的密钥无缝管理密钥所有权验证。

遵循品牌推广指南

为了维护用户信任并确保透明度，所有与 Android 开发者管理中心 API 集成的应用都必须遵守以下品牌推广指南。

术语和大小写

在面向用户的材料或文档中提及本产品时，请务必使用全称“Android 开发者管理中心”。请勿使用缩写“ADC”。

该计划必须称为“Android 开发者验证”。在所有情况下，都应严格遵循此大小写和拼写。

为避免与 APK 或 AAB 混淆，请专门使用“软件包名称”一词，而不是仅使用“软件包”。

在描述添加软件包名称的过程时，请使用“注册软件包名称”一词，而不是“声明软件包名称”。

使用“登录”号召性用语

Android 开发者管理中心的 OAuth 2.0 身份验证依赖于 Google Identity 服务。为确保符合 Google Identity 服务品牌推广指南，您必须在授权按钮上使用“继续使用 Google”或“使用 Google 账号登录”号召性用语。此文本是强制性的，无法修改，因为它可以确保用户了解他们正在使用自己的 Google 凭据授权您的应用访问其 Google 账号。

维护品牌身份和完整性

将 Android 开发者管理中心徽标集成到应用界面中时，您必须遵循以下规范，以保持视觉标识和品牌完整性：

  • 徽标放置位置和层次结构：仅使用官方认可的 Android 开发者管理中心徽标。徽标必须始终次于您自己的应用的主要品牌推广元素，以免将应用误认为 Google 的官方产品。
Android 开发者管理中心官方徽标。点击即可保存文件。
图 7. Android 开发者管理中心官方徽标。点击相应图片即可保存文件。
  • 视觉样式和变形：素材资源必须始终以完全受限的宽高比进行渲染。您绝不得扭曲、拉伸、倾斜、剪裁、翻转或修改徽标的组成部分。请勿更改官方调色板、交换前景颜色或背景颜色，也不要应用阴影、发光效果或装饰性渐变。
  • 使用限制：请勿将任何 Google 自有的品牌推广元素纳入您自己的应用资源中。Android 开发者管理中心徽标素材资源只能在应用布局上下文中使用，以明确表示存在有效的集成。

其他资源