Criar um pacote de apps instantâneo

Você cria uma experiência do Google Play Instant ao incluí-lo como parte de um Android App Bundle. Esse pacote é conhecido como um pacote de apps instantâneos. Este documento mostra como configurar seu ambiente de desenvolvimento para pacotes de apps instantâneos e como configurar, criar, testar e publicar um pacote de apps instantâneos.

Se você já tiver um projeto de app instantâneo que use o plug-in de recurso obsoleto (com.android.feature), aprenda a migrar seu app instantâneo para torná-lo compatível com Android App Bundles.

Observação: para publicar um pacote de apps, é necessário ativar a Assinatura de apps do Google Play.

Configurar o ambiente de desenvolvimento

Para oferecer uma experiência instantânea em um pacote de apps, você precisa de acesso ao SDK de desenvolvimento do Google Play Instant. Para instalar o SDK, siga um destes métodos:

• Instale o Android Studio 3.6 ou uma versão mais recente. Depois de abrir o Android Studio, faça o download do SDK de desenvolvimento do Google Play Instant na guia Ferramentas do SDK do SDK Manager.

• Instale a partir da linha de comando:

  cd path/to/android/sdk/tools/bin && \
    ./sdkmanager 'extras;google;instantapps'
  

Além disso, se você quiser testar sua experiência instantânea localmente, acesse um dispositivo virtual ou físico.

Saber mais sobre as condições de execução necessárias

O Google Play Instant executa pacotes de apps instantâneos em um tipo especial de sandbox do SELinux para maior segurança. Esse sandbox aceita um subconjunto de permissões, bem como tipos limitados de interações com outros apps. As seções a seguir explicam as características desse sandbox com mais detalhes.

Permissões e operações compatíveis

Os pacotes de apps instantâneos só podem usar permissões desta lista:

• ACCESS_COARSE_LOCATION
• ACCESS_FINE_LOCATION
• ACCESS_NETWORK_STATE
• BILLING: obsoleto desde a biblioteca Play Faturamento 1.0.
• CAMERA
• INSTANT_APP_FOREGROUND_SERVICE: somente no Android 8.0 (API de nível 26) e versões mais recentes.
• INTERNET
• READ_PHONE_NUMBERS: somente no Android 8.0 (API de nível 26) e versões mais recentes.
• RECORD_AUDIO
• VIBRATE
• WAKE_LOCK

Como lidar com permissões comuns incompatíveis

Esta é uma lista de permissões comuns incompatíveis que precisam ser removidas do seu app e o caminho de migração recomendado para cada uma delas:

• ACCESS_WIFI_STATE: use ACCESS_NETWORK_STATE, que precisa fornecer informações semelhantes a ACCESS_WIFI_STATE.
• BILLING: esta é uma permissão obsoleta. Use a biblioteca do Google Play Faturamento, que não precisa mais da permissão com.android.vending.BILLING.
• READ/WRITE_EXTERNAL_STORAGE: os apps instantâneos não têm acesso ao armazenamento externo, então use o interno.
• com.google.android.c2dm.permission.RECEIVE e permission.C2D_MESSAGE: o C2DM está obsoleto. Migre para o Firebase Cloud Messaging (FCM). O FCM não precisa de outras permissões para funcionar.

Além disso, os pacotes de apps instantâneos não podem fazer o seguinte:

• Usar serviços em segundo plano.
• Enviar notificações quando são executados em segundo plano.

Acesso a apps instalados

Ao desenvolver uma experiência instantânea, lembre-se de que ela não pode interagir com apps instalados em um dispositivo, a menos que uma das seguintes situações seja verdadeira:

• Uma ou mais atividades no app instalado têm o elemento android:visibleToInstantApps configurado como true. Esse elemento está disponível para apps com Android 8.0 (API de nível 26) ou versões mais recentes.
• Um app instalado tem um filtro de intent que inclui CATEGORY_BROWSABLE.
• A experiência instantânea está enviando uma intent usando a ação ACTION_SEND, ACTION_SENDTO ou ACTION_SEND_MULTIPLE.

Configurar seu projeto para experiências instantâneas

Para ser compatível com o Google Play Instant, você precisa configurar vários aspectos do pacote de apps instantâneos com atenção. As seções a seguir descrevem essas considerações.

Declarar dependências do projeto

Para usar as APIs do Google Play Instant no seu app, inclua a seguinte declaração no arquivo de configuração build.gradle do módulo do app:

Groovy

implementation "com.google.android.gms:play-services-instantapps:17.0.0"

Kotlin

implementation("com.google.android.gms:play-services-instantapps:17.0.0")

Definir os códigos de versão corretos

O código da versão da experiência instantânea do seu app precisa ser menor que o código da versão do app instalável. Espera-se que, depois da experiência no Google Play Instant, os usuários façam o download e instalem o app nos dispositivos deles. O framework do Android considera essa transição como uma atualização de app.

Observação: se o usuário tiver a versão instalada do app no dispositivo, ela sempre será executada em vez da experiência instantânea. Isso acontece mesmo que a versão instalada seja uma versão mais antiga do app em comparação com a experiência instantânea.

Para seguir o esquema de controle de versões que os usuários esperam encontrar, adote uma destas estratégias:

• Reinicie os códigos de versão para a experiência no Google Play Instant em 1.
• Aumente o código de versão do APK instalável para um número alto, por exemplo, 1.000, para garantir que exista espaço suficiente para que o número da versão de experiência do seu app instantâneo possa crescer.

Não há problema em desenvolver seu app instantâneo e seu app instalado em dois projetos separados do Android Studio. No entanto, se você fizer isso, precisará realizar as seguintes etapas para publicar seu app no Google Play:

1. Use o mesmo nome de pacote nos dois projetos do Android Studio.
2. No Google Play Console, faça upload das duas variantes para o mesmo app.

Observação: o código de versão não é um valor voltado para o usuário e é usado principalmente pelo sistema. O nome da versão voltado para o usuário não tem restrições.

Para ver mais detalhes sobre como configurar a versão do seu app, consulte Controlar versões do app.

Atualizar a versão do sandbox de destino

O arquivo AndroidManifest.xml do app instantâneo precisa ser atualizado para ser destinado ao ambiente do sandbox compatível com o Google Play Instant. É possível concluir essa atualização adicionando o atributo android:targetSandboxVersion ao elemento <manifest> do seu app, conforme mostrado no snippet de código a seguir.

<manifest
   xmlns:android="http://schemas.android.com/apk/res/android"
  ...
   android:targetSandboxVersion="2" ...>

Para ver mais informações, consulte a documentação sobre o atributo targetSandboxVersion.

Declarar módulos de apps instantâneos

Você pode declarar que o pacote de apps é compatível com experiências instantâneas usando um destes métodos:

• Se você tiver um pacote de apps que contenha apenas um módulo base, poderá ativá-lo instantaneamente da seguinte maneira:

  1. Abra o painel Project, selecionando View > Tool Windows > Project na barra de menus.
  2. Clique com o botão direito no módulo base, normalmente chamado de "app", e selecione Refactor > Enable Instant Apps Support.
  3. Na caixa de diálogo exibida, selecione o módulo base no menu suspenso.
  4. Clique em OK.

  O Android Studio adiciona a seguinte declaração ao manifesto do módulo:

  <manifest ... xmlns:dist="http://schemas.android.com/apk/distribution">
      <dist:module dist:instant="true" />
      ...
  </manifest>
  

  Observação: por padrão, o módulo base de um pacote de apps é chamado de app.

• Se você tiver um pacote de apps que contenha vários módulos, crie um módulo de recursos compatível com instantâneos. Esse processo também torna o módulo básico do seu app compatível com instantâneos, oferecendo a opção de compatibilidade com vários pontos de entrada instantâneos ao seu app.

Observação: um determinado módulo pode conter várias atividades. No entanto, para que um pacote de apps seja compatível com instantâneos, o tamanho de download combinado do código e dos recursos em todos os módulos compatíveis com instantâneos precisa ser de, no máximo, 15 MB.

Adicionar compatibilidade com login

Se a experiência instantânea permitir que os usuários façam login, seu pacote de apps instantâneos precisa ser compatível com o Smart Lock para senhas no Android. Se você estiver criando um jogo instantâneo do Google Play, use o login com os Serviços relacionados a jogos do Google Play.

Suporte ao ambiente de execução

Para ser compatível com a sandbox do SELinux em que as experiências instantâneas são executadas, considere o seguinte ao criar seu pacote de apps instantâneos:

• Não compartilhe o valor de myUid(), que é o UID atribuído pelo kernel do processo do app.
• Se o app for direcionado para o Android 8.1 (API de nível 27) ou uma versão anterior, crie um arquivo de configuração de segurança de rede e defina cleartextTrafficPermitted como false. As experiências instantâneas não são compatíveis com o tráfego HTTP. Para apps direcionados para Android 9 ou versão mais recente, o tráfego de texto simples é desativado por padrão.

• O download da experiência instantânea permanece no dispositivo do usuário até que o cache da experiência seja apagado, o que ocorre em uma das seguintes situações:

  • O cache da experiência instantânea é coletado da lixeira porque o dispositivo está com pouca memória disponível.
  • O usuário reinicia o dispositivo.

  Se um desses processos ocorrer, é necessário que o usuário faça novamente o download da sua experiência instantânea para interagir com ela.

• Se o sistema estiver com pouco espaço de armazenamento, é possível que os dados do usuário da experiência instantânea sejam removidos do armazenamento interno. Portanto, é recomendável sincronizar periodicamente os dados do usuário com o servidor do app para que o progresso do usuário seja preservado.

Adicionar lógica para fluxos de trabalho de experiência instantânea

Depois de configurar o pacote de apps para que ele seja compatível com experiências instantâneas, adicione a lógica mostrada nas seções a seguir.

Verificar se o app está executando a experiência instantânea

Se parte da lógica do seu app depender de o usuário estar envolvido na experiência instantânea, chame o método isInstantApp(). Esse método retornará true se o processo em execução no momento for uma experiência instantânea.

Exibir uma solicitação de instalação

Se você estiver criando uma versão de avaliação do seu app ou jogo, o Google Play Instant permitirá a exibição de uma solicitação na sua experiência instantânea, convidando os usuários a instalar a experiência completa no dispositivo. Para exibir essa solicitação, use o método InstantApps.showInstallPrompt(), conforme mostrado no snippet de código a seguir.

Kotlin

class MyInstantExperienceActivity : AppCompatActivity {
    // ...
    private fun showInstallPrompt() {
        val postInstall = Intent(Intent.ACTION_MAIN)
                .addCategory(Intent.CATEGORY_DEFAULT)
                .setPackage(your-installed-experience-package-name)

        // The request code is passed to startActivityForResult().
        InstantApps.showInstallPrompt(this@MyInstantExperienceActivity,
                postInstall, request-code, /* referrer= */ null)
    }
}

Java

public class MyInstantExperienceActivity extends AppCompatActivity {
    // ...
    private void showInstallPrompt() {
        Intent postInstall = new Intent(Intent.ACTION_MAIN)
                .addCategory(Intent.CATEGORY_DEFAULT)
                .setPackage(your-installed-experience-package-name);

        // The request code is passed to startActivityForResult().
        InstantApps.showInstallPrompt(MyInstantExperienceActivity.this,
                postInstall, request-code, /* referrer= */ null);
    }
}

Transferir dados para uma experiência instalada

Se o usuário gostar da sua experiência instantânea, poderá decidir instalar o app. Para proporcionar uma boa experiência ao usuário, é importante que os dados dele sejam transferidos da experiência instantânea para a versão completa do seu app.

Se o usuário estiver usando um dispositivo com o Android 8.0 (API de nível 26) ou versão mais recente e especificar um targetSandboxVersion de 2, os dados do usuário serão transferidos automaticamente para a versão completa do seu app. Caso contrário, você precisará transferir os dados manualmente. Para fazer isso, use uma das seguintes APIs:

• Para usuários que usam dispositivos com Android 8.0 (API de nível 26) e versões mais recentes, use a API Cookie: app de amostra (link em inglês)
• Se os usuários puderem interagir com sua experiência em dispositivos com Android 7.1 (API de nível 25) e versões anteriores, adicione compatibilidade com a API Storage: app de amostra (link em inglês)

Criar o pacote de apps

Você pode usar o Android Studio ou a interface de linha de comando para criar seu pacote de apps instantâneos.

Android Studio

Com o Android Studio, você pode criar seu pacote de apps selecionando Build > Build Bundle(s) / APK(s) > Build Bundle(s). Para ver mais informações sobre como criar seu projeto, consulte Criar o projeto.

Interface de linha de comando

Você também pode criar o pacote de apps a partir da linha de comando usando o Gradle.

Suporte a arquiteturas de 64 bits

Os apps publicados no Google Play precisam ter suporte a arquiteturas de 64 bits. A adição de uma versão de 64 bits do seu app proporciona melhorias de desempenho e faz com que ele só possa ser executado em hardware com 64 bits. Saiba mais sobre o suporte a 64 bits.

Testar a experiência instantânea

Antes de publicar seu pacote de apps instantâneos, teste a experiência instantânea em um dos seguintes locais para verificar a funcionalidade:

• Instale em um dispositivo local usando o Android Studio.
• Instale em um dispositivo local usando a interface de linha de comando.
• Publique na faixa de teste interno do Google Play Console.

.

Observação :as experiências instantâneas estão disponíveis apenas em dispositivos com o Android 8.0 (API nível 26) ou mais recente.

Android Studio

Para testar a experiência instantânea do seu app em uma máquina local usando o Android Studio, siga estas etapas:

1. Se houver uma versão do app instalada no dispositivo de teste, desinstale-a.
2. No Android Studio, nas opções de instalação que aparecem na guia General da caixa de diálogo Run/Debug Configurations , marque a caixa de seleção Deploy as instant app.
3. Selecione Run > Run na barra de menus ou clique em Run na barra de ferramentas e escolha o dispositivo em que você quer testar as experiências instantâneas do app. A experiência instantânea do seu app será carregada no dispositivo de teste que você escolher.

Interface de linha de comando

Para testar a experiência instantânea do seu app em uma máquina local usando a linha de comando, siga estas etapas:

1. Se houver uma versão do app instalada no dispositivo de teste, desinstale-a.
2. Transfira seu app instantâneo por sideload e execute-o no dispositivo de teste inserindo o seguinte comando:

ia run output-from-build-command

Observação: é possível fornecer informações alternativas para ia run para iniciar um instante em um dispositivo de teste. Para mais informações, execute o comando: ia help run.

Faixa de teste interno

Para testar a experiência instantânea do seu app na Play Store ou em um banner do seu site, publique o app na faixa de teste interno do Play Console.

Para isso, siga estas etapas:

1. Faça upload do pacote de apps seguindo as etapas do guia Fazer upload do seu pacote de apps para o Play Console.
2. Prepare o pacote enviado para lançamento na faixa de teste interno. Para ver mais informações, consulte o artigo de suporte sobre como Preparar e lançar versões.

3. Faça login em uma conta de testes interna em um dispositivo e inicie sua experiência instantânea a partir de uma das seguintes superfícies:

   • O botão Quero testar nas informações do app na Play Store
   • Link de um banner no site do seu app

Observação: quando você usa a faixa de teste interno do Google Play, o Play Console não aplica os limites de tamanho discutidos na visão geral do Google Play Instant. Portanto, você pode testar e apresentar internamente uma experiência instantânea, mesmo que ela tenha mais de 15 MB.

Publicar o pacote de apps na faixa de produção

Observação: o programa Feito para Família não é compatível com o Google Play Instant. Se seu app ou jogo não é desenvolvido para crianças, será necessário cancelar a inscrição no programa para Famílias. para publicar um app ou jogo instantâneo.

Observação: a partir de junho de 2023, apenas os apps instantâneos publicados com pacotes de apps serão disponíveis para os usuários. Verifique se todos os apps instantâneos baseados em APK foram foram atualizados para os pacotes instantâneos.

Para publicar seu pacote de apps instantâneos, siga estas etapas:

1. Assine o pacote de apps com uma chave de lançamento e faça upload do pacote para o Play Console, caso ainda não tenha feito isso.
2. No Play Console, abra Gerenciamento da versão > Instant Apps Android e navegue até a faixa de produção de app instantâneo.
3. Selecione Atualizar na biblioteca e escolha o pacote de apps instantâneos que você enviou.

Escolher onde publicar sua experiência instantânea

É possível lançar uma experiência instantânea do seu app em um subconjunto de países e regiões onde as pessoas podem instalá-lo. Esse recurso é útil quando você quer promover a experiência instantânea do seu app para usuários que residem em um conjunto específico de países e regiões.

Outros recursos

Para saber mais sobre como criar experiências instantâneas e Android App Bundles, consulte os seguintes recursos:

Vídeo: empacotar um app em um instantâneo (em inglês)

Aprenda a adicionar uma experiência instantânea a um Android App Bundle nesta sessão da Conferência de Desenvolvedores Android 2018.

Vídeo: publicar apps menores com o Android App Bundle (em inglês)

Aprenda como os pacotes de apps ajudam a desenvolver seu app de forma mais rápida e criam APKs menores para seus usuários.

Codelab: seu primeiro Android App Bundle (link em inglês)

Um guia passo a passo para criar um Android App Bundle e adicionar recursos a ele.

O formato Android App Bundle

Saiba mais sobre como o programa de linha de comando bundletool organiza um pacote de apps a partir do código e dos recursos do seu app.