Firebase Crashlytics e o Flutter Casual Games Toolkit

Aprenda a ativar o Crashlytics no exemplo de jogos do Flutter para facilitar a detecção e a correção de problemas no seu jogo

O Flutter Casual Games Toolkit (FCGT) é um template inicial para desenvolvedores que querem criar um app de jogo mobile. Ele já vem personalizado com um menu principal, níveis de jogo, uma tela de configurações, efeitos sonoros, músicas e mais. Além do template do app, você também pode baixar um app TicTacToe baseado nesse template.

As capturas de tela a seguir mostram a tela principal padrão, a página de níveis do jogo e uma página de configurações, nessa ordem:

Capturas de tela das principais telas do FCGT
Capturas de tela das principais telas do FCGT

O FCGT inclui integrações com alguns serviços úteis para desenvolver o seu próprio jogo: Apple Game Center, Google Play Games Services, Google Mobile Ads SDK e o pacote In-App Purchase. Essas integrações mais avançadas vêm inicialmente desativadas porque exigem alguma configuração sua, como desenvolvedor, antes de poderem ser usadas. Se você der uma olhada no main.dart arquivo do template de jogo no GitHub e rolar até o primeiro “TODO”, verá o código dos plugins de Anúncios, Games Services e Compras In-App, inativo e esperando para ser ativado.

Código de Anúncios, Games Services e Compras In-App desativado
Código de Anúncios, Games Services e Compras In-App desativado

O FCGT também inclui o Firebase Crashlytics, uma poderosa solução de relatórios de falhas que ajuda você a detectar, rastrear, priorizar e corrigir problemas em tempo real. O painel do Crashlytics permite visualizar problemas no seu código, ver quantos usuários são afetados e descobrir quais linhas de código estão causando esses problemas.

Painel do Firebase Crashlytics
Painel do Firebase Crashlytics

Em seu estado inicial, sem o Crashlytics ativado, o código do arquivo crashlytics/crashlytics.dart coleta mensagens de erro, logs e stack traces e os grava no console. Essas informações só ficam disponíveis ao testar em dispositivos de desenvolvimento locais. Com o Crashlytics ativado, você pode receber dados de usuários executando o seu código de produção nos próprios dispositivos e visualizá-los no painel do Crashlytics.

Este artigo mostra como ativar o Firebase Crashlytics no FCGT, lançar algumas exceções de teste e demonstrar como essas exceções aparecem no painel do Crashlytics. Se você tem interesse em usar o Crashlytics no seu app Flutter, mas não quer usar o FCGT para desenvolver um jogo, as informações sobre lançar exceções e sobre o painel do Crashlytics se aplicam a qualquer app hospedado no Firebase.

No topo do main.dart file, você pode ver o código da integração com o Crashlytics:

main.dart: código do Firebase Crashlytics desativado
main.dart: código do Firebase Crashlytics desativado

Esse código do Firebase Crashlytics não estava incluído no tutorial original do FCGT no YouTube, Início rápido para criar um jogo em Flutter — esse código será explicado em breve.

Os passos para ativar o Crashlytics no FCGT estão listados na seção do Crashlytics no arquivo do FCGT README.md, mas continue lendo para acompanhar um passo a passo de cada etapa e uma demonstração de como as coisas aparecem no painel do Crashlytics.

Para começar, siga as instruções a seguir:

  1. Baixe uma cópia da versão mais recente do template de jogo na página do projeto Flutter no GitHub.

  2. Certifique-se de que o Flutter está instalado no seu computador e de que você consegue executar apps no iOS Simulator ou no Android Emulator. Se tiver dúvidas sobre como fazer isso, consulte o guia Começar com o Flutter para a sua plataforma de destino.

  3. Abra a pasta do template de jogo no seu IDE ou terminal e atualize para a versão mais recente do Flutter:

bash
$> flutter upgrade
  1. Selecione o dispositivo ou simulador onde você quer executar o app:

  2. Execute o app:

bash
$> flutter run

Se tudo correr bem, o app será iniciado e você verá a tela inicial:

Tela inicial do template de jogo
Tela inicial do template de jogo

O FCGT foi projetado para oferecer aos desenvolvedores uma base rápida e confortável para criar jogos. Enquanto o app estiver rodando, navegue e veja o que ele pode fazer. Você logo vai notar que a “jogabilidade” do FCGT não é a parte mais empolgante (a menos que você seja fã de sliders). A estrutura simples do código do jogo é uma escolha de design deliberada para manter as coisas simples quando você começar a escrever o seu próprio jogo.

Jogabilidade do FCGT
Jogabilidade do FCGT

Agora que você tem o código, acesse o site do Firebase e crie uma conta gratuita (caso ainda não tenha uma). Depois, abra o console do Firebase e clique em Adicionar projeto. A partir daí, criar um novo projeto é um processo de 3 etapas; basta seguir as instruções na tela. Você será perguntado se deseja ativar o Google Analytics (GA). Recomendamos ativar o Google Analytics porque, além de ser gratuito, ele libera algumas funcionalidades de análise poderosas, como dados de usuários sem falhas, trilhas de navegação da sessão, alertas de Velocity e integração com o BigQuery.

Se você ativou o Google Analytics, instale o plugin do Google Analytics para Flutter usando o seguinte comando:

bash
$> flutter pub add firebase_analytics

Para saber mais, consulte os passos 1 e 2 do guia Use o Google Analytics para obter métricas dos relatórios de falhas, mas não é preciso seguir os passos adicionais descritos nele, pois eles são abordados a seguir.

Em seguida, instale a Firebase CLI. Acesse a documentação da Firebase CLI, selecione seu sistema operacional e siga as instruções. Depois de fazer login, execute o seguinte comando no terminal e ele deverá exibir uma lista com os nomes dos projetos Firebase:

bash
$> firebase projects:list

Agora, instale a FlutterFire CLI, que depende da Firebase CLI, então não confunda esses passos. Para isso, siga as instruções de instalação da CLI do FlutterFire.

Usando o terminal, acesse a pasta raiz do projeto do template de jogo. Você saberá que está no diretório certo se conseguir ver o arquivo pubspec.yaml.

Agora execute este comando:

bash
$> flutterfire configure

Selecione o nome do projeto Firebase que você criou antes. Em seguida, selecione quais plataformas de destino o seu app oferece suporte. Atualmente, o console do Crashlytics só oferece suporte a iOS e Android, então selecione essas duas, no máximo.

Saída do comando de configuração do FlutterFire
Saída do comando de configuração do FlutterFire

A FlutterFire CLI gera todas as chaves e IDs de cliente necessários para se conectar ao Firebase e os sobrescreve no arquivo src/firebase_options.dart. Se você adicionar mais plugins ou quiser ativar mais plataformas no futuro, basta executar novamente o comando flutterfire configure.

Para ativar o Crashlytics, volte ao arquivo lib/main.dart e descomente o código do Crashlytics. No topo do arquivo, há 3 instruções import que também precisam ser descomentadas:

Instruções import do Crashlytics descomentadas
Instruções import do Crashlytics descomentadas

Depois, mais abaixo no mesmo arquivo, descomente o código de integração do Crashlytics que você viu antes. Esse código inicializa uma instância do Crashlytics caso ela ainda não exista e, em seguida, verifica se o app está rodando no Android ou no iOS. O código do Crashlytics não será executado se o app estiver rodando no desktop ou na web, porque o painel do Crashlytics ainda não oferece suporte a essas plataformas.

Código de integração do Crashlytics
Código de integração do Crashlytics

Depois de descomentar o código de integração do Crashlytics, use o comando flutter run para executar o app novamente e confirmar que tudo ainda funciona.

Hora de fazer seu app travar!

Na verdade, você vai lançar apenas algumas exceções de teste, mas também vai aprender a localizá-las no painel do Crashlytics. Isso é útil porque uma exceção não tratada pode não fazer o app travar, mas ainda assim causar uma má experiência do usuário e, sem o Crashlytics ativado, pode passar despercebida. As APIs de erro fatal do Crashlytics usadas no arquivo crashlytics/crashlytics.dart registram exceções não tratadas como eventos fatais, para que apareçam no painel do Crashlytics e possam ser priorizadas corretamente.

API de erro fatal do Crashlytics
API de erro fatal do Crashlytics

Para saber mais sobre como esse registro é implementado, consulte o guia sobre como personalizar os relatórios de falhas do Firebase Crashlytics e leia os comentários no arquivo crashlytics.dart.

No editor de texto ou IDE de sua preferência, acesse a pasta main_menu e abra o arquivo main_menu_screen.dart. Role a tela até encontrar o código do botão Settings.

Antes (código original)
Antes (código original)

Faça uma cópia do ElevatedButton e, dentro do onPressed (callback), em vez de chamar GoRouter para navegar até a página Settings, lance uma exceção. Enquanto estiver lá, mude o nome do botão para algo como Throw Test Exception, conforme mostrado abaixo:

dart
ElevatedButton(
  onPressed: () => GoRouter.of(context).go('/settings'),
  child: const Text('Settings'),
),
_gap,
ElevatedButton(
  onPressed: () => throw Exception(),
  child: const Text("Throw Test Exception"),
),

Em seguida, acesse a pasta audio e abra o arquivo audio_controller.dart. Role a tela até encontrar a função _musicOnHandler. O framework chama essa função quando o usuário ativa ou desativa a reprodução de música na tela Settings.

Antes (código original)
Antes (código original)

Dentro da instrução else, abaixo de onde a função _stopMusic() é chamada, use o método _log.severe() para gravar uma mensagem no console. Qualquer mensagem de log com nível Level.severe ou acima é enviada ao Crashlytics, então essa mensagem também vai aparecer no console do Crashlytics. Para fins de demonstração, lance também outra exceção aqui:

dart
void _musicOnHandler() {
  if (_settings!.musicOn.value) {
    // Music got turned on.
    if (!_settings!.muted.value) {
      _resumeMusic();
    }
  } else {
    // Music got turned off.
    _stopMusic();
    _log.severe("Someone is messing with the music!");
    throw Exception();
  }
}

Agora há dois lugares no app onde você pode clicar em um botão e lançar uma exceção. Execute o app novamente e verifique se há um botão Throw Test Exception no menu principal.

Menu principal com o botão de lançar exceção
Menu principal com o botão de lançar exceção

Clicar no botão Throw Test Exception gera um stack trace completo do momento em que a exceção foi lançada e o grava no console:

Saída do console depois que uma exceção foi lançada
Saída do console depois que uma exceção foi lançada

Se você clicar em Settings para abrir a tela de configurações e depois tocar algumas vezes no botão da nota musical, mais exceções e stack traces vão aparecer no seu console. Agora que você tem o Crashlytics ativado, esses dados ficam disponíveis no painel do Crashlytics.

Abra o console do Firebase, selecione seu projeto e, depois, selecione Crashlytics no menu à esquerda. Escolha a versão do projeto que você está executando (Android ou iOS) e você deverá conseguir ver o painel do Crashlytics.

Painel do Firebase Crashlytics
Painel do Firebase Crashlytics

Se, depois de alguns minutos, tudo o que você vir ao acessar o painel do Crashlytics for este personagem girando em volta de bugs, provavelmente é porque o Crashlytics ainda não detectou nenhum evento. Nesse caso, pare a execução do seu app e depois volte para o seu dispositivo ou simulador, feche o app e inicie-o novamente tocando no ícone do app. Agora, tente lançar algumas exceções no app e verifique o painel do Crashlytics de novo. Se você atualizou o console do Firebase, reiniciou o app manualmente e ainda não vê o crash de teste depois de cinco minutos, ative o log de depuração para ver se o seu app está enviando relatórios de crash.

Nenhum evento detectado pelo Crashlytics ainda
Nenhum evento detectado pelo Crashlytics ainda

Se você ativou o Google Analytics, o painel de estatísticas de livre de crashes mostrará a porcentagem de usuários que não sofreram um crash durante o intervalo de tempo selecionado.

Painel de estatísticas sem crashes do painel do Crashlytics
Painel de estatísticas sem crashes do painel do Crashlytics

A tabela Issues, na parte inferior do painel do Crashlytics, exibe as exceções lançadas.

Tabela de issues do painel do Crashlytics
Tabela de issues do painel do Crashlytics

Clicar em um issue específico na tabela mostra um card para cada vez que o issue ocorreu, junto com informações mais detalhadas sobre ele. Por padrão, o stack trace é exibido, o que permite identificar em qual parte do seu código o crash aconteceu. Como você pode ver na captura de tela abaixo, a exceção foi lançada na função _musicOnHandler(), na linha 197 do arquivo audio_controller.dart. Isso não é surpresa, porque é exatamente onde você colocou essa exceção no código, mas imagine como isso é útil para rastrear problemas em apps de produção complexos.

Stack trace do painel do Crashlytics
Stack trace do painel do Crashlytics

Se você clicar na aba Logs, poderá ver todas as mensagens escritas no console pelo método _log.severe():

Logs do painel do Crashlytics
Logs do painel do Crashlytics

Parabéns!! Agora, quando você for escrever um jogo premiado (talvez com muitos sliders), terá o Crashlytics ativado para ajudar a encontrar e corrigir qualquer problema.

Mais do Flutter