Distribuir apps para Android a testadores com o fastlane

Neste guia, descrevemos como distribuir versões do AAB para testadores usando o fastlane, uma plataforma de código aberto que automatiza a criação e o lançamento de apps para iOS e Android. Ele segue instruções simples definidas em um Fastfile. Depois de configurar o fastlane e o Fastfile, é possível integrar o App Distribution à sua configuração do fastlane.

O App Distribution é integrado ao serviço de Compartilhamento interno de apps do Google Play para processar os AABs enviados e disponibilizar APKs otimizados para os Configuradores de dispositivo dos seus 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 no App Distribution, vincule seu app do Firebase a um aplicativo 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 de 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, incluindo 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 aplicativo 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 settings Configuraçõ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 exibidas 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 o fastlane

1. Instalar e configurar o fastlane.

2. Para adicionar o App Distribution à sua configuração do Fastlane, execute o seguinte comando a partir da raiz do seu projeto Android:

   fastlane add_plugin firebase_app_distribution

   Se o comando solicitar uma escolha, selecione Option 3: RubyGems.org.

Etapa 2. Autenticar no Firebase

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

Etapa 3. Configurar o Fastfile e distribuir o app

1. Em uma linha ./fastlane/Fastfile, adicione um bloco firebase_app_distribution. Use os seguintes parâmetros para configurar a distribuição:

   Parâmetros firebase_app_distribution
   app	Obrigatório: ID do app do Firebase do seu aplicativo. É possível encontrar o ID do app no Console do Firebase, na página Configurações gerais. app: "1:1234567890:android:0a1b2c3d4e5f67890"
   firebase_cli_token	Um token de atualização que é impresso quando você autentica o ambiente de CI com a CLI do Firebase. Para mais informações, consulte Usar a CLI com sistemas de CI.
   service_credentials_file	O caminho para o arquivo JSON da sua conta de serviço do Google. Veja acima como fazer a autenticação usando credenciais da conta de serviço.
   android_artifact_type	Especifica o tipo de arquivo do Android (APK ou AAB).
   android_artifact_path	Substitui apk_path (descontinuado). Caminho absoluto para o APK ou o arquivo AAB que você quer enviar. Se não for especificado, o fastlane vai determinar o local do arquivo na linha em que o arquivo foi gerado.
   release_notes release_notes_file	Notas da versão para este build. É possível especificar as notas da versão diretamente: release_notes: "Text of release notes" Como opção, especifique o caminho para um arquivo de texto simples: release_notes_file: "/path/to/release-notes.txt"
   testers testers_file	Os endereços de e-mail dos testadores que você quer convidar. É possível especificar os testadores como uma lista separada por vírgulas de endereços de e-mail: testers: "ali@example.com, bri@example.com, cal@example.com" Como opção, especifique o caminho para um arquivo de texto simples que contém uma lista separada por vírgulas de endereços de e-mail: testers_file: "/path/to/testers.txt"
   groups groups_file	Os grupos de testadores que você quer convidar (consulte Gerenciar testadores). Grupos são especificados usando aliases de grupo, que podem ser encontrados no Console do Firebase. É possível especificar os grupos como uma lista separada por vírgulas: groups: "qa-team, trusted-testers" Também é possível especificar o caminho para um arquivo de texto simples contendo uma lista separada por vírgulas de nomes de grupos: groups_file: "/path/to/groups.txt"
   debug	Uma sinalização booleana. É possível definir isso como true para imprimir a saída de depuração detalhada.

platform :android do
    desc "My awesome app"
    lane :distribute do
        build_android_app(task: "bundle", ...)
        # build_android_app is a built-in fastlane action.
        release = firebase_app_distribution(
            app: "1:123456789:android:abcd1234",
            testers: "tester1@company.com, tester2@company.com",
            release_notes: "Lots of amazing new features to test out!",
            android_artifact_type: "AAB"
        )
    end
end

Para disponibilizar o build para os testadores, execute a linha:

fastlane <lane>

O valor de retorno da ação é um hash que representa a versão enviada. Esse hash também está disponível em lane_context[SharedValues::FIREBASE_APP_DISTRO_RELEASE]. Para mais informações sobre os campos disponíveis no hash, consulte a documentação da API REST.

O plug-in fastlane 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:

• Um link para o Console do Firebase exibindo uma única versão. Você pode compartilhar esse link com outros desenvolvedores na sua organização.
• 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 de acesso à versão para usar o link.
• 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 App Distribution do Console do Firebase por 150 dias. 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 iniciar o processo. Os testadores atuais recebem notificações por e-mail informando que um novo build está pronto para ser testado. Para saber como instalar o app de teste, consulte o guia de configuração do testador. É possível monitorar o status de cada testador para determinar se ele aceitou o convite e se fez o download do app no Console do Firebase.

(Opcional) Para incrementar automaticamente o número da versão sempre que criar uma nova versão no App Distribution, use a ação firebase_app_distribution_get_latest_release e, por exemplo, o plug-in increment_version_code do fastlane. O código a seguir mostra um exemplo de como incrementar automaticamente o número da versão:

lane :increment_version do
  latest_release = firebase_app_distribution_get_latest_release(
    app: "<your Firebase app ID>"
  )
  increment_version_code({ version_code: latest_release[:buildVersion].to_i + 1 })
end

Para saber mais sobre a ação firebase_app_distribution_get_latest_release, consulte Ver informações sobre a versão mais recente do seu app.

Etapa 4 (opcional). Como gerenciar testadores para a distribuição

É possível adicionar e remover testadores do projeto ou grupo usando o arquivo Fastfile ou executando ações do fastlane diretamente. As ações em execução substituem os valores definidos em Fastfile.

Depois que um testador for adicionado ao projeto do Firebase, é possível adicionar às versões individuais. Os testadores removidos de um projeto do Firebase 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.

Se você tiver um grande número de testadores, considere usar grupos.

Usar Fastfile

# Use lanes to add or remove testers from a project.
lane(:add_testers) do
  firebase_app_distribution_add_testers(
    emails: "foo@google.com,bar@google.com"
    # or file: "/path/to/testers.txt"
    group_alias: "qa-team" # (Optional) add testers to this group
  )
end

lane(:remove_testers) do
  firebase_app_distribution_remove_testers(
    emails: "foo@google.com,bar@google.com"
    # or file: "/path/to/testers.txt"
    group_alias: "qa-team" # (Optional) remove testers from this group only
  )
end

# Add or remove testers with the terminal
$ fastlane add_testers
$ fastlane remove_testers

Executar ações do fastlane

fastlane run firebase_app_distribution_create_group display_name:"QA Team" alias:"qa-team"
fastlane run firebase_app_distribution_add_testers group_alias:"qa-team" emails:"foo@google.com,bar@google.com"
fastlane run firebase_app_distribution_remove_testers group_alias:"qa-team" emails:"foo@google.com,bar@google.com"
fastlane run firebase_app_distribution_delete_group alias:"qa-team"

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

As tarefas firebase_app_distribution_add_testers e firebase_app_distribution_remove_testers também aceitam os seguintes argumentos:

• project_name: o número do seu projeto do Firebase.
• group_alias (opcional): se especificado, os testadores são adicionados ao grupo especificado (ou removidos dele).
• service_credentials_file: o caminho para o arquivo de credenciais do serviço do Google.
• firebase_cli_token: token de autenticação para a CLI do Firebase.

service_credentials_file e firebase_cli_token são os mesmos argumentos usados pela ação de upload.

Etapa 5 (opcional). Ver informações sobre a versão mais recente do seu app

Use a ação firebase_app_distribution_get_latest_release para buscar informações sobre a versão mais recente do seu app no App Distribution, incluindo informações e notas sobre a versão do app, além do horário de criação. Os casos de uso incluem o aumento automático da versão e a transferência das notas da versão anterior.

O valor de retorno da ação é um hash que representa a versão mais recente. Esse hash também está disponível em lane_context[SharedValues::FIREBASE_APP_DISTRO_LATEST_RELEASE]. Para mais informações sobre os campos disponíveis no hash, consulte a documentação da API REST.

Parâmetros

app: "1:1234567890:android:0a1b2c3d4e5f67890"

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.

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