Configurar entrega 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.

No momento, 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 será transferido por download no momento da instalação do app. No entanto, o app poderá solicitar o download do módulo sob demanda usando a biblioteca Play Core.

Antes de começar, verifique se você está usando o Android Studio 3.5 ou 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, durante uma confirmação 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 strings 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 Inclusão no momento da instalação, selecione Incluir apenas o módulo na instalação do app para dispositivos com recursos especificados, que cria um módulo incluído no app na instalação do app somente em dispositivos com determinadas configurações que você pode especificar, como recursos do 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 da lista suspensa e selecione uma das sugestões exibidas.
      • 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 da lista suspensa e selecione uma das sugestões exibidas.
    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 sob demanda para esse módulo e desativar a fusão para omiti-lo em dispositivos que não são compatíveis com o download e a 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.

Adicionar opções de entrega condicional a um módulo de recursos 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 poderá 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>