Таргетинг на уровень устройств

Что такое таргетинг на уровне устройств?

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

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

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

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

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

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

  • Gradle (рекомендуется для игр Java и Native) . Для игр, созданных с использованием Gradle, выполните следующие действия, чтобы настроить систему сборки для создания AAB с поддержкой DTT.
    • Если вы экспортируете игру в Gradle, а затем завершаете сборку там, мы рекомендуем следовать этим инструкциям (например, игры Unity , экспортированные в Gradle) ).
  • Плагин Unity : мы предоставим вам пакеты Unity для импорта в ваш проект Unity, что позволит вам настроить и создать AAB с поддержкой DTT.

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

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

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

Градл

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

Единство

Для игр, созданных на Unity, вы настроите пакеты ресурсов с помощью класса AssetPackConfig , как описано в этих инструкциях .

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

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

Теперь вы разделите свои активы между N уровнями (максимум 5), которые вы определите позже. Создайте каталоги DTT, взяв существующие каталоги пакетов ресурсов, созданные на последнем шаге, и опубликуйте исправление соответствующей папки (как описано ниже) с помощью #tier_0, #tier_1, #tier_2 и т. д. При использовании пакетов ресурсов в вашей игре вы не нужно будет обращаться к папкам по постфиксу (другими словами, постфикс автоматически удаляется в процессе сборки).

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

...
.../level1/src/main/assets/character-textures#tier_2/
.../level1/src/main/assets/character-textures#tier_1/
.../level1/src/main/assets/character-textures#tier_0/
...

Когда вы получаете доступ к файлам в папке, вы можете просто использовать тот же путь без исправления сообщений (в этом примере я бы ссылался на level1/assets/character-textures/ без каких-либо постфиксов).

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

Чтобы добавить пакет ресурсов, использующий DTT, вы можете использовать следующие методы AssetPackConfig :

/// Package the specified raw assets in the specified folders,
/// keyed by DeviceTier, in an AssetPack with the specified delivery mode.
public void AddAssetsFolders(
    string assetPackName,
    IDictionary<DeviceTier, string> deviceTierToAssetPackDirectoryPath,
    AssetPackDeliveryMode deliveryMode)

/// Package the specified AssetBundle files, which vary only by DeviceTier,
/// in an AssetPack with the specified delivery mode.
public void AddAssetBundles(
    IDictionary<DeviceTier, string> deviceTierToAssetBundleFilePath,
    AssetPackDeliveryMode deliveryMode)

Например, предположим, что у вас есть три AssetBundles для вашего персонажа с разным уровнем детализации.

Чтобы сопоставить эти AssetBundles с соответствующим уровнем устройства, используйте следующий фрагмент. 

var assetPackConfig = new AssetPackConfig();
var tiers = new Dictionary<DeviceTier, string>
{
    {0, "Assets/LowPoly/Character"},
    {1, "Assets/Mid/Character"},
    {2, "Assets/Detailed/Character"}
};
assetPackConfig.AddAssetBundles(tiers, AssetPackDeliveryMode.OnDemand);

Создание пакета приложений для Android

Градл

В файле build.gradle вашего проекта настройте зависимости так, чтобы они имели версии ниже (или выше) для плагина Android Gradle и Bundletool :

buildscript {
  dependencies {
    classpath 'com.android.tools.build:gradle:4.2.0'
    classpath "com.android.tools.build:bundletool:1.7.1"
    ...
  }
  ...
}

Вам также потребуется обновить версию Gradle до 6.7.1 или выше. Вы можете обновить это в gradle/wrapper/gradle-wrapper.properties внутри вашего проекта.

distributionUrl=https://services.gradle.org/distributions/gradle-6.7.1-all.zip

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

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

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

android {
  bundle {
    deviceTier {
      enableSplit true
    }
    ...
  }
  ...
}

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

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

Создайте свой пакет с помощью Bundletool и на этапе настройки AAB добавьте следующее в свой файл BundleConfig.pb . 

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

Единство

После того как вы настроили AssetPackConfig для включения пакетов DTT, вы можете передать эту конфигурацию в один из следующих методов для создания AAB: 

// Configures the build system to use the newly created assetPackConfig when
// calling Google > Build and Run or Google > Build Android App
Bundle.AssetPackConfigSerializer.SaveConfig(assetPackConfig);
// Alternatively, use BundleTool.BuildBundle to build an App Bundle from script
BuildBundle(new buildPlayerOptions(), assetPackConfig)

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

Прежде чем двигаться дальше, рекомендуется локально протестировать пакет приложений, чтобы убедиться, что все настроено правильно. Используя bundletool (1.8.0 или более позднюю версию), вы локально создаете и тестируете свое приложение, явно указывая правильный уровень устройства. Сначала вы будете использовать build-apks для создания набора файлов .apks , а затем развернете свое приложение на подключенном устройстве с помощью install-apks . Вы также можете указать, какой уровень вы хотите установить, с помощью флага уровня устройства. Дополнительную информацию об этом методе локального тестирования можно найти здесь (обратите внимание, что эта страница еще не обновлена ​​для DTT и поэтому на ней отсутствует флаг device-tier ).

bundletool build-apks --bundle=/path/to/app.aab --output=/path/to/app.apks --local-testing
bundletool install-apks --apks=/path/to/app.apks --device-tier=1

Альтернативно : вы также можете использовать extract-apks для извлечения набора APK для определенного устройства. Однако использование get-device-spec вместе с указанием уровня устройства для этого устройства не будет работать в сочетании с флагом --local-testing , что означает, что вы не сможете тестировать пакеты ресурсов быстрого отслеживания или по требованию. . 

bundletool get-device-spec --output=/path/to/device-spec.json --device-tier=1
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 -> Build and Run позволит собрать и запустить вашу игру с включенным флагом --local-testing . Однако он не позволяет указать уровень устройства, передаваемый в команду install-apks .

Если вы хотите указать уровень устройства, отличный от 0, вам следует:

  1. Создайте AAB, используя пункт меню Google -> Build Android App Bundle .
  2. Следуйте инструкциям из предыдущего раздела, чтобы запустить bundletool , build-apks и install-apks на построенном AAB.

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

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

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

  1. Создайте (при необходимости) и свяжите свой проект API с консолью Google Play .
  2. Настройте клиент доступа к API .

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

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

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

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

HTTP-запрос POST https://androidpublisher.googleapis.com/androidpublisher/v3/applications/{packageName}/deviceTierConfigs
Параметры пути Н/Д
Тело запроса Конфигурация уровня устройства
Тело ответа Конфигурация уровня устройства
Объект конфигурации уровня устройства

Определение уровней устройств состоит из двух этапов:

  1. Определите набор групп устройств .
  2. Определите набор уровней устройств , назначив уровень группам устройств.

Группа устройств — это набор устройств, соответствующих селекторам, которые вы определяете в конфигурации.

Селекторы могут определить требования к оперативной памяти устройства и модели устройства.

Группы идентифицируются по выбранному вами имени; группы могут пересекаться.

Далее вы можете определить набор уровней устройств, ранжируя группы: каждый уровень устройств определяется своим уровнем и группой устройств.

Если устройство соответствует нескольким уровням, ему будет предоставлен контент для самого высокого уровня соответствия.

  {
    device_groups: [
      {
        name: string,
        device_selectors: [
          {
            device_ram: {
              min_bytes: integer
              max_bytes: integer
            },
            included_device_ids: [
              {
                build_brand: string,
                build_device: string
              }
            ],
            excluded_device_ids: [
              {
                build_brand: string,
                build_device: string
              }
            ],
            required_system_features: [
              {
                name: string
              }
            ],
            forbidden_system_features: [
              {
                name: string
              }
            ]
          }
        ]
      }
    ],
    device_tier_set: {
      device_tiers: [
        {
          level: int,
          device_group_names: [string]
        }
      ]
    }
  }

Поля:

  • device_confid_id (целое число): идентификатор, соответствующий конфигурации этого уровня устройства.

  • device_groups (объект): определения групп.

    • имя (строка): имя группы устройств (определенный вами строковый идентификатор).
    • device_selectors (объект): требования к устройству, чтобы устройство принадлежало этой группе.
    • device_ram (объект): требования к оперативной памяти устройства.
      • min_bytes (целое число включительно) : Минимально необходимая ОЗУ (в байтах).
      • max_bytes (целое, исключающее) : Максимально необходимое ОЗУ (в байтах).
    • include_device_ids (объект): модели устройств, которые будут включены в этот селектор (максимум 10 000 device_ids на группу). Устройство должно находиться в этом списке, чтобы соответствовать селектору. Это необходимое, но недостаточное условие для соответствия полному селектору (см. примечание выше об объединении требований в селекторе).
      • build_brand (строка): Производитель устройства.
      • build_device (строка): код модели устройства.
    • Excluded_device_ids (объект): модели устройств, которые будут исключены из этого селектора (максимум 10 000 идентификаторов устройств на группу). Устройство из этого списка не будет соответствовать селектору, даже если оно соответствует всем остальным требованиям в селекторе.
      • build_brand (строка): Производитель устройства.
      • build_device (строка): код модели устройства.

    • require_system_features (объект): функции, которые устройство должно включить в этот селектор (максимум 100 функций в группе) . Чтобы устройство соответствовало селектору, оно должно иметь все системные функции из этого списка. Это необходимое, но недостаточное условие для соответствия полному селектору (см. примечание выше об объединении требований в селекторе).

      Справочник функций системы

      • имя (строка): системная функция.

    • запрещенные_системные_функции (объект): функции, которые устройство не должно включать в этот селектор (максимум 100 функций в группе) . Если устройство имеет какие-либо системные функции из этого списка, оно не соответствует селектору, даже если оно соответствует всем остальным требованиям в селекторе.

      Справочник по функциям системы

      • имя (строка): системная функция.

  • device_tiers (объект): определения уровней.

    • level (int): Уровень уровня.
    • group_name (массив строк): имя группы устройств, принадлежащих этому уровню.

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

  • Проверка отдельных устройств с помощью каталога устройств и поиск производителя и кода модели в местах, как показано в примере ниже (для Google Pixel 4a производителем является «Google», а код модели — «sunfish»)»

    Страница пикселя 4а в каталоге устройств

    Страница пикселя 4а в каталоге устройств

  • Загрузка CSV-файла с поддерживаемыми устройствами и использование кода производителя и модели для полей build_brand и build_device соответственно.

Вот пример конфигурации с тремя уровнями: уровень 2 использует группу устройств High (в которую входят все устройства более 7 ГБ и Pixel 4), уровень 1 использует среднюю группу устройств (которая включает все устройства от 4 до 7 ГБ) и уровень 0. , которая неявно определяется как всеобъемлющая группа.

{
  device_groups: [
    {
      name: 'high',
      device_selectors: [
        {
          device_ram: {
            min_bytes: 7516192768
          },
        },
        {
          included_device_ids: [
            {
              build_brand: 'google',
              build_device: 'flame'
            }
          ],
        }
      ]
    },
    {
      name: 'medium',
      device_selectors: [
        {
          device_ram: {
            min_bytes: 4294967296,
            max_bytes: 7516192768
          },
        }
      ]
    }
  ],
  device_tier_set: {
    device_tiers: [
      {
        level: 1,
        device_group_names: [
          'medium'
        ]
      },
      {
        level: 2,
        device_group_names: [
          'high'
        ]
      }
    ]
  }
}

Вы можете следовать инструкциям ниже, чтобы проверить конфигурацию таргетинга на устройства перед ее загрузкой в ​​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 вы можете оценить, какие группы и уровень будут соответствовать конкретному устройству. Либо вы подключаете целевое устройство к рабочей станции и используете флаг --connected-device ; или вы вручную компилируете файл JSON со свойствами устройства и предоставляете его с помощью флага --device-properties .

bundletool evaluate-device-targeting-config --config=mydtc.json --connected-device
bundletool evaluate-device-targeting-config --config=mydtc.json --device-properties=deviceproperties.json

Файл свойств устройства должен представлять собой файл JSON, соответствующий структуре protobuf DeviceProperties . Например: 

{
  "ram": 2057072640,
  "device_id": {
    "build_brand":"google",
    "build_device":"redfin"
  },
  "system_features": [
    {
      "name":"android.hardware.bluetooth"
    },
    {
      "name":"android.hardware.camera"
    }
  ]
}

Загрузка пакета приложений 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 будет применена к вашему пакету приложений.

Вы можете убедиться, что ваш пакет собран правильно, перейдя в App Bundle Explorer (с выбранной правильной сборкой) > Доставка и щелкнув каждый пакет ресурсов. Должно быть показано, что у вас есть созданные вами N уровней. В этом примере показано, что у меня есть 3 уровня — 0, 1 и 2 для моего пакета активов main_asset .

пакет активов с тремя уровнями

Проверка доставки правильного уровня

Используйте следующий метод, чтобы убедиться, что на устройство доставляется только правильный уровень.

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.tier_2.apk

Вспомогательный

Быстрый старт с использованием Curl

Ниже приведен пример (с использованием инструмента командной строки Curl) создания новой конфигурации уровня устройства и использования Edits API для создания нового редактирования, загрузки нового AAB (связывая его с определенной конфигурацией уровня устройства), установки track/ выпустите конфигурацию и зафиксируйте изменения. (таким образом обнародовав изменение) . Обязательно укажите местоположение:

  • Ключ, соответствующий вашему API-клиенту.
  • Имя пакета вашего приложения

Сначала создайте конфигурацию уровня устройства и запишите идентификатор deviceTierConfigId , который вы получите при успешном вызове.

curl -H "$(oauth2l header --json $HOME/{apiKey} androidpublisher)" -XPOST -H "Content-Type: application/json" -d "{ device_groups: [ { name: 'high', device_selectors: [ { device_ram: { min_bytes: 7516192768 }, }, { included_device_ids: [ { build_brand: 'google', build_device: 'flame' } ], } ] }, { name: 'medium', device_selectors: [ { device_ram: { min_bytes: 4294967296, max_bytes: 7516192768 }, } ] } ], device_tier_set: { device_tiers: [ { level: 1, device_group_names: [ 'medium' ] }, { level: 2, device_group_names: [ 'high' ] } ] } }" 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="{dttConfigID}"

Назначьте 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