此页面由 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 中内置的库）

创建国家/地区组合专用目录

如果使用 Gradle

现在，您需要在稍后要定义的国家/地区组合（最多 20 个）之间拆分资源。取上一步中创建的现有资源 bundle 目录，并在相应文件夹后添加 #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,
        }
      }],
    }
  }
}

本地测试

在继续下一步之前，建议您在本地测试 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。不过，如果同时使用了 --local-testing 标志，则运用 get-device-spec 并指定该设备的国家/地区这种做法会不起作用，这意味着您无法测试快速跟进式分发资源包或按需分发资源包。

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 参考文档。稍后，如果您选择通过该 API 上传 build，需要使用 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 查询参数指定一组 10 个设备定位配置）：

HTTP 请求	`GET https://androidpublisher.googleapis.com/androidpublisher/v3/applications/{packageName}/deviceTierConfigs`
路径参数	不适用
查询参数	page_token（可选）- 用于指定具体的一组 10 个 DTC。如果您创建的 DTC 超过 10 个，而您希望查看在最近 10 个 DTC 之前创建的 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，并将特定的设备定位配置关联到您的 build。

此处简要介绍了 Edits 方法，还有关于如何发布到 Google Play 管理中心内不同轨道的深入示例（对于后一个链接，您需要使用适合 AAB 文件的 API，而非该页面中列出的适合 APK 的 API）。如需为 build 指定设备定位配置，需要在调用 edits.bundle.upload 方法时将配置 ID 添加到 deviceTierConfigId 查询参数中，如下所示：

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

通过 Google Play 管理中心

您可以按照此处的说明上传 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 文件，将设备定位配置指定为查询参数 - 如果调用成功，您将看到 build 的版本号、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 管理中心完成发布，以确保各项配置正确无误。

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