国によるアセット ターゲティング

国によるアセット ターゲティングとは

国によるアセット ターゲティングを適用すると、ユーザーの居住国に基づいて、同じアセットの異なるバージョン（解像度が違うなど）をデバイスに配信できます。たとえば、アプリを利用できる国ごとにカスタマイズしたアセットを配信できます。必要なアセットのみをユーザーのデバイスに配信するため、ゲーム全体のサイズが大きくなることはありません。これは、Play Asset Delivery のアセットパックのコンセプトに基づいています。以下で説明するように、最大 20 セットの国ごとにターゲティング条件を定義できます。この条件の基準となるデバイスの「国」は通常、Google Play アカウントに登録されているユーザーの請求先住所によって判断されます。

Play Asset Delivery と同様に、国によるターゲティングは、Android 4.1（API レベル 16）以降をサポートしています。ただし、Android 4.4（API レベル 19）以前を搭載しているデバイスでは、ユーザーの場所にかかわらず、デフォルトの国セットが適用されます。

デベロッパーが実施する手順

国によるターゲティングを既存のゲームに統合する主な手順は次のとおりです。

1. 国によるターゲティング（および Play Asset Delivery）をゲームに統合します。
   • Play Asset Delivery をゲームに統合します（まだ統合していない場合）。
   • アセットをアセットパックに分割します。
   • Play にアップロードする最終的な Android App Bundle アーティファクト用に、コードとアセットをまとめてパッケージ化します。
2. デバイス ターゲティング構成を作成し、ユーザーのデバイスにアセットを配信する方法を Play が認識できるようにします。
   • Google Play Developer API を設定します（まだ完了していない場合）。この API を使用してターゲティング構成を Play に送信します
   • 手順に沿ってターゲティング構成を作成します。
3. AAB を Play にアップロードし、すべてが正しく設定されているかどうかをテストします。

Java およびネイティブ ゲームのビルドシステムには、Gradle を使用することをおすすめします。Gradle を使用してビルドしたゲームの場合は、次の手順に沿って、国によるターゲティングをサポートする AAB をビルドするようにビルドシステムを設定します。

ゲームを Gradle にエクスポートし、Gradle でビルドを完了する場合、以下の手順を行うことをおすすめします（例: Gradle にエクスポートされた Unity ゲーム）

アプリ内で国によるアセット ターゲティングを設定する

Play Asset Delivery をゲームに統合する（まだ完了していない場合）

Play Asset Delivery（PAD）を使用すると、インストール時または実行時にゲームのアセットを動的に配信できます。詳しくは、Play Asset Delivery をご覧ください。国によるターゲティングでは、Play は、ユーザーのさまざまな地域に対して指定された国セットに基づいて、アセットパックのコンテンツを配信します。以下のガイダンスに沿って PAD をゲームに統合し（アセットパックを作成し、ゲームに取得機能を実装する）、プロジェクト コードを変更して国によるターゲティングを有効にすることをおすすめします。

Gradle

Gradle でビルドされたゲームの場合は、次の手順で Gradle を使用してアセットパックをビルドしてから、手順に沿って次のアセットパックの取得をゲームに統合します。

• Java
• ネイティブ
• Gradle にエクスポートされた Unity ゲーム
  • JNI 経由で Java ライブラリ（Unity に組み込まれたライブラリなど）を使用します。

国セットごとのディレクトリを作成する

Gradle を使用する場合

次に、後で定義する国セット（最大 20 セット）にアセットを分割します。前のステップで作成した既存のアセット バンドル ディレクトリを取得し、適切なフォルダ（下記の説明を参照）に #countries_latam、#countries_na などの接尾辞を付けて、ターゲティング ディレクトリを作成します。ゲームでアセットパックを使用する場合、フォルダに接尾辞を付ける必要はありません（接尾辞はビルドプロセス中に自動的に削除されます）。

前のステップを実施すると、次のようになります。

...
.../level1/src/main/assets/character-textures#countries_latam/
.../level1/src/main/assets/character-textures#countries_na/
.../level1/src/main/assets/character-textures/
...

フォルダの下のファイルにアクセスする場合、接尾辞なしで同じパスを使用できます（この例では、接尾辞なしで level1/assets/character-textures/ として参照します）。

Android App Bundle をビルドする

Gradle

プロジェクトの build.gradle ファイルで、次の（またはそれ以上の）バージョンの Android Gradle プラグインと bundletool を持つように依存関係を設定します。

buildscript {
  dependencies {
    classpath 'com.android.tools.build:gradle:8.1.0-alpha01'
    classpath "com.android.tools.build:bundletool:1.14.0"
    ...
  }
  ...
}

また、Gradle のバージョンを 8.0 以上にアップデートする必要もあります。これは、プロジェクト内の gradle/wrapper/gradle-wrapper.properties でアップデートできます。

distributionUrl=https://services.gradle.org/distributions/gradle-8.0-rc-1-all.zip

最後に、Play Asset Delivery Library を使用する必要があります。モノリシックな Play Core Library を使用している場合は、1.8.3 以上にアップデートします。可能であれば、Play Asset Delivery Library に切り替えて、最新バージョンにアップデートすることをおすすめします。

dependencies {
  implementation 'com.google.android.play:asset-delivery:2.0.1'
  ...
}

メインアプリ モジュールの build.gradle ファイルで、国によるターゲティング分割を有効にします。

android {
  bundle {
    countrySet {
      enableSplit true
    }
    ...
  }
  ...
}

最後に、Android App Bundle（AAB）をビルドします。

• Android Studio
• CLI

bundletool

bundletool を使用してバンドルを作成します。また、AAB をカスタマイズするステップで、BundleConfig.pb ファイルに以下を追加します。

{
  ...
  "optimizations": {
    "splitsConfig": {
      "splitDimension": [
      ...
      {
        "value": "COUNTRY_SET",
        "negate": false,
        "suffixStripping": {
          "enabled": true,
        }
      }],
    }
  }
}

ローカルテスト

先に進む前に、App Bundle をローカルでテストして、すべてが正しく設定されているか確認することをおすすめします。bundletool（1.14.0 以降）を使用して、ローカルでアプリのビルドとテストを行い、正しい国を明示的に指定します。最初に build-apks を使用して一連の .apks ファイルを生成してから、install-apks を使用して接続されたデバイスにアプリをデプロイします。country-set フラグを使用して、インストールする国セットを指定することもできます。ローカルテストの方法について詳しくは、こちらをご覧ください（このページは国によるターゲティングについては更新されていないため、country-set フラグに関する情報は記載されていません）。

bundletool build-apks --bundle=/path/to/app.aab --output=/path/to/app.apks --local-testing
bundletool install-apks --apks=/path/to/app.apks --country-set=latam

別の方法: extract-apks を使用して、特定のデバイス用に APK のセットを抽出することもできます。ただし、このデバイスに対して国を指定した状態で get-device-spec を使用した場合、--local-testing フラグとは連携して動作しないため、fast-follow アセットパックや on-demand アセットパックはテストできません。

bundletool get-device-spec --output=/path/to/device-spec.json --country-set=latam
bundletool extract-apks --apks=/path/to/existing_APK_set.apks --output-dir=/path/to/device_specific_APK_set.apks --device-spec=/path/to/device-spec.json

Google Play Developer API でデバイス ターゲティング構成を作成する

Google Play Developer API のスタートガイド（まだ完了していない場合）

国によるターゲティングを構成する（国セットを定義する）には、Android Publisher API を使用して構成を Google Play にアップロードする必要があります。API の詳細については上記のリンクをご覧ください。使用を開始するための手順がいくつか用意されています。

1. 必要に応じて、API プロジェクトを作成して Google Play Console にリンクします。
2. API アクセス クライアントを設定します。

API リファレンスはこちらで確認できます。後で API 経由でビルドをアップロードする場合は、Edits メソッドを使用します。 また、API を使用する前に、こちらのページを確認することをおすすめします。

Device Target Configuration API の使用

デバイス ターゲティング構成を作成するには、次の API 呼び出しを使用します。

デバイス ターゲティング構成の作成

HTTP リクエスト	POST https://androidpublisher.googleapis.com/androidpublisher/v3/applications/{packageName}/deviceTierConfigs
パスパラメータ	なし
リクエストの本文	デバイス ターゲティング構成
レスポンスの本文	デバイス ターゲティング構成

デバイス ターゲティング構成オブジェクト

{
  "user_country_sets": [
    {
      "name": "latam",
      "country_codes": [
        "AR",
        "BR",
        ...
      ]
    },
    {
      "name": "sea",
      "country_codes": [
        "VN",
        "TW",
        ...
      ]
    }
  ]
}

フィールド:

• device_config_id（整数）: このデバイス ターゲティング構成に対応する ID。
• user_country_sets（オブジェクト）: 国セットの定義
  • name（文字列）: 国セットの名前（自分で定義した文字列 ID）。
  • country_codes（文字列）: この国セットに属する国（形式: ISO 3166-1 alpha-2）。

Google Play にアップロードする前に、次の手順に沿ってデバイス ターゲティング構成を検証してください。

デバイス ターゲティング構成を ID で取得する

次の呼び出しを使用して、ID で特定のデバイス ターゲティング構成を取得できます。

HTTP リクエスト	GET https://androidpublisher.googleapis.com/androidpublisher/v3/applications/{packageName}/deviceTierConfigs/{deviceTierConfigId}
パスパラメータ	なし
リクエストの本文	なし
レスポンスの本文	デバイス ターゲティング構成

デバイス ターゲティング構成のリストを取得する

次の呼び出しを行うと、最新のデバイス ターゲティング構成を 10 個取得できます（または、page_token クエリ パラメータを使用して 10 個のセットを適切に指定します）。

HTTP リクエスト	GET https://androidpublisher.googleapis.com/androidpublisher/v3/applications/{packageName}/deviceTierConfigs
パスパラメータ	なし
クエリ パラメータ	page_token（省略可）- 10 個の DTC からなる特定のグループを指定するために使用されます。これは、10 個以上の DTC を作成している場合に、最近作成した 10 個よりも前に作成した DTC を確認したいときに便利です。
リクエストの本文	なし
レスポンスの本文	デバイス ターゲティング構成のリスト page_token

デバイス ターゲティング構成を検証する

bundletool には、Google Play にアップロードする前に、デバイス ターゲティング構成が意図通りに動作することを検証するためのコマンドが 2 つあります。

bundletool print-device-targeting-config を使用すると、JSON ファイルの構文が正しいことを確認できます。

bundletool print-device-targeting-config --config=mydtc.json

bundletool evaluate-device-targeting-config を使用すると、特定のデバイスに一致する国セットを評価できます。ユーザーの国は --country-code フラグを使用して指定できます。

bundletool evaluate-device-targeting-config --config=mydtc.json --connected-device --country-code=AR

Android App Bundle を Google Play にアップロードする

API 経由

Google Play Developer API を使用して、Android App Bundle を Google Play にアップロードしたり、特定のデバイス ターゲティング構成をビルドにリンクしたりすることができます。

Edits メソッドの全般的な概要と、Google Play Console のさまざまなトラックへのリリースに関する詳細な例をご覧ください（最後のリンクでは、ページ内にリストされている APK 対応 API の代わりに、AAB 対応 API を使用する必要があります）。ビルドのデバイス ターゲティング構成を指定するには、edits.bundle.upload メソッドを呼び出す際に、次のように構成 ID を deviceTierConfigId クエリ パラメータに追加します。

https://androidpublisher.googleapis.com/upload/androidpublisher/v3/applications/{packageName}/edits/{editId}/bundles?deviceTierConfigId="{deviceTierConfigId}

Google Play Console 経由

こちらの手順に沿って Android App Bundle をアップロードします。最新の DTC 設定が App Bundle に適用されます。

正しいアセットが配信されていることを確認する

正しいアセットのみがデバイスに配信されるようにするには、次のメソッドを使用します。

adb shell pm path {packageName}

次のような出力が表示されます。

package:{...}/base.apk
package:{...}/split_config.en.apk
package:{...}/split_config.xxhdpi.apk
package:{...}/split_main_asset.apk
package:{...}/split_main_asset.config.countries_latam.apk

補足事項

curl によるクイック スタート

以下に、コマンドライン ツール curl を使用した新しいデバイス ターゲティング構成の作成と、Edits API を使用した新しい編集の作成、新しい AAB のアップロード（特定のデバイス ターゲティング構成への関連付け）、トラックまたはリリース構成の設定、編集のコミット（変更の公開）の例を示します。以下のものの場所を確認してください。

• API クライアントに対応するキー
• アプリのパッケージ名

まず、デバイス ターゲティング構成を作成し、呼び出しが成功したときに受け取る deviceTierConfigId をメモします。

curl -H "$(oauth2l header --json $HOME/{apiKey} androidpublisher)" -XPOST -H "Content-Type: application/json" -d "{ "user_country_sets": [ { "name": "latam", "country_codes": [ "AR", "BR" ] }, { "name": "sea", "country_codes": [ "VN", "TW" ] } ] }" https://androidpublisher.googleapis.com/androidpublisher/v3/applications/{packageName}/deviceTierConfigs

編集を開始すると、編集用の ID と有効期限が表示されます。次の呼び出し用に ID を保存します。

curl -H "$(oauth2l header --json $HOME/{apiKey} androidpublisher)" -XPOST https://androidpublisher.googleapis.com/androidpublisher/v3/applications/{packageName}/edits

AAB をアップロードし、クエリ パラメータとしてデバイス ターゲティング構成を指定します。呼び出しが成功すると、ビルドのバージョン コード、sha1 および sha256 が表示されます。次回の呼び出し用にバージョン コードを保存します。

curl -H "$(oauth2l header --json $HOME/{apiKey} androidpublisher)" --data-binary @$HOME/{aabFile} -H "Content-Type: application/octet-stream" -XPOST https://androidpublisher.googleapis.com/upload/androidpublisher/v3/applications/{packageName}/edits/{editID}/bundles?deviceTierConfigId="{deviceTargetingConfigID}"

AAB を目的のトラックに割り当てます（テストには内部テストトラックを使用することをおすすめします。こちらでさまざまなトラックの詳細をご覧いただけます。ここではリリースノートなしで簡単に公開していますが、未公開のリリースとリリースノートを段階的に公開する方法について詳しくは、こちらのページをご覧ください。Publisher API を初めて使用する場合は、すべてが正しく設定されるように、未公開のリリースとして作成してから、Google Play Console でリリースを完了することをおすすめします。

curl -H "$(oauth2l header --json $HOME/{apiKey} androidpublisher)" -XPUT -H "Content-Type: application/json" -d "{ releases: [{status: '{status}'</code>, <code><strong>versionCodes</strong></code>: <code>['{versionCode}']</code> <code><strong>}]}</strong></code>" <code>https://androidpublisher.googleapis.com/androidpublisher/v3/applications/{packageName}/edits/{editID}/tracks/{track}

変更をコミットします（Play 上の目的のトラックにすべての変更が公開されるため、慎重に行ってください）。

curl -H "$(oauth2l header --json $HOME/{apiKey} androidpublisher)" -XPOST https://androidpublisher.googleapis.com/androidpublisher/v3/applications/{packageName}/edits/{editID}:commit