使用 Android 開發人員控制台 API 註冊套件名稱

Android Developer Console 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 控制台。
  3. 建立 Google Cloud 專案。

在 Google Cloud 專案中啟用 API

  1. 開啟 Google Cloud 控制台。
  2. 在導覽選單 (☰) 中，依序選取「API 和服務」>「程式庫」。
  3. 從專案下拉式選單中，選取要啟用 API 的 Google Cloud 專案。
  4. 使用「API 和服務」搜尋列，選取「Android 開發人員控制台 API」。
  5. 啟用 API：
    1. 從搜尋結果中選取 API，前往 API 的總覽頁面。
    2. 點選藍色的「啟用」按鈕。Google Cloud 會為所選專案啟用 API，這項作業通常很快就會完成。啟用後即可開始使用。

驗證 API

如要呼叫 Android 開發人員控制台 API，您必須使用 OAuth 2.0 驗證要求。

使用 OAuth 2.0 進行驗證

Android 開發人員控制台 API 必須使用 OAuth 2.0 驗證，才能授權存取開發人員帳戶資源和套件名稱。由於開發人員帳戶資料與使用者的 Google 帳戶 (而非 Google Cloud 專案) 綁定，因此無法使用服務帳戶、Workload Identity Federation 和 API 金鑰驗證 API 要求。

OAuth 2.0 範圍

所有作業都需要下列範圍：

OAuth 2.0 範圍 說明
https://www.googleapis.com/auth/androiddeveloperconsole 查看及管理 Android 開發人員控制台帳戶中的套件名稱和資料

實作 OAuth 2.0 網路伺服器流程

如要與 Android 開發人員控制台 API 整合，應用程式必須使用 OAuth 2.0 網路伺服器流程。視應用程式類型和自動化需求而定，您可以選擇兩種主要的憑證管理策略：

做法 A (建議)：離線 / 自動化存取 (CI/CD 和伺服器整合) 選項 B：暫時性 / 互動式存取權
這項策略可讓自動化程序 (例如 CI/CD 管道) 在背景執行，不需人工介入：

一次性使用者同意聲明設定：在初始設定期間，開發人員或帳戶擁有者會在瀏覽器中完成一次性同意聲明流程。您的應用程式要求離線存取權 (access_type=offline) 和 API 範圍。Google 會傳回授權碼，您的應用程式會將其交換為初始存取權杖和長期更新權杖。

背景執行：將 refresh_token 安全地儲存在部署環境或密鑰管理工具 (例如 GitHub Actions Secrets、Google Secret Manager)。後續呼叫 API 時，自動化工作流程會使用儲存的更新權杖，視需要取得新的短期存取權杖，略過任何手動登入或雙重驗證提示。 		如果您不想在環境中儲存長期更新權杖，或應用程式是在互動式使用者環境中執行：

在執行時提示：不要要求離線存取權或儲存更新權杖。每次執行工具或應用程式時，請將使用者重新導向至瀏覽器中的 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：表示驗證未完成，並限制帳戶註冊套件。您也可以提供主要行動號召按鈕，讓開發人員選取帳戶後，直接前往 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. UI 元件，用於透過上傳已簽署的 APK 驗證金鑰擁有權。

說明註冊金鑰的原因

如果已知金鑰的 justificationRequired 欄位設為 REQUIRED， 開發人員必須提交完整的業務理由，才能一併註冊該金鑰和套件名稱。

請呼叫 JustifyAndroidPackageKeyRegistration API 方法提交這項理由。請確保應用程式的使用者介面設有專屬文字輸入區，用於收集開發人員的理由，並通知他們必須提供理由，才能提交金鑰註冊要求。Google 會審查提交的正當理由，這項程序最多可能需要 24 小時才能核准，之後套件名稱註冊才會完成。

自動驗證受管理金鑰

如果您的應用程式會管理開發人員的簽署金鑰，開發人員就無法手動簽署 APK 來驗證擁有權。您必須代表使用者自動執行 VerifyAndroidPackageKeyOwnership API 呼叫。

應用程式會自動處理權杖納入和 APK 上傳程序，因此您不必手動執行這些步驟。請務必通知開發人員，應用程式會使用系統中儲存的金鑰，順暢管理金鑰擁有權驗證。

遵循品牌宣傳指南

為維護使用者信任並確保資訊公開，所有與 Android Developer Console API 整合的應用程式，都必須遵守下列品牌宣傳指南。

術語和大小寫

在面向使用者的資料或說明文件中提及產品時，請一律使用全名「Android 開發人員控制台」。請勿使用縮寫「ADC」。

這項計畫必須稱為 Android 開發人員驗證。在所有情況下，請務必按照這個大小寫和拼寫方式。

為避免與 APK 或 AAB 混淆，請使用「套件名稱」一詞，而非僅使用「套件」。

說明新增套件名稱的程序時，請使用「註冊套件名稱」一詞，而非「聲明套件名稱」。

使用「登入」行動號召

Android 開發人員控制台的 OAuth 2.0 驗證機制仰賴 Google Identity Services。為遵守 Google Identity 服務品牌宣傳指南，授權按鈕必須使用「使用 Google 帳戶繼續」或「使用 Google 帳戶登入」行動號召。這段文字為必填，且無法修改，目的是確保使用者瞭解自己正在使用 Google 憑證，授權您的應用程式存取其 Google 帳戶。

維護品牌識別和完整性

將 Android 開發人員控制台標誌整合至應用程式介面時，請務必遵循下列規格，以維持視覺識別和品牌完整性：

  • 標誌位置和階層：僅使用官方核准的 Android 開發人員控制台標誌。標誌必須一律次於應用程式的主要品牌元素，以免誤導使用者認為應用程式是 Google 官方產品。
Android 開發人員控制台官方標誌。按一下即可儲存檔案。
圖 7. Android 開發人員控制台官方標誌。按一下圖片即可儲存檔案。
  • 視覺風格和變形：素材資源顯示時，顯示比例必須完全受限。請勿扭曲、拉伸、傾斜、裁剪、翻轉或修改標誌的任何部分。請勿更改官方調色盤、調換前景或背景顏色，或套用投射陰影、光暈效果或裝飾性漸層。
  • 使用限制：請勿在自己的應用程式素材資源中加入任何 Google 擁有的品牌元素。Android 開發人員控制台標誌素材資源只能在應用程式版面配置環境中使用，明確表示有效整合。

其他資源