Таргетинг на устройства для условных модулей

Что такое таргетинг на устройства для условных модулей?

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

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

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

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

В этом документе описывается, как добавить таргетинг на устройства для условной доставки с помощью подключаемого модуля Android Gradle.

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

Добавление функционального модуля в приложение

Play Feature Delivery позволяет предоставлять определенные функции вашего приложения на определенных условиях или загружать их по требованию. Обзор этой функции можно прочитать здесь . С помощью таргетинга на устройства вы можете условно предоставить функцию устройствам, включенным в предоставленные группы.

Чтобы использовать DT для условной доставки, вам необходимо использовать bundletool версии 1.7.0 и выше. Для этого вам необходимо явно указать версию Bundletool для плагина Android Gradle. Этого можно добиться в корневом разделе buildscript файла build.gradle :

buildscript {
  dependencies {
    classpath "com.android.tools.build:bundletool:1.7.0"
    ...
  }
  ...
}

Чтобы создать функциональный модуль, используйте эти инструкции по модульной разработке приложения Android .

После завершения разработки функции вы можете указать условия доставки на основе таргетинга на устройства в AndroidManifest.xml вашей функции. Вам необходимо указать условие группы устройств внутри dist:conditions элемента dist:module . Общая информация об условиях доступна здесь . Для групп устройств доступны новые условия, в которых вы можете указать все группы, которым должна быть предоставлена ​​эта функция:

<dist:device-groups>
  <dist:device-group dist:name="..." />
  <dist:device-group dist:name="..." />
  ...
</dist:device-groups>

Например, предположим, что вы определили группу устройств под названием _my_group 1 (вы узнаете, как ее определить, в разделе «Создание конфигурации таргетинга устройств» ниже). Если функциональный модуль должен быть доставлен только на устройства, принадлежащие устройствам _my_group 1 , его AndroidManifest.xml должен выглядеть следующим образом:

<manifest ...>
  ...
  <dist:module dist:title="...">
    <dist:delivery>
      <dist:install-time>
        <dist:conditions>
          <dist:device-groups>
            <dist:device-group dist:name="my_group_1"/>
          </dist:device-groups>
          ...
        </dist:conditions>
      </dist:install-time>
    </dist:delivery>
  </dist:module>
  ...
</manifest>

Для функции, предназначенной как для _my_group 1 , так и для _my_group 2 , ее AndroidManifest.xml выглядит следующим образом:

<manifest ...>
  ...
  <dist:module dist:title="...">
    <dist:delivery>
      <dist:install-time>
        <dist:conditions>
          <dist:device-groups>
            <dist:device-group dist:name="my_group_1"/>
            <dist:device-group dist:name="my_group_2"/>
          </dist:device-groups>
          ...
        </dist:conditions>
      </dist:install-time>
    </dist:delivery>
  </dist:module>
  ...
</manifest>

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

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

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

bundletool build-apks --bundle=/path/to/app.aab --output=/path/to/app.apks --local-testingbundletool install-apks --apks=/path/to/app.apks --device-groups=my_group_1,my_group_2

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

bundletool get-device-spec --output=/path/to/device-spec.json --device-groups=my_group_1,my_group_2bundletool 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 по ссылке выше. Чтобы начать работу, вам необходимо выполнить несколько шагов :

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

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

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

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

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

HTTP-запрос POST https://androidpublisher.googleapis.com/androidpublisher/v3/applications/{packageName}/deviceTierConfigs
Параметры пути Н/Д
Тело запроса Конфигурация таргетинга устройств
Тело ответа Конфигурация таргетинга устройств
Объект конфигурации нацеливания на устройства
{
  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_config_id (целое число): идентификатор, соответствующий этой конфигурации таргетинга устройств.

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

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

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

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

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

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

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

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

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

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

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

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

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

Например, следующая группа соответствует всем устройствам с объемом оперативной памяти более 4 ГБ, за исключением Pixel 5 (google redfin) и включая Pixel 3 (Google Blueline с объемом оперативной памяти менее 4 ГБ).

device_groups: [
  {
    name: "my_group_1",
    device_selectors: [
      {
        device_ram: {
          min_bytes: 4294967296
        },
        excluded_device_ids: [
          {
            build_brand: "google",
            build_device: "redfin"
          }
        ]
      },
      {
        included_device_ids: [
          {
            build_brand: "google",
            build_device: "blueline"
          }
        ]
      }
    ]
  }
]

Вы можете прочитать это как:

[ (RAM > 4GB) AND NOT (google redfin) ] OR [ (google blueline) ]

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

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

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

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

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

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

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

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

Быстрый старт с использованием 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: "my_group_1", device_selectors: [ { device_ram: { min_bytes: 4294967296 }, excluded_device_ids: [ { build_brand: "google", build_device: "redfin" } ] }, { included_device_ids: [ { build_brand: "google", build_device: "blueline" } ] } ] } ] }" 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 , указав конфигурацию таргетинга на устройство (deviceTierConfigId) в качестве параметра запроса. Если вызов успешен, вы увидите код версии 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="{deviceTierConfigId}

Назначьте AAB нужному треку (для тестирования рекомендуется использовать внутренний тестовый трек, но подробнее о различных треках можно прочитать здесь) , здесь мы делаем простое развертывание без примечаний к выпуску, но вы можете прочитать эту страницу , чтобы Узнайте больше о поэтапном внедрении, черновых выпусках и примечаниях к выпуску. Если вы впервые используете API издателя, мы рекомендуем создать черновой выпуск и завершить выпуск в консоли Google Play, чтобы убедиться, что все настроено правильно .

curl -H "$(oauth2l header --json $HOME/{apiKey} androidpublisher)" -XPUT -H "Content-Type: application/json" -d "{ releases: [{status: '{status}', versionCodes: ['{versionCode}'] }]}" 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