使用 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 账号（如果您还没有）。
  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 服务器流程。您可以根据应用类型和自动化需求，在两种主要凭证管理策略之间进行选择：

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

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

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

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

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

注册软件包名称

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

注册新软件包名称

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

注册现有软件包名称

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

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

关键资格规则

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

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

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

验证密钥所有权

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

证明密钥注册的合理性

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

用户体验最佳做法

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

建立清晰的 OAuth 授权上下文

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

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

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

识别开发者账号

  1. 与 ListDeveloperAccounts API 方法集成，以检索和列出已获授权访问的所有开发者账号。
  2. 提供账号选择器，以便开发者选择其首选开发者账号。
  3. 突出显示账号 displayName，并将 name 字段中的账号作为次要信息。
  4. 显示账号验证状态 (verificationState)：
    • VERIFIED：通过醒目的视觉提示（例如绿色对勾标记）确认已验证的开发者身份。
    • NOT_VERIFIED：表示验证未完成，并限制该账号注册软件包。（可选）提供一个主要 CTA 按钮，以便在选择账号后将开发者引导至 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，开发者必须证明其私有签名密钥的所有权。所有权证明需要提交一个已签名的 APK，其中包含 API 生成的 verificationToken。

如需支持密钥所有权验证，请集成 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 开发者管理中心徽标素材资源只能在应用布局上下文中使用，以明确表示存在有效的集成。

其他资源