Personalize seus relatórios de erros do Firebase Crashlytics

Unidade de vibração iOS + Android

No painel do Crashlytics, você pode clicar em um problema e obter um relatório detalhado do evento. Você pode personalizar esses relatórios para ajudar a entender melhor o que está acontecendo no seu aplicativo e as circunstâncias dos eventos relatados ao Crashlytics.

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

• Instrumente seu aplicativo para registrar chaves personalizadas , mensagens de log personalizadas e identificadores de usuário .

• Obtenha registros de localização atual automaticamente se seu aplicativo usar o SDK do Firebase para Google Analytics. Esses registros fornecem visibilidade das ações do usuário que levaram a um evento coletado pelo Crashlytics no seu aplicativo.

• Desative o relatório automático de falhas e ative o relatório opcional para seus usuários. Observe que, por padrão, o Crashlytics coleta automaticamente relatórios de falhas nativos da plataforma para todos os usuários do seu aplicativo.

Observação: para aplicativos Flutter, os relatórios fatais são enviados ao Crashlytics em tempo real, sem a necessidade do usuário reiniciar o aplicativo. Os relatórios não fatais são gravados no disco para serem enviados junto com o próximo relatório fatal ou quando o aplicativo for reiniciado.

Relatar exceções não detectadas

Você pode capturar automaticamente todos os erros "fatais" gerados na estrutura Flutter, substituindo FlutterError.onError por FirebaseCrashlytics.instance.recordFlutterFatalError . Como alternativa, para capturar também 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 detectados pela estrutura Flutter:

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

Para detectar esses erros, você pode usar o manipulador 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 fora do Flutter

Para capturar erros que acontecem fora do contexto do Flutter, instale um ouvinte de erro 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);

Relatar exceções capturadas

Além de relatar automaticamente as falhas do seu aplicativo, o Crashlytics permite registrar exceções não fatais e enviá-las a você na próxima vez que um evento fatal for relatado ou quando o aplicativo for reiniciado.

Observação: o Crashlytics armazena apenas as oito exceções não fatais registradas mais recentes. Se seu aplicativo lançar mais de oito, as exceções mais antigas serão perdidas. Essa contagem é redefinida sempre que uma exceção fatal é lançada, pois 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 seu aplicativo. Por exemplo:

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

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

Você também pode registrar mais informações sobre o erro, o que é possível 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 desejar incluir um valor exclusivo (por exemplo, um ID de usuário ou um carimbo de data/hora) em sua 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 obtém em caso de falhas, além de detalhamentos por versão e dispositivo de hardware.

O Crashlytics processa exceções em um thread de segundo plano dedicado para minimizar o impacto no desempenho do seu aplicativo. Para reduzir o tráfego de rede dos seus usuários, o Crashlytics limitará a taxa do número de relatórios enviados para fora do dispositivo, se necessário.

Adicione chaves personalizadas

As chaves personalizadas ajudam você a obter o estado específico do seu aplicativo que levou a uma falha. Você pode associar pares chave/valor arbitrários aos seus relatórios de falhas e, em seguida, usar as chaves personalizadas para pesquisar e filtrar relatórios de falhas no Console do Firebase.

• No painel do Crashlytics , você pode pesquisar problemas que correspondam a uma chave personalizada.

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

Observação: o Crashlytics oferece suporte a no máximo 64 pares de chave/valor. Depois de atingir esse limite, os valores adicionais não serão salvos. Cada par chave/valor pode ter até 1 KB de tamanho.

Use o método de instância setCustomKey para configurar pares chave/valor. aqui estão 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);

Adicione mensagens de log personalizadas

Para ter mais contexto sobre os eventos que levaram a uma falha, você pode adicionar registros personalizados do Crashlytics ao seu aplicativo. O Crashlytics associa os registros aos dados de falhas e os exibe no console do Firebase , na guia Registros do Crashlytics.

Observação: para evitar lentidão no aplicativo, 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. Por exemplo:

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

Definir identificadores de usuário

Para diagnosticar um problema, muitas vezes é útil saber quais dos seus usuários sofreram uma determinada falha. O Crashlytics inclui uma maneira de identificar usuários anonimamente em seus relatórios de falhas.

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

FirebaseCrashlytics.instance.setUserIdentifier("12345");

Se você precisar limpar um identificador de usuário depois de defini-lo, redefina o valor para uma sequência em branco. Limpar um identificador de usuário não remove os registros existentes do Crashlytics. Se você precisar excluir registros associados a um ID de usuário, entre em contato com o suporte do Firebase .

Obtenha registros de localização atual

Os registros de localização atual fornecem uma melhor compreensão das interações que um usuário teve com seu aplicativo, levando a um evento de falha, não fatal ou ANR. Esses logs podem ser úteis ao tentar reproduzir e depurar um problema.

Os registros de navegação estrutural são desenvolvidos pelo Google Analytics. Portanto, para obtê-los, você precisa ativar o Google Analytics para seu projeto do Firebase e adicionar o SDK do Firebase para Google Analytics ao seu aplicativo. Depois que esses requisitos forem atendidos, os logs de navegação serão automaticamente incluídos nos dados de um evento na guia Logs quando você visualizar os detalhes de um problema.

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

Os logs de localização atual também são preenchidos com quaisquer 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.

Observe que você pode controlar a coleta e o uso de dados do Google Analytics , que incluem os dados que preenchem os registros de localização atual.

Ativar relatórios de aceitação

Por padrão, o Crashlytics coleta automaticamente relatórios de erros de todos os usuários do seu aplicativo. Para dar aos usuários mais controle sobre os dados que enviam, você pode ativar os relatórios de aceitação desativando os relatórios automáticos e enviando dados ao Crashlytics apenas quando desejar em seu código:

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

   Plataformas Apple

   Adicione uma nova chave ao seu arquivo Info.plist :

   • Chave: FirebaseCrashlyticsCollectionEnabled
   • Valor: false

   Android

   No bloco de 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. Habilite a coleta para usuários selecionados chamando a substituição da coleta de dados do Crashlytics em tempo de execução.

   O valor de substituição persiste durante as inicializações do seu aplicativo para que o Crashlytics possa coletar relatórios automaticamente. Para cancelar o relatório automático de falhas, passe false como o valor de substituição. Quando definido como false , o novo valor não se aplica até a próxima execução do aplicativo.

   FirebaseCrashlytics.instance.setCrashlyticsCollectionEnabled(true);
   

Observação: quando a coleta de dados estiver desativada, o Crashlytics armazenará informações de falhas localmente no dispositivo. Se a coleta de dados for ativada posteriormente, qualquer informação de falha armazenada no dispositivo será enviada ao Crashlytics para processamento.

Gerenciar dados do Crash Insights

O Crash Insights ajuda a resolver problemas comparando seus rastreamentos de pilha anônimos com rastreamentos de outros aplicativos do Firebase e informando se o problema faz parte de uma tendência maior. Para muitos problemas, o Crash Insights ainda fornece recursos para ajudá-lo a depurar a falha.

Crash Insights usa dados agregados de falhas para identificar tendências comuns de estabilidade. Se preferir não compartilhar os dados do seu aplicativo, você pode desativar o Crash Insights no menu Crash Insights, na parte superior da lista de problemas do Crashlytics no console do Firebase .

Observação: desabilitar o compartilhamento de dados também remove insights sobre seus problemas. As alterações podem levar até 24 horas para entrar em vigor.