Configurar o envio condicional

A entrega condicional permite que você defina alguns requisitos de configuração de dispositivos para que os módulos de recursos sejam transferidos por download automaticamente durante a instalação do app. Por exemplo, você pode configurar um módulo de recursos que inclua a funcionalidade de realidade aumentada (RA) disponível na instalação do app apenas para dispositivos compatíveis com RA.

Atualmente, esse mecanismo de entrega permite controlar o download de um módulo no momento da instalação do app com base nas seguintes configurações de dispositivos:

Se um dispositivo não atender a todos os requisitos especificados, o módulo não vai ser transferido por download no momento da instalação do app. No entanto, o app vai poder solicitar o download do módulo sob demanda usando o SDK Play Core.

Antes de começar, verifique se você está usando o Android Studio 3.5 ou uma versão mais recente. As seções a seguir mostram como adicionar compatibilidade com a entrega condicional aos seus módulos de recursos.

Adicionar um novo módulo com opções de entrega condicional

A maneira mais fácil de criar um novo módulo de recurso com entrega condicional é usando o assistente New Module, da seguinte maneira:

  1. Para abrir a caixa de diálogo New Module, selecione File > New > New Module na barra de menus.
  2. Na caixa de diálogo "New Module", selecione Dynamic Feature Module e clique em Next.
  3. Configure seu módulo como faria normalmente e clique em Next.

  4. Na seção Module Download Options, faça o seguinte:

    1. Use a opção Module title para especificar o título do módulo em até 50 caracteres. A plataforma usa esse título para identificar o módulo para o usuário, por exemplo, ao perguntar se o usuário quer fazer o download do módulo. Por isso, o módulo base do app precisa incluir o título do módulo como um recurso de string, que você pode traduzir. Durante a criação do módulo usando o Android Studio, o ambiente de desenvolvimento integrado adiciona o recurso de string ao módulo base para você e injeta a seguinte entrada no manifesto do módulo de recursos:

      <dist:module
    ...
    dist:title="@string/feature_title">
</dist:module>

    2. No menu suspenso em Install-time inclusion, selecione Only include module at app install for devices with specified features, que cria um módulo incluído na instalação do app somente em dispositivos com determinadas configurações que você pode especificar, como recursos de dispositivo ou país. O Android Studio injeta o seguinte no manifesto do módulo para refletir sua escolha:

      <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. Para limitar o download automático do módulo para determinados países ou um nível mínimo de API, clique em Finish para concluir a criação do módulo e, em seguida, leia a seção sobre como especificar condições com base no país ou no nível mínimo de API. Caso contrário, clique em + device feature para adicionar um recurso necessário para o dispositivo fazer o download do módulo no momento da instalação.

    4. Ao lado de device-feature, selecione uma das seguintes opções no menu suspenso e especifique o valor:

      • Name: permite especificar um recurso de hardware ou software necessário para um dispositivo fazer o download do módulo no momento da instalação. Os recursos compatíveis com a entrega condicional são os mesmos listados como constantes FEATURE_* por PackageManager. Se você selecionar essa opção, comece a digitar qualquer parte do valor da constante do recurso, como "bluetooth", no campo ao lado do menu suspenso e selecione uma das sugestões mostradas.
      • OpenGL ES Version: permite que você especifique uma versão do OpenGL ES necessário para um dispositivo fazer o download do módulo no momento da instalação. Se você selecionar essa opção, comece a digitar a versão, como "0x00030001", no campo ao lado do menu suspenso e selecione uma das sugestões mostradas.

    5. Se você quer adicionar várias condições com base nos recursos disponíveis do dispositivo, clique em + device feature para cada condição de recurso do dispositivo que queira especificar.

    6. Marque a caixa ao lado de Fusing se você quiser que esse módulo esteja disponível para dispositivos com Android 4.4 (API de nível 20) e anterior e seja incluído em vários APKs. Isso significa que você pode ativar o comportamento on demand desse módulo e desativar a fusão para o omitir em dispositivos que não oferecem suporte ao download e à instalação de APKs divididos. O Android Studio injeta o seguinte no manifesto do módulo para refletir sua escolha:

      <dist:module ...>
    <dist:fusing dist:include="true | false" />
</dist:module>

  5. Ao terminar de configurar as opções de download de módulo, clique em Finish.

O Plug-in do Android para Gradle não tem suporte para a execução de lint dos módulos de recursos dinâmicos. A execução do lint no módulo de aplicativo correspondente é feita nos módulos de recursos dinâmicos e inclui todos os problemas no relatório do lint do app.

Adicionar opções de entrega condicional a um módulo de recursos já existente

Você pode facilmente adicionar opções de entrega condicional a um módulo de recurso existente por meio do manifesto do módulo. No entanto, leia primeiro sobre a compatibilidade das opções de entrega condicional com outras opções de entrega que você já tenha ativado.

Para começar, primeiro é necessário migrar o manifesto para o novo elemento <dist:delivery>. O snippet de código abaixo mostra um exemplo da sintaxe antiga:

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

Agora, as opções de entrega acima são especificadas da seguinte forma.

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

Em seguida, inclua opções de entrega condicional com base nos recursos do dispositivo da seguinte maneira.

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

As seções abaixo discutem outras opções para entrega condicional, como por país ou nível mínimo de API.

Compatibilidade com outras opções de download de módulo

Como os módulos de recursos oferecem várias opções para configurar como cada recurso é entregue ao dispositivo do usuário, é importante entender como as opções de entrega condicional são afetadas por outras configurações. A tabela a seguir resume a compatibilidade da entrega condicional com outras opções de download de módulo.

Opção de download de módulo Compatibilidade com a entrega condicional
Fusing (<dist:fusing dist:include="true"/>) Se um módulo definir essa opção como true, o Google Play não respeitará as opções de entrega condicional especificadas ao implantar seu app em dispositivos que executam o nível de API 19 ou anterior. Ou seja, os módulos de recursos que permitem a fusão são sempre incluídos na instalação para dispositivos com o nível 19 da API ou mais recente.
Instant-enabled (<dist:module dist:instant="true"/>) As opções de entrega condicional não são compatíveis com módulos de recursos instantâneos.
On demand (<dist:on-demand/>) Por padrão, se você especificar opções de entrega condicional, o módulo também estará disponível sob demanda.

Especificar condições com base no país

A entrega condicional também permite que você especifique quais países impedir (ou permitir) que façam o download do seu módulo no momento da instalação do app. Especificar essa condição pode ser útil se, por exemplo, seu módulo implementa uma forma de pagamento que não está disponível em determinadas regiões.

Nesse contexto, o país do dispositivo é normalmente determinado pelo endereço de faturamento do usuário registrado na conta do Google Play.

Para especificar países para seu módulo, inclua o seguinte no manifesto do módulo de recursos.

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

Especificar condições para o nível da API

Especificar uma condição com base no nível da API do dispositivo pode ser útil se um módulo de recursos depender de APIs disponíveis somente em determinadas versões da plataforma Android.

Para definir uma condição com base em um nível de API mínimo ou máximo do dispositivo, inclua o seguinte no manifesto do módulo de recurso:

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