Эта страница переведена с помощью Cloud Translation API.

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

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

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

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

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

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

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

Gradle — рекомендуемая система сборки для Java и собственных игр. Для игр, созданных с использованием Gradle, выполните следующие действия, чтобы настроить систему сборки для создания AAB с поддержкой таргетинга на страну.

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

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

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

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

Градл

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

Ява
Родной
Игры Unity , экспортированные в Gradle
- Используйте библиотеки Java через JNI (например , встроенную в 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

Градл

В файле 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; если вы все еще используете монолитную библиотеку Play Core, обновите ее до версии 1.8.3 или выше. Мы рекомендуем переключиться на библиотеку доставки ресурсов Play и, если возможно, обновить ее до последней версии.

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

В файле build.gradle основного модуля приложения включите разделение таргетинга по стране:

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

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

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

Создайте свой пакет с помощью 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

Создание конфигурации таргетинга на устройства с помощью API разработчика Google Play

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

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

Вы можете найти ссылку на API здесь — позже, если вы решите загрузить свою сборку через API, вы будете использовать методы Edits . Кроме того, рекомендуется просмотреть эту страницу перед использованием API.

Использование 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 (целое число): идентификатор, соответствующий этой конфигурации таргетинга устройств.
user_country_sets (объект): определения набора стран.
- name (строка): название набора стран (определяемый вами строковый идентификатор).
- Country_codes (строка): страны, входящие в этот набор стран (формат: ISO 3166-1 альфа-2 ).

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

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

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

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. Это полезно, если вы создали более 10 кодов неисправности и хотите просмотреть коды неисправности, созданные до последних 10.
Тело запроса	Н/Д
Тело ответа	Список конфигураций таргетинга устройств 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 в Google Play

Через API

Вы можете использовать API разработчика Google Play, чтобы загрузить пакет Android App Bundle в 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

Вы можете следовать инструкциям здесь , чтобы загрузить пакет приложений для Android. Последняя конфигурация 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 (связывая его с конкретной конфигурацией таргетинга на устройство), установки track/ выпустите конфигурацию и зафиксируйте изменения. (таким образом обнародовав изменение) . Обязательно укажите местоположение:

Ключ, соответствующий вашему 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

Начните редактирование — вы получите идентификатор и срок действия редактирования. Сохраните идентификатор для следующих вызовов.

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 нужному треку (для тестирования рекомендуется использовать внутренний тестовый трек, но подробнее о различных треках можно прочитать здесь) , здесь мы делаем простое развертывание без примечаний к выпуску, но вы можете прочитать эту страницу , чтобы Узнайте больше о поэтапном внедрении, черновых выпусках и примечаниях к выпуску. Если вы впервые используете 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