Distribuir apps Android para testadores usando o Gradle

Para integrar o App Distribution ao processo de build do Android, use um plug-in do Gradle para App Distribution. O plug-in permite que você especifique testadores e notas de lançamento no arquivo do gradle do seu aplicativo. Assim, você pode configurar distribuições para diferentes tipos de builds e variantes do seu aplicativo.

Neste guia, descrevemos como distribuir Android App Bundles (AABs) para testadores usando o plug-in do Gradle para App Distribution.

O App Distribution se integra ao serviço de compartilhamento interno de apps do Google Play para processar os AABs enviados e disponibilizar APKs otimizados para as configurações do dispositivo dos testadores. Com a distribuição de AABs, você pode fazer o seguinte:

• Executar APKs (distribuídos pelo Google Play) que são otimizados para os dispositivos dos seus testadores

• Descobrir e depurar problemas específicos do dispositivo

• Testar recursos do pacote de app, como o Play Feature Delivery e o Play Asset Delivery

• Reduzir o tamanho dos downloads para seus testadores

Permissões necessárias

Para fazer upload de AABs para o App Distribution, vincule seu app do Firebase a um app no Google Play. Você precisa ter o nível de acesso necessário para realizar essas ações.

Se você não tiver o acesso necessário do Firebase, peça a um proprietário do projeto do Firebase para atribuir a você o papel aplicável usando as configurações de IAM do console do Firebase. Se você tiver dúvidas sobre como acessar seu projeto do Firebase, inclusive como encontrar ou atribuir um proprietário, consulte as perguntas frequentes sobre permissões e acesso aos projetos do Firebase.

A tabela a seguir se aplica à vinculação de um app do Firebase a um app no Google Play e ao upload de AABs.

Antes de começar

1. Adicione o Firebase ao seu projeto para Android, caso ainda não tenha feito isso. No final deste fluxo de trabalho, você terá um app Android do Firebase no seu projeto.

   Caso você não use outros produtos do Firebase, basta criar um projeto e registrar seu app. Se quiser usar outros produtos, conclua todas as etapas em Adicionar o Firebase ao seu projeto do Android.

2. Para criar um link do Firebase para o Google Play e fazer upload de AABs, verifique se seu app atende aos seguintes requisitos:

   • O app no Google Play e o app Android do Firebase são registrados usando o mesmo nome de pacote.

   • O app no Google Play é configurado no painel do app e distribuído para uma das faixas do Google Play: teste interno, teste fechado, teste aberto ou produção.

   • A avaliação do app no Google Play é concluída e ele é publicado. Seu app será publicado se a coluna Status do app exibir um dos seguintes status: teste interno (e não teste interno de rascunho), teste fechado, teste aberto ou produção.

3. Vincule o app Android do Firebase à sua conta de desenvolvedor do Google Play:

   1. No console do Firebase, acesse as settingsConfigurações do projeto e selecione a guia Integrações.

   2. No card do Google Play, clique em Vincular.
      Se você já tiver links para o Google Play, clique em Gerenciar.

   3. Siga as instruções na tela para ativar a integração do App Distribution e selecione quais apps Android do Firebase serão vinculados ao Google Play.

   Saiba mais sobre como vincular ao Google Play.

Etapa 1. Configurar seu projeto do Android

1. No arquivo Gradle no nível raiz do projeto (<project>/build.gradle.kts ou <project>/build.gradle), adicione o plug-in do Gradle para App Distribution como uma dependência:

   Kotlin

   plugins {
       // ...
       id("com.android.application") version "7.3.0" apply false
   
       // Make sure that you have the Google services Gradle plugin dependency
       id("com.google.gms.google-services") version "4.4.2" apply false
   
       // Add the dependency for the App Distribution Gradle plugin
       id("com.google.firebase.appdistribution") version "5.1.1" apply false
   }

   Groovy

   plugins {
       // ...
       id 'com.android.application' version '7.3.0' apply false
   
       // Make sure that you have the Google services Gradle plugin dependency
       id 'com.google.gms.google-services' version '4.4.2' apply false
   
       // Add the dependency for the App Distribution Gradle plugin
       id 'com.google.firebase.appdistribution' version '5.1.1' apply false
   }

2. No arquivo Gradle do módulo (nível do app) (geralmente <project>/<app-module>/build.gradle.kts ou <project>/<app-module>/build.gradle), adicione o plug-in do Gradle para App Distribution:

   Kotlin

   plugins {
     id("com.android.application")
   
     // Make sure that you have the Google services Gradle plugin
     id("com.google.gms.google-services")
   
     // Add the App Distribution Gradle plugin
     id("com.google.firebase.appdistribution")
   }

   Groovy

   plugins {
     id 'com.android.application'
   
     // Make sure that you have the Google services Gradle plugin
     id 'com.google.gms.google-services'
   
     // Add the App Distribution Gradle plugin
     id 'com.google.firebase.appdistribution'
   }

3. Se houver um proxy ou firewall corporativo ativado, adicione a seguinte propriedade do sistema Java que permite que o App Distribution faça upload das distribuições para o Firebase:

   -Djavax.net.ssl.trustStore=/path/to/truststore -Djavax.net.ssl.trustStorePassword=password
   

Etapa 2. Como autenticar com o Firebase

Antes de usar o plug-in do Gradle, primeiro faça a autenticação com seu projeto do Firebase de uma das seguintes maneiras. Por padrão, o plug-in do Gradle procura credenciais da CLI do Firebase se nenhum outro método de autenticação for usado.

Etapa 3. Configurar suas propriedades de distribuição

No arquivo Gradle do módulo (nível do app) (geralmente <project>/<app-module>/build.gradle.kts ou <project>/<app-module>/build.gradle), adicione pelo menos uma seção do firebaseAppDistribution para configurar o App Distribution.

Por exemplo, para distribuir o build release para testadores, siga estas instruções:

import com.google.firebase.appdistribution.gradle.firebaseAppDistribution

android {

  // ...

  buildTypes {
      getByName("release") {
          firebaseAppDistribution {
              artifactType = "AAB"
              releaseNotesFile = "/path/to/releasenotes.txt"
              testers = "ali@example.com, bri@example.com, cal@example.com"
          }
      }
  }

  // ...
}

android {

  // ...

  buildTypes {
      release {
          firebaseAppDistribution {
              artifactType="AAB"
              releaseNotesFile="/path/to/releasenotes.txt"
              testers="ali@example.com, bri@example.com, cal@example.com"
          }
      }
  }

  // ...
}

É possível configurar o App Distribution para tipos de build e variações de produtos.

Por exemplo, para distribuir os builds debug e release nas variações de produto "demonstração" e "completa", siga estas instruções:

import com.google.firebase.appdistribution.gradle.firebaseAppDistribution

android {

  // ...

  buildTypes {
      getByName("debug") {...}
      getByName("release") {...}
  }

  flavorDimensions += "version"
  productFlavors {
      create("demo") {
          dimension = "version"
          firebaseAppDistribution {
              releaseNotes = "Release notes for demo version"
              testers = "demo@testers.com"
          }
      }
      create("full") {
          dimension = "version"
          firebaseAppDistribution {
              releaseNotes = "Release notes for full version"
              testers = "full@testers.com"
          }
      }
  }

  // ...
}

android {

  // ...

  buildTypes {
      debug {...}
      release {...}
  }

  flavorDimensions "version"
  productFlavors {
      demo {
          dimension "version"
          firebaseAppDistribution {
              releaseNotes="Release notes for demo version"
              testers="demo@testers.com"
          }
      }
      full {
          dimension "version"
          firebaseAppDistribution {
              releaseNotes="Release notes for full version"
              testers="full@testers.com"
          }
      }
  }

  // ...
}

Use os seguintes parâmetros para configurar a distribuição:

appId="1:1234567890:android:321abc456def7890"

testers="ali@example.com, bri@example.com, cal@example.com"

testersFile="/path/to/testers.txt"

groups="qa-team, android-testers"

groupsFile="/path/to/tester-groups.txt"

testDevices="model=shiba,version=34,locale=en,orientation=portrait;model=b0q,version=33,locale=en,orientation=portrait"

testDevicesFile="/path/to/testDevices.txt"

testPasswordFile="/path/to/testPassword.txt"

Etapa 4. Distribuir seu app para os testadores

1. Por último, para empacotar o app de teste e convidar testadores, crie os destinos BUILD-VARIANT e appDistributionUploadBUILD-VARIANT com o wrapper do Gradle do projeto, em que BUILD-VARIANT é a variação de produto opcional e o tipo de compilação que você configurou na etapa anterior. Para mais informações sobre as variações de produtos, consulte Configurar variantes de build.

   Por exemplo, para distribuir seu app usando a variante de build release, execute o seguinte comando:

   ./gradlew bundleRelease appDistributionUploadRelease
   

   Ou, se você autenticou com sua Conta do Google e não forneceu credenciais em seu arquivo de build do Gradle, inclua a variável FIREBASE_TOKEN:

   export FIREBASE_TOKEN=1/a1b2c3d4e5f67890
   ./gradlew --stop // Only needed for environment variable changes
   ./gradlew bundleRelease appDistributionUploadRelease
   

2. Também é possível substituir os valores definidos no arquivo build.gradle transmitindo argumentos de linha de comando no formato --<property-name>=<property-value>. Por exemplo:

   • Para fazer upload de um build de depuração para o App Distribution:

     ./gradlew bundleDebug appDistributionUploadDebug
         --artifactType="AAB"

   • Para convidar mais testadores ou remover os que já estão no projeto do Firebase:

     ./gradlew appDistributionAddTesters
         --projectNumber=<project_number>
         --emails="anothertester@email.com, moretesters@email.com"
     ./gradlew appDistributionRemoveTesters
         --projectNumber=<project_number>
         --emails="anothertester@email.com, moretesters@email.com"

     Depois que um testador é adicionado ao seu projeto do Firebase, ele pode ser adicionado a versões individuais. Os testadores removidos não terão mais acesso às versões do seu projeto, mas poderão manter o acesso às versões por um período.

   Também é possível especificar testadores usando --file="/path/to/testers.txt" em vez de --emails.

   As tarefas appDistributionAddTesters e appDistributionRemoveTesters também aceitam os seguintes argumentos:

   • projectNumber: o número do seu projeto do Firebase.

   • serviceCredentialsFile: o caminho para o arquivo de credenciais do serviço do Google. É o mesmo argumento usado na ação de upload.

O plug-in do Gradle gera os seguintes links após o upload da versão. Esses links ajudam a gerenciar binários e garantir que os testadores e outros desenvolvedores tenham a versão certa:

• firebase_console_uri: um link para o console do Firebase que exibe uma única versão. Você pode compartilhar esse link com outros desenvolvedores na sua organização.
• testing_uri: um link para a versão na experiência do testador (app nativo do Android) que permite que os testadores vejam as notas da versão e instalem o app no dispositivo. O testador precisa acessar a versão para usar o link.
• binary_download_uri: um link assinado que faz o download e instala diretamente o binário do app (arquivo APK ou AAB). O link expira depois de uma hora.

Depois de distribuir o build, ele fica disponível no painel do App Distribution do console do Firebase por 150 dias (cinco meses). Quando faltarem 30 dias para o vencimento do build, o aviso de expiração vai aparecer no console e na lista de builds do testador no dispositivo de teste.

Os testadores que não foram convidados para testar o app recebem convites por e-mail para dar os primeiros passos, e os testadores atuais recebem notificações por e-mail informando que um novo build está pronto para ser testado. Leia o guia de configuração do testador para ver instruções sobre como instalar o app de teste. É possível monitorar o status de cada testador, por exemplo, se ele aceitou o convite e se fez o download do app no console do Firebase.

Os testadores têm 30 dias para aceitar um convite de teste do app antes que ele expire. Quando faltarem cinco dias para o vencimento do convite, um aviso de expiração vai aparecer no console do Firebase ao lado do testador em uma versão. Para renovar um convite, reenvie-o usando o menu suspenso na linha do testador.

Próximas etapas

• Implemente o feedback no app para que os testadores possam enviar feedback sobre seu app, incluindo capturas de tela.

• Saiba como mostrar alertas no app aos testadores quando novos builds do app estiverem disponíveis para instalar.

• Acesse o codelab do Android App Bundle para saber como distribuir as versões do pacote de apps etapa por etapa.

• Conheça as práticas recomendadas para distribuir apps Android aos testadores de controle de qualidade usando CI/CD.