按国家/地区定位资源

什么是按国家/地区定位资源？

通过按国家/地区定位资源，您可以根据用户所在的国家/地区向设备分发同一资源的不同版本，例如不同分辨率的版本。例如，您可以选择向应用的发布国家/地区分发自定义资源。因为系统只会向用户设备分发必要的资源，所以完全不会增加整体游戏大小。这种做法采用了 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，并进行测试以确保各项配置正确无误。

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) 文件了。

• 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。不过，如果同时使用了 --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，您需要按照以下几个步骤操作：

1. 创建（如果需要）API 项目并将其关联到 Google Play 管理中心。
2. 设置 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