Таргетинг активов по странам

Что такое таргетинг активов по странам?

Таргетинг ресурсов по стране позволяет доставлять разные версии (например, разрешения) одного и того же объекта на устройства в зависимости от страны, в которой находится пользователь. Например, вы можете доставить настроенные ресурсы в разные страны, где доступно ваше приложение, — и все это без какого-либо увеличения общего размера игры, поскольку на устройства пользователей доставляются только необходимые ресурсы. Это основано на концепции пакетов ресурсов в Play Asset Delivery . Как вы увидите ниже, вы можете определить критерии таргетирования с до 20 наборов страны. В этом контексте страна устройства обычно определяется платежным адресом пользователя, зарегистрированным в его учетной записи Google Play.

Как и для доставки игровых активов, нацеливание на страну поддерживает Android 4.1 (API -уровень 16) и выше. Однако на устройствах под управлением Android 4.4 (API -уровень 19) или ниже, набор страны по умолчанию доставляется независимо от местоположения пользователя.

Путешествие разработчика

На высоком уровне, чтобы интегрировать таргетинг по странам в вашу существующую игру, выполните следующие действия:

1. Интегрировать таргетинг по стране (и, соответственно, играет на активе) в вашу игру
   • Интегрируйте доставку игровых ресурсов в свою игру (если вы еще этого не сделали).
   • Разделите свои активы на пакеты активов
   • Соберите вместе свой код и ресурсы, чтобы получить окончательный артефакт Android App Bundle, который вы загрузите в Play.
2. Создайте конфигурацию вашего устройства, чтобы Play знала, как доставить ваши активы пользовательским устройствам.
   • Установите API разработчика Google Play Developer (если еще не завершен), что вы используете для отправки конфигураций Targeting для игры.
   • Выполните шаги по созданию конфигурации таргетинга.
3. Загрузите свой AAB в Play и проверьте, все ли настроено правильно.

Gradle is the recommended build system for Java and native games. For games built using Gradle, follow these steps to configure the build system to build out your AAB with country targeting support.

Если вы экспортируете игру в Gradle и завершаете сборку там, мы рекомендуем следовать этим инструкциям (например, игры Unity , экспортированные в Gradle) ).

Настройка активов на страну в вашем приложении

Интеграция доставки игровых ресурсов в вашу игру (если это еще не завершено)

Play Asset Delivery (PAD) позволяет динамически доставлять ресурсы вашей игры во время установки или во время выполнения. Обзор этой функции можно прочитать здесь . Благодаря таргетингу по стране Play будет предоставлять содержимое ваших пакетов ресурсов на основе конфигураций набора стран, которые вы предписываете для разных местоположений пользователей. Рекомендуется следовать приведенным ниже инструкциям и интегрировать PAD в вашу игру (т. е. создать пакеты ресурсов, реализовать извлечение в вашей игре), а затем изменить код проекта, чтобы включить таргетинг по стране.

Градл

Для игр, созданных с помощью Gradle, используйте эти инструкции по созданию пакетов ресурсов с помощью Gradle , а затем следуйте инструкциям по интеграции извлечения пакетов ресурсов в вашу игру:

• Ява
• Родной
• Игры Unity , экспортированные в Gradle
  • Use the Java libraries via the JNI (such as the one built into Unity ).

Создание каталогов для конкретной страны

Если вы используете Gradle

You will now split up your assets between the country sets (max 20) you will define later on. Создайте целевые каталоги, взяв существующие каталоги пакетов активов, созданные на последнем шаге, и опубликуйте исправление соответствующей папки (как описано ниже) с помощью #countries_latam, #countries_na и т. д. При использовании пакетов ресурсов в вашей игре вам не потребуется to address folders by postfix (in other words, the postfix is automatically stripped during the build process).

После предыдущего шага это может выглядеть так:

...
.../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

Градл

В файле 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"
    ...
  }
  ...
}

You will also need to update your gradle version to 8.0 or above. Вы можете обновить это в gradle/wrapper/gradle-wrapper.properties внутри вашего проекта.

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

Наконец, вам нужно будет использовать библиотеку доставки игровых активов; если вы все еще используете монолитную библиотеку Play Core, обновите ее до версии 1.8.3 или выше. Мы рекомендуем переключиться на библиотеку доставки ресурсов Play и, если возможно, обновить ее до последней версии.

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

In the main app module's build.gradle file, enable the country targeting split:

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

Наконец, вы можете создать свой пакет приложений для Android (AAB).

• Android-студия
• интерфейс командной строки

Пакетный инструмент

Создайте свой пакет Bundletool , и , находясь на шаге для настройки вашего AAB , добавьте следующее в свой файл BundleConfig.pb .

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

Локальное тестирование

Before moving on, it is recommended to locally test your app bundle to make sure everything is set up correctly. Using bundletool (1.14.0 or above), you locally build and test your app, explicitly specifying the correct country. Сначала вы будете использовать build-apks для создания набора файлов .apks , а затем развернете свое приложение на подключенном устройстве с помощью install-apks . You can also specify which country set you'd like to be installed via the country-set flag. Дополнительную информацию об этом методе локального тестирования можно найти здесь (обратите внимание, что эта страница еще не обновлена ​​для таргетинга по стране и поэтому на ней отсутствует флаг 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

Creating a Device Targeting Configuration via Google Play Developer API

Начало работы с API разработчика Google Play (если еще не завершено)

Чтобы настроить таргетинг по стране (т. е. определить наборы стран), вам потребуется использовать API Android Publisher для загрузки вашей конфигурации в Google Play. Вы можете прочитать больше об API по ссылке выше. Чтобы начать работу, вам необходимо выполнить несколько шагов :

1. Create (if needed) and link your API project to your Google Play Console .
2. Настройте клиент доступа к API .

You can find the API reference here - later on, if you choose to upload your build via the API, you will be using the Edits methods . Кроме того, рекомендуется просмотреть эту страницу перед использованием API.

Использование API настройки таргетинга на устройства

You can use the following API call to create your device targeting configuration:

Создать конфигурацию таргетинга устройств

Объект конфигурации нацеливания на устройства

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

Поля:

• device_confid_id (integer): ID corresponding to this device targeting configuration.
• user_country_sets (object): Country set definitions
  • name (string): Name of the country set (a string ID you define).
  • country_codes (string): Countries that belong to this country set (format: ISO 3166-1 alpha-2 ).

You can follow the instructions below for validating your Device Targeting Configuration before uploading it to Google Play.

Получить конфигурацию таргетинга устройств по идентификатору

You can retrieve a specific device targeting configuration by ID using the following call:

Получить список конфигураций таргетинга устройств

Вы можете получить последние 10 конфигураций на таргетинге устройства с учетом следующего вызова (или оптимально указать набор из десяти, используя параметр запроса page_token ):

Проверка конфигурации таргетинга на устройства

bundletool includes two commands that help you validate that your Device Targeting Configuration works as intended before uploading it to Play.

With bundletool print-device-targeting-config , you can validate that your JSON file is syntactically correct.

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

With bundletool evaluate-device-targeting-config , you can evaluate what country set would match a specific device. You can provide the user country through the --country-code flag.

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

Загрузка пакета приложений Android в Google Play

Через API

Вы можете использовать API Developer Google Play для загрузки вашего пакета приложений Android в Google Play, а также связать конкретную конфигурацию для устройства с вашей сборкой.

Здесь представлен общий обзор методов редактирования , а также более подробные примеры выпуска на различные треки в консоли Google Play (для последней ссылки вы захотите использовать API-интерфейсы, совместимые с AAB, вместо API-интерфейса, дружественного к APK , которые указаны на странице). Чтобы указать конфигурацию таргетирования устройства для вашей сборки, вы добавите идентификатор конфигурации в параметр запроса deviceTierConfigId , вызывая метод edits.bundle.upload , например:

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

Через консоль Google Play

You can follow the instructions here to upload your Android App Bundle. The latest DTC config will be applied to your App Bundle.

Verifying the correct assets are being delivered

Use the following method to ensure only the correct assets are being delivered to the device

You should see something like:

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 инструмента командной строки) создания новой конфигурации для таргетинга устройства , а также использования API EDITS для создания нового редактирования, загрузите новый AAB (связывая его с определенным конфигурацией на таргетинге устройства), установите трек/ release config, and commit the edit. (thus making the change public) . Make sure to have the location of:

• The key corresponding to your API client
• The package name of your app

First, create a device targeting config, and take note of the deviceTierConfigId you'll receive upon a successful call.

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

Start an edit - you will get an id and expiry time for the edit. Save the id for the following calls.

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

Загрузите AAB , указав конфигурацию таргетинга устройства в качестве параметра запроса - если вызов успешен, вы увидите код версии, SHA1 и SHA256 сборки. Save the version code for the next call.

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 на желаемую дорожку (для тестирования рекомендуется использовать внутреннюю тестовую дорожку, но вы можете прочитать больше о различных треках здесь) , здесь мы делаем простое развертывание без заметок о выпуске, но вы можете прочитать эту страницу на странице learn more about how to staged rollouts, draft releases, and release notes. Если это ваш первый раз, когда вы используете 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}

Commit changes (proceed with caution, as this will make all changes go live on Play to the desired track)

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