Как настроить условную доставку

Условная доставка позволяет задать определенные требования к конфигурации устройства, чтобы модули функций скачивались автоматически во время установки приложения. Например, вы можете настроить модуль функции, который включает функциональность для дополненной реальности (AR), чтобы он был доступен при установке приложения только на устройствах, которые поддерживают AR.

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

Если устройство не соответствует всем указанным требованиям, модуль не будет скачан при установке приложения. Однако позже приложение может запросить скачивание модуля по запросу с помощью Play Core SDK.

Прежде чем начать, убедитесь, что вы используете Android Studio 3.5 или более поздней версии. В следующих разделах рассказывается, как добавить поддержку условной доставки в модули функций.

Как добавить новый модуль с условной доставкой

Проще всего создать модуль функции с условной доставкой с помощью мастера New Module (Новый модуль). Для этого выполните следующие действия:

  1. Чтобы открыть диалоговое окно New Module (Новый модуль), в строке меню выберите File (Файл) > New (Создать) > New Module (Новый модуль).
  2. В диалоговом окне New Module (Новый модуль) выберите Dynamic Feature Module (Модуль динамических функций) и нажмите Next (Далее).
  3. Настройте модуль как обычно и нажмите Далее.
  4. В разделе Module Download Options (Параметры скачивания модулей) выполните следующие действия:

    1. Укажите название модуля (не более 50 символов). Платформа использует это название, чтобы идентифицировать модуль для пользователей, например когда запрашивает подтверждение на скачивание модуля. Поэтому в базовом модуле приложения должно быть указано название модуля в виде строкового ресурса, который можно перевести. При создании модуля в Android Studio интегрированная среда разработки автоматически добавляет строковый ресурс в базовый модуль и вставляет в манифест модуля функции следующую запись:

      <dist:module
          ...
          dist:title="@string/feature_title">
      </dist:module>
      
    2. В раскрывающемся меню Включение при установке выберите Включать модуль при установке приложения только на устройства с определенными функциями. Модуль будет устанавливаться вместе с приложением только на устройства с определенными характеристиками, например функциями или страной. Android Studio добавляет в манифест модуля следующий код:

      <dist:module ... >
        <dist:delivery>
            <dist:install-time>
                <dist:conditions>
                    <!-- If you specify conditions, as described in the steps
                         below, the IDE includes them here. -->
                </dist:conditions>
            </dist:install-time>
        </dist:delivery>
      </dist:module>
      
    3. Если вы хотите ограничить автоматическое скачивание модуля определенными странами или минимальным уровнем API, нажмите Готово, чтобы завершить создание модуля, а затем прочитайте раздел о том, как указать условия на основе страны или минимального уровня API. В противном случае нажмите + функция устройства, чтобы добавить функцию, которая требуется устройству для скачивания модуля во время установки.

    4. Рядом с параметром device-feature выберите в раскрывающемся меню один из следующих вариантов и укажите его значение:

      • Name. Позволяет указать аппаратную или программную функцию, которая требуется устройству для скачивания модуля во время установки. Поддерживаемые функции условной доставки совпадают с константами FEATURE_*, перечисленными в PackageManager. Если вы выберете этот вариант, начните вводить любую часть постоянного значения функции, например "bluetooth", в поле рядом с раскрывающимся меню и выберите один из предложенных вариантов.
      • Версия OpenGL ES. Позволяет указать версию OpenGL ES, которая должна быть установлена на устройстве, чтобы модуль скачивался при установке. Если вы выберете этот вариант, начните вводить версию, например "0x00030001", в поле рядом с раскрывающимся меню и выберите один из предложенных вариантов.
    5. Если вы хотите добавить несколько условий на основе доступных функций устройства, нажмите + функция устройства для каждого условия, которое хотите указать.

    6. Установите флажок Объединение, если хотите, чтобы этот модуль был доступен на устройствах с Android 4.4 (уровень API 20) и более ранних версий и входил в состав набора APK. Это значит, что вы можете включить для этого модуля поведение по запросу и отключить объединение, чтобы он не устанавливался на устройствах, которые не поддерживают скачивание и установку раздельных APK. Android Studio добавит в манифест модуля следующий код:

      <dist:module ...>
          <dist:fusing dist:include="true | false" />
      </dist:module>
      
  5. Завершив настройку параметров скачивания модулей, нажмите Finish (Готово).

Обратите внимание, что плагин Android Gradle не поддерживает запуск lint из модулей динамических функций. Если запустить lint из соответствующего модуля приложения, то будут проверены и модули динамических функций, а все проблемы будут включены в отчет lint для приложения.

Как добавить условную доставку в существующий модуль функции

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

Для начала вам нужно перенести манифест в новый элемент <dist:delivery>. Ниже приведен пример старого синтаксиса.

<!-- This is the old syntax. -->
<dist:module
  dist:title="@string/feature_title" dist:onDemand="true">
  <dist:fusing dist:include="true"/>
</dist:module>

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

<dist:module
  dist:title="@string/feature_title">
  <dist:delivery>
      <dist:on-demand/>
  </dist:delivery>
  <dist:fusing dist:include="true"/>
</dist:module>

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

<dist:module
    dist:title="@string/feature_title">
    <dist:delivery>
      <dist:on-demand/>
      <dist:install-time>
        <dist:conditions>
          <!-- Requires that the device support AR to download the module at
          app install-time.  -->
          <dist:device-feature dist:name="android.hardware.camera.ar"/>
        </dist:conditions>
      </dist:install-time>
    </dist:delivery>
    <dist:fusing dist:include="true"/>
</dist:module>

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

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

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

Вариант скачивания модуля Совместимость с условной доставкой
Объединение (<dist:fusing dist:include="true"/>) Если для модуля задано значение true, Google Play не будет учитывать условную доставку при развертывании приложения на устройствах с уровнем API 19 или ниже. Это значит, что модули функций, которые позволяют объединять код, всегда включаются при установке на устройствах с уровнем API 19 или ниже.
С мгновенным запуском (<dist:module dist:instant="true"/>) Для модулей функций с мгновенным запуском не поддерживаются варианты условной доставки.
По запросу (<dist:on-demand/>) По умолчанию, если вы задаете параметры условной доставки, модуль также доступен по запросу.

Укажите условия в зависимости от страны

Условная доставка также позволяет указать, в каких странах модуль будет скачиваться при установке приложения, а в каких – нет. Это может быть полезно, например, если ваш модуль реализует способ оплаты, недоступный в некоторых регионах.

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

Чтобы указать страны для модуля, добавьте в его манифест следующий код:

<dist:conditions>
   <!-- Set to "true" to specify countries to exclude from downloading
   this module at app install-time. By default, modules are available
   for download to all user countries. -->
  <dist:user-countries dist:exclude="true">
    <!-- Specifies the two-letter  CLDR country code for regions that should
    not download the module at app install-time. -->
    <dist:country dist:code="CN"/>
    <dist:country dist:code="HK"/>
  </dist:user-countries>
</dist:conditions>

Укажите условия для уровня API

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

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

<dist:conditions>
    <!-- Specifies the minimum API level that the device must satisfy
         in order to download your module at app install-time. The API level you
         specify must be greater or equal to the module's own minSdkVersion. -->
   <dist:min-sdk dist:value="21"/>
    <!-- Specifies the maximum API level that the device cannot exceed
         in order to download your module at app install-time. The API level you
         specify must be less than or equal to the module's own maxSdkVersion. -->
   <dist:max-sdk dist:value="24"/>
</dist:conditions>

Как задать условия для других свойств устройств (бета-версия)

Чтобы задать условия для других свойств устройства, таких как название модели, ОЗУ, системные функции и процессор, можно использовать файл конфигурации таргетинга на устройства.

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

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

<dist:conditions>
   <dist:device-groups>
      <dist:device-group dist:name="myCustomGroup1"/>
      <dist:device-group dist:name="myCustomGroup2"/>
   </dist:device-groups>
</dist:conditions>