Distribuir builds de pré-lançamento do iOS mais rapidamente com o App Distribution e o fastlane

1. Antes de começar

Neste codelab, você vai aprender a usar o Firebase App Distribution e o plug-in fastlane para distribuir um app iOS para testadores, coletar UDIDs de dispositivos de teste e registrá-los no perfil de provisionamento do app. Assim, você pode enviar builds ad hoc rapidamente para os testadores.

O que você vai aprender

• Como fazer upload e distribuir um app iOS de pré-lançamento (Ad Hoc) para testadores usando o App Distribution do Firebase e o fastlane.
• Como se inscrever como testador e fazer o download do app distribuído em um dispositivo de teste.
• Como registrar rapidamente dispositivos de teste exportando os UDIDs deles com o plug-in fastlane da distribuição de apps.
• Como atualizar o perfil de provisionamento do app e fazer o upload novamente para distribuição.

Pré-requisitos

• Uma Conta do Google
• Uma máquina Apple com o XCode 11.7 ou mais recente instalado
• Um app iOS de pré-lançamento do Ad Hoc criado no Xcode
• Uma conta de desenvolvedor da Apple paga
• Um dispositivo iOS físico para testes.

O app simulador do iOS funciona para a maior parte do codelab, mas os simuladores não podem fazer o download de versões.

Para verificar se a configuração funcionou, confira se o botão "Download" aparece no app da Web do testador de distribuição de apps.

2. Primeiros passos

Configurar o fastlane

O App Distribution se integra ao fastlane para permitir a distribuição automatizada de builds de pré-lançamento do app. O App Distribution se integra à configuração do fastlane.

1. Instale e configure o fastlane.
2. Execute fastlane init no diretório raiz do projeto durante a configuração e escolha "Configuração manual". Você vai encontrar um subdiretório chamado fastlane, que contém Fastfile, Appfile e Pluginfile, que serão usados para configurar a faixa rápida.

Instalar a CLI do Firebase

Você também vai precisar instalar a CLI do Firebase. Se você estiver usando macOS ou Linux, execute o seguinte comando cURL:

curl -sL https://firebase.tools | bash

Se você estiver usando o Windows, leia as instruções de instalação para conseguir um binário independente ou instalar pelo npm.

Depois de instalar a CLI, a execução de firebase --version vai informar uma versão de 12.0.0 ou mais recente:

$ firebase --version
12.0.0

3. Criar seu app com o fastlane

Criar o app

1. Defina algumas variáveis globais para fastlane no ./fastlane/Appfile.. Inclua o ID do app e do Apple ID:

app_identifier("<your app's bundle identifier>")
apple_id("<your Apple id>")

2. Crie sua primeira faixa e use a ação build_app da fastlane (também conhecida como gym) para criar seu app adicionando o seguinte à ./fastlane/Fastfile:

default_platform(:ios)

lane :build do
    build_app(export_method: "ad-hoc")
end

3. Assine o app para distribuição.

Neste codelab, você vai gerenciar sua própria certificação e perfil usando get_certificates (também conhecido como cert), que gera certificados de assinatura localmente e armazena tudo no seu Keychain do macOS. No entanto, normalmente, é recomendável usar a fastlane sync_code_signing action (também conhecida como match) para gerenciar com segurança os certificados e perfis de assinatura de código da sua equipe.

lane :build do
    get_certificates()
    build_app(export_method: "ad-hoc")
end

4. Configure um perfil de provisionamento para o app usando a ação get_provisioning_profile (também conhecida como sigh). Assim, você pode compartilhar o app com testadores.

lane :build do
    get_certificates()
    get_provisioning_profile(adhoc: true)
    build_app(export_method: "ad-hoc")
end

5. [Opcional] Se você nunca executou o app, execute o comando a seguir para criar o app no Apple Developer Console:

$ fastlane produce --skip_itc

6. Por fim, crie o app executando a faixa.

Você vai precisar informar seu ID Apple, senha (armazenada no Keychain) e o ID do pacote do app.

$ fastlane build

Se você tiver algum problema, consulte o guia de solução de problemas da fastlane.

4. Fazer upload do app para o Firebase

Agora que você criou o app, está tudo pronto para fazer o upload dele para a distribuição de apps.

Criar e configurar um projeto do Firebase

1. Faça login no Firebase.
2. No Console do Firebase, crie ou adicione um novo projeto e nomeie-o como "UDID Export Codelab".

Você não precisa ativar o Google Analytics neste projeto.

3. Clique em Criar projeto.

Adicionar o app iOS ao projeto

1. Clique no ícone do iOS para criar um novo app iOS do Firebase e insira o ID do pacote do app.

2. Pule as próximas etapas e clique em Continuar no console. Você vai adicionar SDKs ao app mais tarde.

Seu projeto e app agora estão disponíveis na página Visão geral do projeto.

Ativar a Distribuição de apps

1. Na seção "Lançamento e monitoramento", clique em Distribuição de apps.
2. Depois de aceitar os termos, clique em "Começar" para ativar a distribuição de apps.

Configurar uma distribuição no fastlane

1. Execute o comando a seguir na raiz do seu projeto iOS para adicionar o App Distribution à configuração do fastlane.

Se o comando solicitar uma opção, selecione Opção 3: RubyGems.org:

$ fastlane add_plugin firebase_app_distribution

2. Confirme se o plug-in está instalado:

$ fastlane

A saída vai mostrar fastlane-plugin-firebase_app_distribution na lista de plug-ins instalados.

3. Depois de confirmar que o plug-in foi instalado, escolha a opção 0 para cancelar.

Autentique seu projeto do Firebase

Para usar o plug-in fastlane, primeiro faça a autenticação do seu projeto do Firebase.

1. Execute o comando a seguir para conectar a CLI à sua Conta do Google:

$ firebase login

2. Quando o comando imprimir um link de autenticação, abra o link em um navegador.
3. Quando solicitado, faça login na sua Conta do Google e conceda permissão para acessar seu projeto do Firebase.

Distribuir seu app

Agora está tudo pronto para distribuir o app.

1. Na parte de cima do ./fastlane/Fastfile, defina uma variável chamada firebase_app_id. Substitua <your_app_id> pelo ID do app do Firebase que você criou. Ele pode ser encontrado na página Configurações do projeto.

O Fastfile é escrito em Ruby. Portanto, use a sintaxe do Ruby para definir variáveis.

firebase_app_id = "<your_app_id>"

2. Adicione uma nova faixa chamada distribute, que chama a faixa de build e distribui o app usando a ação firebase_app_distribution.

lane :distribute do
    build
    firebase_app_distribution(
        app: firebase_app_id,
        release_notes: "Try out this app!",
    )
end

3. Execute a nova faixa para criar o app e uma distribuição.

$ fastlane distribute

Neste ponto, seu Fastfile vai ficar assim:

firebase_app_id = "<your Firebase app ID>"

default_platform(:ios)

lane :build do
    get_certificates()
    get_provisioning_profile(adhoc: true)
    build_app(export_method: "ad-hoc")
end

lane :distribute do
    build
    firebase_app_distribution(
        app: firebase_app_id,
        release_notes: "Try out this app!",
    )
end

Depois de atualizar o console do Firebase, você vai encontrar a nova versão do app.

5. Convide testadores para fazer o download do seu app

Quando um testador aceita um convite para testar um build ad hoc, ele precisa permitir o compartilhamento do UDID. Se eles concordarem, o App Distribution vai coletar as informações do dispositivo e enviar uma notificação por e-mail. Nesta seção, você vai adicionar a si mesmo como um testador para fazer o download e testar o app que você distribuiu.

Adicionar você como testador à versão

1. Em firebase_app_id, na parte de cima do Fastfile, crie uma variável para armazenar testadores e inclua seu próprio endereço de e-mail, bem como outros endereços de e-mail opcionais que você gostaria de tentar.

firebase_app_id = "<your Firebase app ID>"
app_testers = [
  "[e-mail]",
  "[e-mail]",
]

2. Aplique o método Array#join do Ruby para transformar a matriz app_testers em uma string separada por vírgulas, que é o que o parâmetro testers espera. Em seguida, transmita o resultado para o parâmetro testers de firebase_app_distribution..

lane :distribute do
    build
    firebase_app_distribution(
        app: firebase_app_id,
        release_notes: "Try out this app!"
        testers: app_testers.join(","),
    )
end

Neste ponto, seu Fastfile vai ficar assim:

firebase_app_id = "<your Firebase app ID>"
app_testers = [
  "[e-mail]",
  "[e-mail]",
]

default_platform(:ios)

lane :build do
    get_certificates()
    get_provisioning_profile(adhoc: true)
    build_app(export_method: "ad-hoc")
end

lane :distribute do
    build
    firebase_app_distribution(
        app: firebase_app_id,
        release_notes: "Try out this app!",
        testers: app_testers.join(","),
    )
end

3. Execute a faixa novamente.

$ fastlane distribute

Depois que você executar a faixa, os testadores adicionados vão receber um e-mail de convite do App Distribution notificando a versão recém-disponível. No Console do Firebase, agora é possível conferir os testadores adicionados na versão do app.

Como você incluiu seu endereço de e-mail, vai receber um e-mail do Firebase App Distribution convidando você a testar o app. Você é o primeiro testador! Continue na seção abaixo para configurar o dispositivo de teste como um testador.

Registrar o dispositivo de teste

Como testador, você precisa fazer login no Google no seu dispositivo de teste para acessar as versões do app que você foi convidado a testar. Como o build de teste é uma versão ad hoc, você também precisa registrar o dispositivo de teste instalando o perfil do Firebase. Depois, as versões que ficarem disponíveis podem ser acessadas no app da Web do testador do App Distribution usando o clipe da Web adicionado à tela inicial do dispositivo.

1. No dispositivo de teste iOS, abra o e-mail enviado pelo Firebase App Distribution e toque no link Começar. Abra o link no Safari.
2. Agora você está no app da Web do testador do App Distribution. Na página que aparece, faça login com sua Conta do Google e toque em Aceitar convite.

3. Agora você pode conferir as versões para as quais recebeu convites. Toque em Registrar dispositivo em uma das versões.

4. Quando solicitado, faça o download do perfil do Firebase e instale-o no app Configurações.

A instalação do perfil concede ao Firebase permissão para:

• Registre o dispositivo de teste coletando o ID exclusivo do dispositivo (UDID).

O Firebase envia um e-mail a todos os proprietários e editores do projeto do Firebase que inclui o UDID do dispositivo de teste.

• Instale um clipe da Web na tela inicial do dispositivo de teste. O clipe da Web abre o app da Web do App Distribution Tester, que permite instalar e acessar todos os seus apps de teste.

No app da Web do testador do App Distribution, o dispositivo de teste agora está registrado para a versão do app.

Observação:se você já adicionou esse dispositivo à sua conta de desenvolvedor, ele pode já ter sido incluído no perfil de provisionamento, e você já vai encontrar um botão "Download" aqui.

Agora que você compartilhou o UDID do dispositivo de teste com o Firebase, pode retomar o desenvolvimento. Na guia Testadores do painel do App Distribution, as informações do testador agora aparecem na versão do app com o status "Aceito":

Na próxima seção, você vai adicionar o UDID do dispositivo ao perfil de provisionamento do app e criar uma versão que funcione com o dispositivo de teste.

Exportar os UDIDs do dispositivo de teste

Como desenvolvedor, você vai receber um e-mail do Firebase com o UDID do dispositivo de teste. Como opção, a distribuição de apps facilita a coleta de vários novos UDIDs de dispositivos de uma só vez, permitindo que você os exporte diretamente do console do Firebase como um arquivo de texto bruto.

1. Para exportar todos os UDIDs, abra a guia Testadores e grupos.

2. Clique em Exportar UDIDs da Apple.

O arquivo precisa conter o UDID do dispositivo de teste.

Device ID            Device Name                            Device Platform
1234567890     [e-mail] - iPhone SE 2nd Gen        ios

Os UDIDs também podem ser exportados da linha de comando usando a fastlane, que você vai fazer na próxima seção.

6. Atualizar e recriar o perfil de provisionamento do app

Agora, adicione o UDID do dispositivo de teste ao perfil de provisionamento do app, recrie uma versão do app que funcione no dispositivo e distribua a nova versão.

Adicionar a faixa de exportação de UDID

1. Adicione outra variável na parte de cima do arquivo Fastfile e defina um caminho de arquivo para fazer o download dos UDIDs dos dispositivos dos testadores.

firebase_app_id = "<your Firebase app ID>"
app_testers = [
  "[e-mail]",
  "[e-mail]",
]
tester_udids_file = "tester_udids.txt"

2. Configure uma nova faixa que use a ação de exportação de UDID do plug-in de distribuição de apps para fazer o download dos UDIDs do testador, assim como você fez no console.

lane :download_udids do
    firebase_app_distribution_get_udids(
        app: firebase_app_id,
        output_file: tester_udids_file,
    )
end

3. Execute a faixa a seguir para fazer o download dos UDIDs.

$ fastlane download_udids

4. Imprima o arquivo transferido por download, que deve conter os UDIDs do dispositivo de teste.

$ cat tester_udids.txt

Adicionar dispositivos ao Apple Developer Console

1. Crie a seguinte faixa para adicionar os UDIDs à lista de dispositivos no Apple Developer Console e, em seguida, ao perfil de provisionamento usando a ação fastlane register_devices:

lane :add_new_devices do
    register_devices(devices_file: tester_udids_file)
end

2. Em seguida, execute a faixa:

$ fastlane add_new_devices

Os novos dispositivos vão aparecer na lista de dispositivos do console do desenvolvedor.

Adicionar dispositivos ao perfil de provisionamento

1. Adicione o argumento force à etapa do perfil de provisionamento na faixa build para forçar a seleção de novos dispositivos sempre que você criar.

lane :build do
    get_certificates()
    get_provisioning_profile(adhoc: true, force: true)
    build_app(export_method: "ad-hoc")
end

Refazer a execução da faixa para criar e fazer upload

Agora, você vai atualizar a faixa distribute com as novas faixas para adicionar os dispositivos ao perfil de provisionamento, recriar o app e distribuí-lo.

1. Chame as novas faixas de distribute:

lane :distribute do
    download_udids
    add_new_devices
    build
    firebase_app_distribution(
        app: "1:123456789:ios:abcd1234",
        release_notes: "Try out this app!"
        testers: app_testers.join(","),
    )
end

2. Execute a faixa distribute:

$ fastlane distribute

Neste ponto, seu Fastfile vai ficar assim:

firebase_app_id = "<your Firebase app ID>"
app_testers = [
  "[e-mail]",
  "[e-mail]",
]
tester_udids_file = "tester_udids.txt"

default_platform(:ios)

lane :build do
    get_certificates()
    get_provisioning_profile(adhoc: true, force: true)
    build_app(export_method: "ad-hoc")
end

lane :distribute do
    download_udids
    add_new_devices
    build
    firebase_app_distribution(
        app: firebase_app_id,
        release_notes: "Try out this app!",
        testers: app_testers.join(","),
    )
end

lane :download_udids do
    firebase_app_distribution_get_udids(
        app: firebase_app_id,
        output_file: tester_udids_file,
    )
end

lane :add_new_devices do
    register_devices(devices_file: tester_udids_file)
end

Fazer o download da versão do dispositivo de teste

Agora que o app inclui os UDIDs do dispositivo de teste, eles podem ser instalados nos dispositivos de teste.

1. No dispositivo de teste, volte ao app da Web do testador do App Distribution usando o link no e-mail ou o ícone na tela inicial do dispositivo.

Ao navegar até o app do codelab do UDID, você vai notar que a versão está pronta para download.

2. Se você estiver em um dispositivo físico, clique em "Fazer o download", depois instale e execute o app.

Observação:os downloads de lançamentos só funcionam em dispositivos físicos. Se você estiver em um simulador, o download não vai funcionar, mas ainda é possível verificar se a configuração funcionou verificando se o botão "Download" aparece no app da Web do Testador de distribuição de apps.

7. Parabéns

Agora você configurou o App Distribution e o fastlane para automatizar o processo de teste de pré-lançamento. Agora, quando você quiser convidar outros testadores ou adicionar os UDIDs deles ao app, basta executar um comando: fastlane distribute.

Não é mais necessário coletar UDIDs individualmente dos testadores nem acessar o Apple Developer Console para atualizar listas de dispositivos ou perfis de provisionamento. Você nem precisa abrir o XCode.

Esse fluxo de trabalho é fácil de configurar para execução a cada hora ou dia no seu ambiente de integração contínua.

Leitura adicional

• Conheça os recursos do Firebase App Distribution, incluindo o SDK no app para iOS.
• Saiba mais sobre o fastlane
• Gerenciar a assinatura de código da sua equipe com o match
• Integrar o fastlane na CI