Começar a usar o Firebase Crashlytics

Neste guia de início rápido, descrevemos como configurar o Firebase Crashlytics no seu app com o plug-in do Flutter do Crashlytics para que você receba relatórios de erros abrangentes no Console do Firebase.

A configuração do Crashlytics envolve o uso de uma ferramenta de linha de comando e do ambiente de desenvolvimento integrado. Para concluir a configuração, será necessário forçar uma exceção de teste para enviar seu primeiro relatório de erros ao Firebase.

Antes de começar

  1. Configure e inicialize o Firebase no seu projeto criado com o Flutter, caso ainda não tenha feito isso.

  2. Recomendado: para gerar automaticamente registros de navegação estrutural e entender as ações do usuário que levam a uma falha, um evento não fatal ou um ANR, você precisa para ativar o Google Analytics no seu projeto do Firebase.

    • Caso seu projeto do Firebase não tenha o Google Analytics ativado, faça a ativação na guia Integrações das suas > Configurações do projeto no Console do Firebase.

    • Se estiver criando um novo projeto do Firebase, ative o Google Analytics durante o fluxo de trabalho de criação do projeto.

    Os registros de navegação estrutural estão disponíveis para todas as plataformas Android e Apple compatíveis com o Crashlytics (exceto o watchOS).

Etapa 1: adicionar o Crashlytics ao seu projeto do Flutter

  1. Na raiz do seu projeto do Flutter, execute o seguinte comando para instalar o plug-in do Flutter para o Crashlytics.

    Para aproveitar os registros de navegação estrutural, adicione também o plug-in do Flutter para o Google Analytics ao seu app. Verifique se o Google Analytics está ativado no seu projeto do Firebase.

    flutter pub add firebase_crashlytics && flutter pub add firebase_analytics

  2. No diretório raiz do projeto do Flutter, execute o seguinte comando:

    flutterfire configure

    A execução desse comando garante que a configuração do Firebase do seu app Flutter está atualizada e, no Android, adiciona o plug-in Gradle do Crashlytics necessário ao app.

  3. Após a conclusão, recrie seu projeto do Flutter:

    flutter run

  4. (Opcional) Se o projeto do Flutter usa a flag --split-debug-info (e, opcionalmente, também a flag --obfuscate), outras etapas são necessárias para mostrar stack traces legíveis para seus aplicativos.

    • Plataformas Apple: verifique se o projeto está usando a configuração de versão recomendada (Flutter 3.12.0+ e plug-in do Flutter do Crashlytics 3.3.4+) para que ele possa gerar e fazer upload automaticamente de símbolos do Flutter (arquivos dSYM) para o Crashlytics.

    • Android: use a Firebase CLI (v.11.9.0+) para fazer upload de símbolos de depuração do Flutter. Você precisa fazer upload dos símbolos de depuração antes de relatar uma falha de um build de código ofuscado.

      No diretório raiz do projeto do Flutter, execute o seguinte comando:

      firebase crashlytics:symbols:upload --app=FIREBASE_APP_ID PATH/TO/symbols

      • FIREBASE_APP_ID: seu ID do app Android do Firebase (não o nome do pacote)
        Exemplo de ID do app Android do Firebase: 1:567383003300:android:17104a2ced0c9b9b

      • PATH/TO/symbols: o mesmo diretório que você passa para a flag --split-debug-info ao criar o aplicativo.

Etapa 2: configurar gerenciadores de falhas

Você pode capturar automaticamente todos os erros gerados no framework do Flutter substituindo FlutterError.onError por FirebaseCrashlytics.instance.recordFlutterFatalError:

void main() async {
  WidgetsFlutterBinding.ensureInitialized();

  await Firebase.initializeApp();

  // Pass all uncaught "fatal" errors from the framework to Crashlytics
  FlutterError.onError = FirebaseCrashlytics.instance.recordFlutterFatalError;

  runApp(MyApp());
}

Para detectar erros assíncronos que não são processados pelo framework do Flutter, use PlatformDispatcher.instance.onError:

Future<void> main() async {
    WidgetsFlutterBinding.ensureInitialized();
    await Firebase.initializeApp();
    FlutterError.onError = (errorDetails) {
      FirebaseCrashlytics.instance.recordFlutterFatalError(errorDetails);
    };
    // Pass all uncaught asynchronous errors that aren't handled by the Flutter framework to Crashlytics
    PlatformDispatcher.instance.onError = (error, stack) {
      FirebaseCrashlytics.instance.recordError(error, stack, fatal: true);
      return true;
    };
    runApp(MyApp());

}

Para ver exemplos de como lidar com outros tipos de erros, consulte Personalizar relatórios de erros.

Etapa 3: forçar uma falha de teste para concluir a configuração

Para concluir a configuração do Crashlytics e ver os dados iniciais no painel do Console do Firebase, é necessário forçar a geração de uma exceção de teste.

  1. Adicione um código ao app que possa ser usado para forçar a geração de uma exceção de teste.

    Se você adicionou um gerenciador de erros que chama FirebaseCrashlytics.instance.recordError(error, stack, fatal: true) para o Zone de nível superior, é possível usar o código a seguir para adicionar um botão ao seu app que, quando pressionado, gera uma exceção de teste:

    TextButton(
    onPressed: () => throw Exception(),
    child: const Text("Throw Test Exception"),
),

  2. Crie e execute seu app.

  3. Force a geração da exceção de teste para enviar o primeiro relatório do app:

    1. Abra o app no dispositivo ou emulador de teste.

    2. No seu app, pressione o botão de exceção de teste adicionado com o código acima.

  4. Acesse o painel do Crashlytics no Console do Firebase para conferir a falha do teste.

    Se você atualizou o console e ainda não consegue ver a falha de teste após cinco minutos, ative a geração de registros de depuração para ver se o app está enviando relatórios de falha.


Pronto. O Crashlytics agora está monitorando seu app em busca de falhas e, no Android, erros não fatais e ANRs. Acesse o painel do Crashlytics para ver e analisar todos os relatórios e estatísticas.

Próximas etapas