Distribuir apps para Android a testadores com o fastlane

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

Antes de começar

Adicione o Firebase ao seu projeto para Android, caso ainda não tenha feito isso.

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 na página vinculada acima.

Etapa 1. Configurar o fastlane

1. Instalar e configurar o fastlane.

2. Para adicionar o App Distribution à configuração do fastlane, execute o seguinte comando pela raiz do seu projeto Android:

   fastlane add_plugin firebase_app_distribution

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

Etapa 2. Como autenticar com o 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 procura 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 app. Encontre 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 por 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"
   test_devices test_devices_file	Os tipos de distribuição a seguir fazem parte do recurso Beta Testador automatizado. Os dispositivos de teste para os quais você quer distribuir builds (consulte Testes automatizados). É possível especificar os dispositivos de teste como uma lista de dispositivos de teste separada por ponto e vírgula: test_devices: "model=shiba,version=34,locale=en,orientation=portrait;model=b0q,version=33,locale=en,orientation=portrait" Também é possível especificar o caminho para um arquivo de texto simples que contenha uma lista de dispositivos de teste separada por ponto e vírgula: test_devices_file: "/path/to/test-devices.txt"
   test_username	O nome de usuário para o login automático a ser usado durante os testes automatizados.
   test_password test_password_file	A senha para login automático que será usada durante os testes automatizados. Se preferir, é possível especificar o caminho para um arquivo de texto simples que contenha uma senha: test_password_file: "/path/to/test-password.txt"
   test_username_resource	Nome do recurso para o campo de nome de usuário para login automático que será usado durante os testes automatizados.
   test_password_resource	Nome do recurso do campo de senha para login automático que será usado durante os testes automatizados.
   test_non_blocking	Execute testes automatizados de forma assíncrona. Acesse o console do Firebase para conferir os resultados do teste automático.
   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(...)
        # 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!"
        )
    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 que exibe 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 seu build, ele fica disponível no painel do 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.