本頁面由 Cloud Translation API 翻譯而成。

依國家/地區指定資產

什麼是依國家/地區指定資產？

透過依國家/地區指定資產功能，您可以根據使用者所在的國家/地區，為裝置提供同一資產的不同版本 (如解析度)。舉例來說，您可以選擇向應用程式發行的不同國家/地區提供自訂資產。這樣一來，由於只向使用者的裝置提供必要資產，所以完全不會增加整體遊戲大小。這項功能是以 Play Asset Delivery 中的資產包概念為基礎。如下所示，您可以定義最多 20 個國家/地區組合的指定條件。在這種情況下，裝置所在的國家/地區通常取決於使用者在 Google Play 帳戶中註冊的帳單地址。

與 Play Asset Delivery 一樣，依國家/地區指定功能適用於 Android 4.1 (API 級別 16) 以上版本。但請注意，在搭載 Android 4.4 (API 級別 19) 以下版本的裝置上，不論使用者身處何地，系統都會提供預設的國家/地區組合。

開發人員旅程

大致來說，如要在現有遊戲中整合依國家/地區指定功能，請按照下列步驟操作：

在遊戲中整合依國家/地區指定功能以及 Play Asset Delivery。
- 在遊戲中整合 Play Asset Delivery (如果尚未整合的話)。
- 將資產分為多個「資產包」。
- 將程式碼和資產打包在一起，做為要上傳至 Play 的最終 Android App Bundle 構件。
建立裝置指定設定，讓 Play 瞭解如何為使用者裝置提供資產。
- 設定 Google Play Developer API (如果尚未完成設定的話)。您會使用這個 API 將指定目標設定傳送至 Play。
- 按照步驟建立指定目標設定。
將 AAB 上傳至 Play 並進行測試，確認所有設定皆正確無誤。

Gradle 是 Java 和原生遊戲建議使用的建構系統。如果是使用 Gradle 建構的遊戲，請按照下列步驟設定建構系統，透過國家/地區指定目標支援建立 AAB。

如果您將遊戲匯出到 Gradle 並在此完成建構，建議您按照下列指示操作 (例如匯出至 Gradle 的 Unity 遊戲)。

設定應用程式內的依國家/地區指定資產功能

在遊戲中整合 Play Asset Delivery (如果尚未整合完成)

Play Asset Delivery (PAD) 可讓您在安裝期間或執行階段動態供應遊戲資產，詳情請參閱這篇簡介文章。依國家/地區指定目標後，Play 將根據您為不同使用者位置指定的國家/地區組合設定，提供資產包的內容。建議您按照下列指南在遊戲中整合 PAD (也就是建立資產包及在遊戲中導入擷取功能)，然後修改專案程式碼，啟用依國家/地區指定功能。

Gradle

如果是使用 Gradle 建構的遊戲，請按照這篇文章的操作說明使用 Gradle 建構資產包，然後按照下列操作說明在遊戲中整合資產包擷取功能：

Java
原生
匯出至 Gradle 的 Unity 遊戲
- 透過 JNI 使用 Java 程式庫 (例如 Unity 內建的 JNI)。

建立國家/地區組合專屬目錄

使用 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 程式庫；如果您仍使用單體 Play Core 程式庫，請將其更新至 1.8.3 以上版本。建議您改用 Play Asset Delivery 程式庫，並盡可能更新至最新版本。

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

在主要應用程式模組的 build.gradle 檔案中啟用國家/地區指定分割功能：

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

完成上述步驟後，您就可以建立 Android App Bundle (AAB)。

Bundletool

使用 bundletool 建構套件，並在自訂 AAB 的步驟中將以下程式碼加入 BundleConfig.pb 檔案。

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

本機測試

建議您先在本機測試應用程式套件，確認所有設定皆正確無誤後，再繼續進行後續步驟。您可以使用 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 標記。也就是說，您將無法測試快速追蹤或隨選資產包。

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，請點選上述連結。另外，請按照這篇文章的幾個步驟展開操作，包括：

您可以按這裡查看 API 參考資料。如果您之後選擇透過 API 上傳您建構的 AAB，就會使用 Edits 方法。此外，建議您在使用 API 之前，先詳閱這個網頁。

使用 Device Targeting 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_confid_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」查詢參數，以最適當的方式指定 (一組十個)：

HTTP 要求	`GET https://androidpublisher.googleapis.com/androidpublisher/v3/applications/{packageName}/deviceTierConfigs`
路徑參數	無
查詢參數	page_token (選用)：指定 10 個 DTC 的特定群組。如果您建立的 DTC 超過 10 個，而且想查看的 DTC 並不是最近建立的 10 個 DTC，這個參數就非常實用。
要求主體	無
回應主體	裝置指定設定清單 page_token

驗證裝置指定設定

bundletool 包含兩個指令，可在上傳到 Play 之前確認裝置指定設定是否正常運作。

使用 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，然後將特定的裝置指定設定連結至您建構的 AAB。

您可以參閱 Edits 方法的概要總覽，也可以參閱這篇文章，透過更深入的範例瞭解如何在 Google Play 管理中心的不同測試群組中發布內容 (建議您在參閱第二篇文章時，使用適用 AAB 的 API，不要使用文中所列的適用 APK 的 API)。如要針對您的版本指明裝置指定設定，請在呼叫 edits.bundle.upload 方法時，將設定 ID 新增至 deviceTierConfigId 查詢參數，就像這樣：

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

透過 Google Play 管理中心

請按照這篇文章的操作說明上傳 Android App Bundle。您的 App Bundle 會套用最新的 DTC 設定。

驗證是否提供正確資產

請利用以下方法，確保只將正確資產提供給裝置

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，建議您以草稿版本的形式建立 AAB，然後在 Google Play 管理中心完成版本設定，確保所有設定正確無誤。

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