App Store Review API デベロッパー ガイド

App Store Review API を使用すると、Google Play のサードパーティのアプリストア プログラムを通じて Google Play に登録されているサードパーティのアプリストアは、ストアでホストされているアプリに必要な詳細情報を提供できます。この情報には、アプリのメタデータ、掲載情報、APK バイナリ、ポリシー遵守の宣言が含まれます。

エンドポイント、メソッド、リソース スキーマの一覧については、App Store Review API リファレンスをご覧ください。

始める前に

App Store Review API を呼び出すには、メインのスタートガイドを完了して、API アクセス、サービス認証情報、Google Cloud プロジェクトを設定しておく必要があります。App Store Review API は、アプリストアごとに 1 分あたり最大 300 件のリクエストを想定しています。

API の設計とアーキテクチャ

App Store Review API は、アトミック スナップショット パターンで動作します。トランザクション セッションを使用するのではなく、ファイルを個別にアップロードしてから、単一のアトミック呼び出しで完全な状態をコミットします。

  1. 個々のファイルとアセット（APK、画像、ポリシー ファイル）は、個別の直接呼び出しでアップロードします。
  2. これらのファイルの返された ID をキャッシュに保存します。
  3. 単一の最終的な UpdateAppStoreHostedApp リクエストを送信して、ホスト型アプリの状態全体をアトミックにコミットします。

1. 登録

ホスト型アプリを登録するには、createappstorehostedapp メソッドを呼び出し、アプリのパッケージ名とストアのパッケージ名を指定します。リクエストとレスポンスのスキーマの詳細については、API リファレンスをご覧ください。

2. バイナリとアセットのアップロード

ホスト型アプリを登録したら、専用のアップロード エンドポイントを使用してアセットをアップロードする必要があります。

  • APK: アプリのすべての有効な配布 APK バイナリ（uploadapk を使用）。
  • 画像: アプリアイコンやスクリーンショットなどの画像アセット（uploadimage を使用）。
  • ポリシー: （関連する場合）ポリシー関連のドキュメント（uploadappstoreapppolicydeclarationfile を使用）。

アセットのキャッシュ保存と再利用

帯域幅とパフォーマンスを最適化するため、同じアセットを再アップロードしないでください。返される apkId、imageId、fileId のトークンはすべて永続的です。これらの ID を独自のバックエンド データベースにキャッシュに保存して、後続のホスト型アプリの更新で再利用できます。たとえば、ホスト型アプリの説明を更新するが、アプリアイコンとスクリーンショットは変更しない場合は、次の更新呼び出しでキャッシュに保存された imageId トークンを使用します。

3. アセンブルしてコミット

すべてのアセットをアップロードしてそれぞれの ID を取得したら、ホスト型アプリの完全な状態をアセンブルして、updateappstorehostedapp メソッドを使用してコミットする必要があります。このメソッドは、ホスト型アプリの詳細、ローカライズされたストアの掲載情報、アクティブな APK セット、安全性に関する宣言の完全なアトミック表現を受け取ります。

この呼び出しにより、以前にアクティブだった状態がリクエストで指定された新しい状態に置き換えられます。

リクエスト本文の例

すべてのキー要素を示す、現実的で構文的に有効な JSON リクエスト本文を次に示します。

{
  "appStorePackageName": "com.example.thirdparty.store",
  "packageName": "com.example.hostedapp.game",
  "appDetails": {
    "developerName": "Adventure Games Studio Ltd.",
    "contactEmail": "support@adventuregames.example.com",
    "developerWebsite": "https://adventuregames.example.com"
  },
  "activeLocalizedStoreListings": [
    {
      "languageCode": "en-US",
      "appName": "Super Quest Legends",
      "shortDescription": "An epic fantasy RPG adventure.",
      "fullDescription": "Super Quest Legends is an immersive action RPG featuring real-time battles, customizable classes, and a deep fantasy narrative. Journey through a magical realm, fight epic bosses, and team up with friends in dungeon raids.",
      "appIconId": "987123",
      "screenshotId": [
        "102938",
        "475869",
        "384756"
      ],
      "videoLink": "https://www.youtube.com/watch?v=dQw4w9WgXcQ"
    },
    {
      "languageCode": "es-ES",
      "appName": "Super Quest Leyendas",
      "shortDescription": "Una aventura épica de RPG fantástico.",
      "fullDescription": "Super Quest Leyendas es un RPG de acción inmersivo con batallas en tiempo real, clases personalizables y una profunda narrativa de fantasía. Viaja a través de un reino mágico, lucha contra jefes épicos y únete a amigos en incursiones.",
      "appIconId": "987123",
      "screenshotId": [
        "102938",
        "475869",
        "384756"
      ]
    }
  ],
  "activeApks": {
    "activeApkSets": [
      {
        "baseApkId": "554433"
      },
      {
        "baseApkId": "990011"
      }
    ]
  },
  "policyDeclarations": [
    {
      "declarationId": "POLICY_DECLARATION_ID_TARGET_AUDIENCE_CONTENT",
      "responses": [
        {
          "questionId": "POLICY_QUESTION_ID_TAC_TARGET_AGE_GROUPS",
          "multipleChoiceResponse": {
            "values": [
              "POLICY_RESPONSE_CHOICE_ID_TAC_AGE_EIGHTEEN_AND_ABOVE"
            ]
          }
        },
        // ... other responses for TAC
      ]
    },
    {
      "declarationId": "POLICY_DECLARATION_ID_ADVERTISING_ID",
      "responses": [
        {
          "questionId": "POLICY_QUESTION_ID_AD_ID_IS_USED",
          "booleanResponse": {
            "value": false
          }
        }
        // ... other responses for AD_ID
      ]
    }
    // ... other declarations
  ]
}

ポリシーの申告

API を使用してアプリ情報を送信または更新する場合は、必要なポリシー宣言を含める必要があります。

申告に関する要件

次の宣言が対象となります。

すべてのアプリで追加の申告が必要かどうかを確認するために必要なこと:

  1. 健康アプリ: 健康アプリのポリシーでアプリが満たす必要のある要件を把握するため、アプリで使用しているヘルスケア機能をお知らせください。
  2. 金融取引機能: 金融取引機能を提供するアプリは、一部の国 / 地域で特定の規制を遵守することが必要になる場合があります。アプリの金融取引機能の正確かつ最新の情報をお送りください。お送りいただいた情報をもとに、担当チームが審査します。
  3. 広告 ID: アプリで広告 ID を使用しているかどうかを知らせることができます。
  4. テスト用認証情報（ログインの詳細）: ログインの詳細、メンバーシップ情報、位置情報などの認証情報に基づいてアプリの特定の機能が制限される場合は、該当する機能にアクセスするための手順を提供してください。
  5. プライバシー ポリシー: アプリのプライバシー ポリシーへのリンクと詳細。
  6. ターゲット ユーザーおよびコンテンツ: アプリの対象年齢層と、アプリのコンテンツに関するその他の情報をご提供ください。子供向けのアプリが安全で適切なものであることを確認するために必要な情報となります。
  7. 広告: アプリに広告が含まれているかどうかを申告する必要があります。

条件付きで必須:

  1. 行政アプリ: お客様のアプリがなんらかの行政機関で使用するものであるかどうかを申告してください。これには、中央政府や地方自治体が含まれます。お送りいただいた情報をもとに、担当チームが審査します。この申告が完了していない場合、アプリは行政アプリではないとみなされます。
  2. 子どもの安全基準: 「ソーシャル」または「マッチング」カテゴリのアプリに必要です。ソーシャル アプリやマッチング アプリに分類されるアプリについては、子どもの安全基準に関するポリシーに準拠するために、公表されている安全基準と連絡先情報をお知らせいただく必要があります。
  3. ニュース＆雑誌アプリ: 「ニュース＆雑誌」カテゴリのアプリに必要です。ニュース＆雑誌アプリの詳細を追加して、アプリの運営法人に関する透明性を確保してください。

API リクエストの構造

ポリシーの申告は、UpdateAppStoreHostedAppRequest の本文の policyDeclarations 配列内で提供されます。この配列の各項目は AppStoreAppPolicyDeclaration オブジェクトです。

AppStoreAppPolicyDeclaration オブジェクト:

  • declarationId（文字列、必須）: ポリシーの申告の一意の識別子（POLICY_DECLARATION_ID_FINANCE、POLICY_DECLARATION_ID_TARGET_AUDIENCE_CONTENT など）。
  • responses（PolicyResponse の配列、必須）: その特定の申告内の質問に対する回答のリスト。

PolicyResponse オブジェクト:

  • questionId（文字列、必須）: 回答される特定の質問の一意の識別子（POLICY_QUESTION_ID_FINANCIAL_PRODUCT_TYPES、POLICY_QUESTION_ID_TAC_TARGET_AGE_GROUPS など）。
  • value（必須）: 回答自体。次のいずれかのタイプになります。
    • booleanResponse: 「はい」または「いいえ」の質問の場合。
      • value（ブール値）
    • stringResponse: URL を含む書式なしテキストの回答。
      • value（文字列）
    • singleChoiceResponse: リストから 1 つのオプションのみを選択できる場合。
      • value（文字列）: 選択された回答の選択肢の ID。
    • multipleChoiceResponse: 複数のオプションを選択できる場合。
      • values（文字列の配列）: 選択された回答の選択肢の ID。
    • documentResponse: ドキュメントのアップロードが必要な質問の場合。ドキュメントのアップロードの処理をご覧ください。
    • groupResponse: ネストされた質問の繰り返しセットの場合。
    • keyedGroupResponse: 特定のキーでグループ化されたネストされた質問のセット。

申告のコード スニペットの例については、詳細なガイドをご覧ください。

ドキュメントのアップロードの処理

ポリシーに関する質問によっては、補足ドキュメント（金融取引機能のライセンスなど）の提出が必要になることがあります。ドキュメントを UpdateAppStoreHostedAppRequest に直接埋め込むことはできません。代わりに、次のことを行う必要があります。

  1. ドキュメントをアップロードする: UploadAppStoreAppPolicyDeclarationFile エンドポイントを使用します。これはメディア アップロード リクエストです。fileType は DECLARATION_FILE_TYPE_DOCUMENT に設定する必要があります。

    • エンドポイント: POST /androidpublisher/v3/appstore/{appStorePackageName}/apps/{packageName}/policyDeclarationFiles:upload
    • アップロードが成功すると、fileId がレスポンスに含まれます。

  2. ドキュメント ID を参照する: ドキュメントの質問の PolicyResponse で、documentResponse 型を使用します。アップロードの手順で取得した fileId を documentId フィールドに入力します。

PolicyDocumentResponse オブジェクト:

  • documentId（文字列、必須）: UploadAppStoreAppPolicyDeclarationFile エンドポイントから返された ID。
  • expiryDate（日付、省略可）: ドキュメントの有効期限（該当する場合）。
  • nonExpiring（ブール値、省略可）: ドキュメントの有効期限がない場合は true に設定します。

ドキュメント レスポンスの例:

// Inside a PolicyResponse object
{
  "questionId": "POLICY_QUESTION_ID_FINANCE_CRYPTO_US_FINCEN_LICENSE", // Example ID
  "documentResponse": {
    "documentId": "123456789", // The fileId from upload
    "expiryDate": {
      "year": 2027,
      "month": 6,
      "day": 1
    }
  }
}

4. 利用可否の管理

UpdateAppStoreHostedApp を使用してホスト型アプリの状態をコミットすると、アプリは自動的に処理され、デフォルトでサードパーティのアプリストア向けに Google Play で公開済みとしてマークされます。

アプリのコミット後にアプリの利用可否を制御するには、updateappstorehostedapppublishstatus メソッドを呼び出して状態を更新します。

  • アプリの公開停止: ホスト型アプリを利用不可にするには、publishState フィールドを APP_STORE_APP_PUBLISH_STATE_UNPUBLISHED に設定します。
  • アプリの再公開: 以前に非公開にしたアプリを、掲載情報を変更したりアセットを再アップロードしたりせずに、再び公開するには、publishState フィールドを APP_STORE_APP_PUBLISH_STATE_PUBLISHED に設定します。