Personalizar relatórios de erros do Firebase Crashlytics

iOS Android Flutter Unity

No painel do Crashlytics, clique em um problema e acesse um relatório de eventos detalhado. É possível personalizar esses relatórios para entender melhor o que está acontecendo no app e as circunstâncias em torno dos eventos informados ao Crashlytics.

• Informe exceções não capturadas e exceções capturadas ao Crashlytics.

• Instrumente o app para registrar chaves personalizadas, mensagens de registro personalizadas e identificadores de usuários.

• Receba automaticamente registros de navegação estrutural se o app usar o SDK do Firebase para Google Analytics. Esses registros permitem visualizar as ações do usuário que levam a um evento coletado pelo Crashlytics no seu app.

• Desative os relatórios automáticos de falhas e ative a permissão para geração de relatórios para seus usuários. Por padrão, o Crashlytics coleta automaticamente relatórios de erros nativos da plataforma para todos os usuários do seu app.

Observação: para apps do Flutter, os relatórios de erros fatais são enviados ao Crashlytics em tempo real, sem que o usuário precise reiniciar o aplicativo. Os relatórios não fatais são gravados no disco para serem enviados com o próximo relatório de erros fatais ou quando o app for reiniciado.

Informar exceções não capturadas

Você pode capturar automaticamente todos os erros "fatais" gerados no framework do Flutter substituindo FlutterError.onError por FirebaseCrashlytics.instance.recordFlutterFatalError. Como alternativa, para também capturar exceções "não fatais", substitua FlutterError.onError por FirebaseCrashlytics.instance.recordFlutterError:

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

  await Firebase.initializeApp();
  bool weWantFatalErrorRecording = true;
  FlutterError.onError = (errorDetails) {
    if(weWantFatalErrorRecording){
      FirebaseCrashlytics.instance.recordFlutterFatalError(errorDetails);
    } else {
      FirebaseCrashlytics.instance.recordFlutterError(errorDetails);
    }
  };

  runApp(MyApp());
}

Erros assíncronos

Erros assíncronos não são capturados pelo framework do Flutter:

ElevatedButton(
  onPressed: () async {
    throw Error();
  }
  ...
)

Para detectar esses erros, use o gerenciador 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());

}

Erros de fora do Flutter

Para detectar erros que acontecem fora do contexto do Flutter, instale um listener de erros no Isolate atual:

Isolate.current.addErrorListener(RawReceivePort((pair) async {
  final List<dynamic> errorAndStacktrace = pair;
  await FirebaseCrashlytics.instance.recordError(
    errorAndStacktrace.first,
    errorAndStacktrace.last,
    fatal: true,
  );
}).sendPort);

Informar exceções capturadas

Além de reportar automaticamente as falhas do seu app, o Crashlytics permite registrar exceções não fatais e enviar elas para você na próxima vez que um evento fatal for relatado ou quando o app for reiniciado.

Observação: o Crashlytics armazena apenas as oito últimas exceções não fatais registradas. Se o app lançar mais de oito, as exceções mais antigas serão perdidas. Essa contagem será redefinida sempre que uma exceção fatal for gerada, já que isso faz com que um relatório seja enviado ao Crashlytics.

Use o método recordError para registrar exceções não fatais nos blocos catch do app. Exemplo:

await FirebaseCrashlytics.instance.recordError(
  error,
  stackTrace,
  reason: 'a non-fatal error'
);

// Or you can use:
await FirebaseCrashlytics.instance.recordFlutterError(errorDetails);

Também é possível registrar mais informações sobre o erro usando a propriedade information:

await FirebaseCrashlytics.instance.recordError(
  error,
  stackTrace,
  reason: 'a non-fatal error',
  information: ['further diagnostic information about the error', 'version 2.0'],
);

Aviso: se você quiser incluir um valor exclusivo (por exemplo, um ID do usuário ou um carimbo de data/hora) na mensagem de exceção, use uma chave personalizada em vez de adicionar o valor diretamente na mensagem de exceção. Adicionar valores diretamente pode resultar em vários problemas e fazer com que o Crashlytics limite os erros de relatório no seu aplicativo.

Essas exceções aparecem como problemas não fatais no Console do Firebase. O resumo do problema contém todas as informações de estado que você normalmente recebe com as falhas, além de detalhamentos por versão do dispositivo de hardware.

O Crashlytics processa exceções em uma linha de execução dedicada em segundo plano para minimizar o impacto no desempenho do app. Para reduzir o tráfego de rede dos usuários, o Crashlytic vai limitar a taxa do número de relatórios enviados do dispositivo, se necessário.

Adicionar chaves personalizadas

As chaves personalizadas ajudam você a chegar ao estado específico do seu aplicativo que está gerando uma falha. É possível associar pares de chave-valor arbitrários aos seus relatórios de erros e usar as chaves personalizadas para pesquisar e filtrar relatórios de erros no Console do Firebase.

• No painel do Crashlytics, é possível pesquisar problemas que correspondam a uma chave personalizada.

• Ao analisar um problema específico no console, você pode ver as chaves personalizadas associadas a cada evento (subguia Chaves) e até mesmo filtrar os eventos por chaves personalizadas (Filtro, na parte de cima da página).

Observação: o Crashlytics aceita no máximo 64 pares de chave-valor. Ao atingir esse limite, os valores adicionais não serão salvos. Cada par de chave-valor pode ter um tamanho de até 1 KB.

Use o método de instância setCustomKey para definir pares de chave-valor. Veja alguns exemplos:

// Set a key to a string.
FirebaseCrashlytics.instance.setCustomKey('str_key', 'hello');

// Set a key to a boolean.
FirebaseCrashlytics.instance.setCustomKey("bool_key", true);

// Set a key to an int.
FirebaseCrashlytics.instance.setCustomKey("int_key", 1);

// Set a key to a long.
FirebaseCrashlytics.instance.setCustomKey("int_key", 1L);

// Set a key to a float.
FirebaseCrashlytics.instance.setCustomKey("float_key", 1.0f);

// Set a key to a double.
FirebaseCrashlytics.instance.setCustomKey("double_key", 1.0);

Adicionar mensagens de registro personalizadas

Para dar mais contexto aos eventos que geram uma falha, adicione registros personalizados do Crashlytics ao seu app. O Crashlytics associa os registros aos dados de falhas e exibe eles no Console do Firebase, na guia Registros do Crashlytics.

Observação: para evitar que o app fique lento, o Crashlytics limita os registros a 64 KB e exclui entradas de registro mais antigas quando os registros de uma sessão ultrapassam esse limite.

Use log para ajudar a identificar problemas. Exemplo:

FirebaseCrashlytics.instance.log("Higgs-Boson detected! Bailing out");

Definir identificadores de usuários

Para diagnosticar um problema, muitas vezes é útil saber quais usuários observaram uma determinada falha. O Crashlytics inclui uma maneira de identificar anonimamente os usuários nos relatórios de erros.

Para adicionar IDs de usuários aos seus relatórios, atribua a cada usuário um identificador exclusivo na forma de um número de ID, token ou valor de hash:

FirebaseCrashlytics.instance.setUserIdentifier("12345");

Se você precisar apagar um identificador de usuário depois de configurá-lo, redefina o valor deixando uma string em branco. Limpar um identificador de usuário não remove os registros atuais do Crashlytics. Se você precisar excluir registros associados a um ID de usuário, entre em contato com o suporte do Firebase.

Acessar registros de navegação estrutural

Os registros de navegação estrutural oferecem uma melhor compreensão das interações de um usuário com seu app que levaram a um evento não fatal, de falha ou de ANR. Esses registros podem ser úteis ao tentar reproduzir e depurar um problema.

Os registros de navegação estrutural usam a tecnologia do Google Analytics. Para receber esses registros, ative o Google Analytics no seu projeto do Firebase e adicione o SDK do Firebase para Google Analytics ao seu app. Quando esses requisitos forem atendidos, os registros de navegação estrutural serão incluídos automaticamente com os dados de um evento na guia Registros quando você visualizar os detalhes de um problema.

O SDK do Analytics registra automaticamente o evento screen_view, o que permite que os registros de navegação estrutural mostrem uma lista de telas visualizadas antes do evento de falha, não fatal ou ANR. Um registro de navegação estrutural screen_view contém um parâmetro firebase_screen_class.

Os registros de navegação estrutural também são preenchidos com todos os eventos personalizados registrados manualmente na sessão do usuário, incluindo os dados de parâmetro do evento. Esses dados podem ajudar a mostrar uma série de ações do usuário que levam a um evento de falha, não fatal ou ANR.

É possível controlar a coleta e o uso de dados do Google Analytics, o que inclui os dados que preenchem os registros de navegação estrutural.

Ative a permissão para geração de relatórios

Por padrão, o Crashlytics coleta automaticamente relatórios de erros para todos os usuários do seu app. Caso queira dar aos usuários mais controle sobre os dados enviados, é possível ativar a geração de relatórios. Para fazer isso, basta desativar a geração automática de relatórios e enviar dados ao Crashlytics somente quando você escolher no seu código:

1. Desative a coleta automática de forma nativa:

   Plataformas da Apple

   Adicione uma nova chave ao arquivo Info.plist:

   • Chave: FirebaseCrashlyticsCollectionEnabled
   • Valor: false

   Android

   No bloco application do arquivo AndroidManifest.xml, adicione uma tag meta-data para desativar a coleta automática:

   <meta-data
       android:name="firebase_crashlytics_collection_enabled"
       android:value="false" />
   

2. Para ativar a coleta nos usuários selecionados, chame a modificação da coleta de dados do Crashlytics no ambiente de execução.

   O valor de modificação continua entre os lançamentos do seu app. Assim, o Crashlytics pode coletar relatórios automaticamente. Para desativar o relatório automático de falhas, transmita false como o valor de modificação. Quando definido como false, o novo valor não se aplica até a próxima execução do app.

   FirebaseCrashlytics.instance.setCrashlyticsCollectionEnabled(true);
   

Observação: quando a coleta de dados é desativada, o Crashlytics armazena informações de falha localmente no dispositivo. Se a coleta de dados for ativada posteriormente, as informações de falhas armazenadas no dispositivo serão enviadas ao Crashlytics para processamento.

Gerenciar dados do Crash Insights

Com o Crash Insights, você soluciona problemas quando compara stack traces anônimos a traces de outros aplicativos do Firebase. Você receberá um aviso se o problema fizer parte de uma tendência maior. Para muitos problemas, o Crash Insights também oferece recursos para ajudar a depurar a falha.

Ele usa dados de falhas agregados para identificar tendências de estabilidade comuns. Caso prefira não compartilhar os dados do app, é possível desativar o Crash Insights no menu com o mesmo nome na parte de cima da lista de problemas do Crashlytics no Console do Firebase.

Observação: desativar o compartilhamento de dados também remove insights sobre seus problemas. As mudanças levam até 24 horas para entrar em vigor.