使用 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 控制台。
  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 專案) 相關聯，因此無法使用服務帳戶、工作負載身分聯盟和 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 管道) 在背景執行，無需人為介入：

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

背景執行：在部署環境或密鑰管理工具 (例如 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。

說明金鑰註冊的理由

如果金鑰註冊需要理由，開發人員必須提交詳細的業務理由。Google 會審查這項理由，套件名稱註冊核准程序最多可能需要 24 小時。

使用者體驗最佳做法

建議使用 Android 開發人員控制台 API 的應用程式遵循這些模式，確保完美整合。

建立明確的 OAuth 授權脈絡

在要求 OAuth 授權前提供明確的背景資訊，有助於開發人員瞭解為何需要帳戶存取權。為有效引導使用者，請在啟動 OAuth 同意畫面之前，清楚說明預期功能。

請使用下列格式建構授權環境：

  • 標題：「連結 Android 開發人員控制台帳戶」
  • 摘要：「在『[應用程式名稱]』中管理 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，開發人員必須證明自己擁有私密簽署金鑰。如要證明擁有權，請提交已簽署的 APK，其中包含 API 產生的 verificationToken。

如要支援金鑰擁有權驗證，請整合 VerifyAndroidPackageKeyOwnership API 方法，並建構下列使用者介面元件：

  • 權杖顯示元件：在程式碼片段區塊內醒目顯示 verificationToken，並提供實用的「複製到剪貼簿」按鈕。
  • 開發人員設定說明：提供詳細說明，引導開發人員將包含 verificationToken 的 adi-registration.properties 檔案放入應用程式的資產資料夾。
  • APK 提交區：提供專屬的檔案上傳區，接收已簽署的 APK。
用於驗證金鑰擁有權的放置區和權杖顯示畫面。
圖 6. 透過上傳已簽署的 APK 驗證金鑰擁有權的 UI 元件。

說明註冊金鑰的理由

如果已知金鑰的 justificationRequired 欄位設為 REQUIRED，開發人員必須提交詳盡的商家理由，才能註冊該金鑰和套件名稱。

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

自動驗證代管金鑰

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

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

遵循品牌宣傳指南

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

術語與大小寫

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

請務必將這項計畫稱為「Android 開發人員驗證」。在所有情境中，請務必使用這個大小寫和拼字。

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

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

使用「登入」行動號召

Android 開發人員控制台的 OAuth 2.0 驗證功能依賴 Google 身分識別服務。為確保符合 Google Identity 服務品牌宣傳指南，授權按鈕必須使用「使用 Google 帳戶繼續」或「使用 Google 帳戶登入」的號召性動作。這段文字為必填，且無法修改，因為這段文字可確保使用者瞭解他們是使用 Google 憑證授權應用程式存取 Google 帳戶。

維護品牌識別和完整性

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

  • 標誌位置和階層：請只使用官方核准的 Android 開發人員控制台標誌。標誌一律不得搶走應用程式主要品牌宣傳元素的風采，以免誤導使用者，以為應用程式是 Google 官方產品。
Android 開發人員控制台官方標誌。按一下即可儲存檔案。
圖 7. Android 開發人員控制台官方標誌。按一下圖片即可儲存檔案。
  • 視覺風格和扭曲：資產一律必須以完全受限的長寬比呈現。請勿扭曲、延展、傾斜、裁剪、翻轉或修改標誌的任何部分。請勿變更官方色調、互換前景或背景顏色，或是套用投射陰影、發光效果或裝飾性漸層。
  • 使用限制：請勿在自己的應用程式資產中加入任何 Google 擁有的品牌宣傳元素。Android 開發人員控制台標誌資產只能在應用程式版面配置環境中使用，明確表示整合作業正在進行中。

其他資源