Android Developer Console API でパッケージ名を登録する

Android Developer Console API は、アプリの販売元と個々のデベロッパーが Android Developer Console でパッケージ名をプログラムで登録できるように設計された公開インターフェースです。

サーバー間機能（）

アプリの販売元 個々のデベロッパー
ストアにアプリを公開するデベロッパーに代わってパッケージ名 - 鍵を登録する。ストアで管理される鍵を使用してパッケージ名を登録する。パッケージ名に関連付けられた鍵の所有権を証明する。 継続的デプロイ ワークフローでパッケージ名 - 鍵を登録する。パッケージ名に関連付けられた鍵の所有権を証明する。

始める前に

始める前に、次のものを用意してください。

  1. Google Cloud プロジェクトに対する管理者権限。
  2. 次の基本的な知識。

以下の用語についても知っておく必要があります。

用語 定義
デベロッパー アカウント 1 つ以上のパッケージ名を所有できる Android Developer Console アカウントを表します。確認ステータス（NOT_VERIFIED または VERIFIED）が含まれます。
パッケージ名 デベロッパー アカウント内の特定の Android パッケージ名（com.example.app など）。1 つ以上の鍵に関連付けることができます。登録ステータス（DRAFT、IN_REVIEW、REGISTERED、PENDING_TRANSFER）が含まれます。
キー Android パッケージ名の署名に使用される特定の公開鍵証明書/鍵。SHA-256 ハッシュと現在の登録ステータス（DRAFT、OWNERSHIP_VERIFIED、IN_REVIEW、REGISTERED、PENDING_TRANSFER）が含まれます。

始める

Android Developer Console 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 Developer Console API] を選択します。
  5. API を有効にします。
    1. 検索結果から API を選択して、API の概要ページに移動します。
    2. 青色の [有効にする] ボタンをクリックします。Google Cloud は、選択したプロジェクトの API を有効にします。通常、これには数分しかかかりません。有効にすると、使用を開始できます。

API を認証する

Android Developer Console API を呼び出すには、OAuth 2.0 を使用してリクエストを認証する必要があります。

OAuth 2.0 で認証する

Android Developer Console API では、デベロッパー アカウントのリソースとパッケージ名へのアクセスを承認するために OAuth 2.0 認証が必要です。デベロッパー アカウントのデータは Google Cloud プロジェクトではなくユーザーの Google アカウントに関連付けられているため、サービス アカウント、Workload Identity 連携、API キーを使用して API リクエストを認証することはできません。

OAuth 2.0 スコープ

すべてのオペレーションに次のスコープが必要です。

OAuth 2.0 スコープ 説明
https://www.googleapis.com/auth/androiddeveloperconsole Android Developer Console アカウントのパッケージ名とデータの参照、管理

OAuth 2.0 ウェブサーバー フローを実装する

Android Developer Console API と統合するには、アプリケーションで OAuth 2.0 ウェブサーバー フローを使用する必要があります。アプリケーションのタイプと自動化のニーズに応じて、次の 2 つの主要な認証情報管理戦略から選択できます。

オプション A（推奨）: オフライン / 自動アクセス（CI/CD とサーバーの統合） オプション B: 一時的な / インタラクティブなアクセス
この戦略では、自動化されたプロセス（CI/CD パイプラインなど）をユーザーの操作なしでバックグラウンドで実行できます:

ユーザーの同意設定（1 回限り）: 最初の設定時に、デベロッパーまたはアカウント オーナーがブラウザで 1 回限りの同意フローを完了します。アプリケーションは、API スコープとともにオフライン アクセス（access_type=offline）をリクエストします。Google は認証コード を返します。アプリケーションは、この認証コードを最初のアクセス トークン と長期の更新トークン と交換します。

バックグラウンド実行: refresh_token をデプロイ環境またはシークレット マネージャー（GitHub Actions Secrets、Google Secret Manager など）に安全に保存します。以降の API 呼び出しでは、自動化されたワークフローで保存された更新トークンを使用して、必要に応じて有効期間の短い新しいアクセス トークンを取得します。手動ログインや 2 要素認証のプロンプトは表示されません。 		環境に長期の更新トークンを保存したくない場合や、アプリケーションがインタラクティブなユーザー コンテキストで実行される場合は、次の手順を行います。

実行時にプロンプトを表示: オフライン アクセスをリクエストしたり、更新トークンを保存したりしないでください。ツールまたはアプリケーションが実行されるたびに、ブラウザで Google OAuth 同意ページにリダイレクトして、ユーザーに認証を求めます。

有効期間の短いアクセス: ユーザーがログインして同意すると、アプリケーションは有効期間の短いアクセス トークンを直接（または認可コード交換を使用して）受け取ります。このアクセス トークンは API 呼び出しに使用され、実行後に破棄されます。今後実行するには、ユーザーが再認証する必要があります。

パッケージ名を登録する

パッケージ名の登録とは、鍵をパッケージ名に関連付けるプロセスです。 鍵の登録方法は、Android で新規のパッケージ名に鍵を登録するか、既存のパッケージ名に鍵を登録するかによって異なります。

新規のパッケージ名を登録する

Android で一度も使用されたことのない新規のパッケージ名を登録する場合は、アプリの署名鍵ペアの 公開鍵証明書を指定するだけで登録できます。

既存のパッケージ名を登録する

既存のパッケージ名を登録するには、既知の署名用の秘密鍵の所有権を証明する必要があります。新規登録の場合とは異なり、API は登録可能な既知の公開鍵証明書フィンガープリントのリストを返します。これらの鍵は直接登録に使用できます。

登録する鍵が「正当化が必要」と表示されている場合でも登録できますが、所有権の証明を完了するだけでなく、デベロッパーはパッケージ名の使用を正当化する理由を提出する必要があります。

鍵の利用資格ルール

利用可能な鍵のリストは、パッケージ名の共有を最小限に抑えられるように設計されたパッケージ名の利用資格ルールに基づいて決定されます（Android デベロッパーの確認の一環として導入されました）。

パッケージ名が複数のデベロッパーによって使用されている場合や、複数の署名鍵が存在する場合は、以下のルールに基づいて利用資格が判断されます。

シナリオ 直接登録のルール その他のデベロッパーに適用されるルール
過半数を占める鍵所有者 既知の合計インストール数の 50% 以上を占める鍵が優先されます。 その他すべてのデベロッパーは正当化の理由を提出する必要があります。
インストール数が 50 件以上 50% 以上を占める鍵が一つもない場合は、インストール数が 50 件以上のすべての鍵が対象になります。 50 件を占める鍵がないデベロッパーは、正当化の理由を提出する必要があります。
インストール数が 50 件未満 インストール数 50 件以上という基準値を満たす鍵がない場合は、すべての鍵が先着順で利用可能になります。 最初のデベロッパーが登録すると、他のデベロッパーは正当化の理由を提出しなければならなくなります。

鍵の所有権を確認する

既存のパッケージ名の確認を完了するために、API は確認文字列を提供します。この確認文字列は、アプリのアセット フォルダ内の adi-registration.properties という名前の新しいファイルに含める必要があります。次に、登録する公開鍵に対応する秘密鍵を使用して APK に署名し、アップロードする必要があります。

鍵の登録を正当化する

鍵の登録に正当化の理由が必要な場合は、デベロッパーが詳細なビジネス上の理由を提出する必要があります。Google がこの正当化の理由を確認し、パッケージ名の登録が承認されるまでに最大 24 時間かかることがあります。

ユーザー エクスペリエンスのベスト プラクティス

Android Developer Console API を使用するアプリケーションでは、シームレスな統合を確保するために、次のパターンに従うことをおすすめします。

OAuth 認証のコンテキストを明確にする

OAuth 認証をリクエストする前に明示的なコンテキストを提供することで、デベロッパーはアカウントへのアクセスが必要な理由を理解できます。ユーザーを効果的に誘導するには、OAuth 同意画面を起動する前に、想定される機能について明確に説明します。

次の形式で認証コンテキストを構成します。

  • タイトル: 「Android Developer Console アカウントをリンクする」
  • 概要: 「[アプリケーション名] 内で Android デベロッパーの確認用のパッケージ名の登録を管理する」
  • 操作ボタン: [Google で続行] ボタンまたは [Google でログイン] ボタン
アカウントをリンクするための OAuth 認証コンテキストを示すダイアログ。
図 1.OAuth 認証コンテキストのダイアログ レイアウトをクリアします。

デベロッパー アカウントを特定する

  1. ListDeveloperAccounts API メソッドと統合して、アクセスが承認されているすべてのデベロッパー アカウントを取得して一覧表示します。
  2. デベロッパーが優先するデベロッパー アカウントを選択できるように、アカウント選択ツールを提供します。
  3. アカウントの displayName を目立つように表示し、name フィールドの口座番号を補足情報として使用します。
  4. アカウント確認ステータス（verificationState）を表示します。
    • VERIFIED: 確認済みのデベロッパー ID を肯定的な視覚的合図（緑色のチェックマークなど）で確認します。
    • NOT_VERIFIED: 確認が完了していないことを示し、アカウントのパッケージ登録を制限します。必要に応じて、アカウントを選択したときにデベロッパーを Android Developer Console に誘導するプライマリ CTA ボタンを表示します。
デベロッパー アカウント名と確認ステータスが表示されたアカウント選択ツール。
図 2.デベロッパー アカウントと確認ステータスを表示するアカウント選択ツール。

Google アカウントに関連付けられているデベロッパー アカウントがないため、空のレスポンスが返された場合は、プライマリ CTA ボタンを使用してデベロッパーを Android Developer Console に誘導します。

パッケージ名を管理する

  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 のアップロードで鍵の所有権を確認するための UI コンポーネント。

鍵の登録を正当化する

既知の鍵の justificationRequired フィールドが REQUIRED に設定されている場合、パッケージ名とともにその鍵を登録するには、デベロッパーがビジネス上の理由を詳しく提出する必要があります。

この正当化の理由を提出するには、JustifyAndroidPackageKeyRegistration API メソッドを呼び出します。アプリケーションのユーザー インターフェースに、デベロッパーから正当化の理由を収集するための専用のテキスト入力領域を設け、鍵の登録リクエストを送信する前に理由を提出する必要があることを通知します。Google が提出された正当化の理由を確認します。パッケージ名の登録が完了するまでに最大 24 時間かかることがあります。

管理対象の鍵の鍵の確認を自動化する

アプリケーションがデベロッパーの署名鍵を管理している場合、デベロッパーは所有権の確認のために APK に手動で署名することはできません。代わりに、VerifyAndroidPackageKeyOwnership API 呼び出しをデベロッパーに代わって自動的に実行する必要があります。

トークンの組み込みと APK のアップロード プロセスを自動的に処理することで、アプリケーションはこれらの手動の手順を排除します。鍵の所有権の確認は、システムに保存されている鍵を使用してアプリケーションによってシームレスに管理されることをデベロッパーに通知してください。

ブランド ガイドラインを遵守する

ユーザーの信頼を維持し、透明性を確保するため、Android Developer Console API と統合するすべてのアプリケーションは、次のブランド ガイドラインを遵守する必要があります。

用語と大文字の使用

ユーザー向けの資料やドキュメントでプロダクトを参照する場合は、常にフルネームの Android Developer Console を使用してください。「ADC」という略語は使用しないでください。

プログラムは Android デベロッパーの確認と呼ぶ必要があります。すべてのコンテキストで、この大文字と小文字の区別とスペルに従ってください。

APK や AAB との混同を避けるため、「パッケージ」ではなく「パッケージ名」という用語を具体的に使用してください。

パッケージ名を追加するプロセスについて説明する場合は、「パッケージ名を申し立てる」ではなく「パッケージ名を登録する」というフレーズを使用してください。

[ログイン] の行動を促すフレーズを使用する

Android Developer Console での OAuth 2.0 認証は、Google Identity Services に依存しています。 Google Identity Services のブランド ガイドラインに準拠するには、認可ボタンに「Google で続行」または「Google でログイン」の行動を促すフレーズを使用する必要があります。このテキストは必須であり、変更することはできません。ユーザーが Google 認証情報を使用して、Google アカウントへのアクセスをアプリケーションに認可していることをユーザーが理解できるようにするためです。

ブランド アイデンティティと完全性を維持する

Android Developer Console のロゴをアプリケーション インターフェースに統合する場合は、視覚的なアイデンティティとブランドの完全性を維持するために、次の仕様に従う必要があります。

  • ロゴの配置と階層: 公式の承認済み Android Developer Console ロゴのみを使用してください。ロゴは、アプリケーションが Google の公式プロダクトであると誤解されないように、常にアプリケーション独自の主要なブランディング要素の二次的なものにする必要があります。
Android Developer Console の公式ロゴ。クリックしてファイルを保存します。
図 7.Android Developer Console の公式ロゴ。画像をクリックしてファイルを保存します。
  • ビジュアル スタイルと歪み: アセットは常にアスペクト比を完全に制約してレンダリングする必要があります。ロゴのコンポーネントを歪めたり、引き伸ばしたり、傾けたり、切り抜いたり、反転させたり、変更したりしないでください。公式のカラーパレットを変更したり、前景色と背景色を入れ替えたり、ドロップ シャドウ、グロー効果、装飾的なグラデーションを適用したりしないでください。
  • 使用制限: Google が所有するブランディング要素をアプリケーション アセットに組み込まないでください。Android Developer Console のロゴ アセットは、アプリケーション レイアウト コンテキスト内でのみ使用して、アクティブな統合を明示的に示すことができます。

参考情報