Este guia descreve como personalizar os relatórios de erros usando as APIs do Crashlytics. Por padrão, o Crashlytics coleta automaticamente relatórios de erros nativos da plataforma para todos os usuários do seu app. Também é possível desativar os relatórios de falhas automáticos e ativar os relatórios de permissão para os usuários. O Crashlytics oferece cinco mecanismos de geração de registros prontos para uso: chaves personalizadas, registros personalizados, identificadores de usuários e exceções detectadas e não detectadas.
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.
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'],
);
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).
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.
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.
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:
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 arquivoAndroidManifest.xml
, adicione uma tagmeta-data
para desativar a coleta automática:<meta-data android:name="firebase_crashlytics_collection_enabled" android:value="false" />
- Chave:
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 comofalse
, o novo valor não se aplica até a próxima execução do app.FirebaseCrashlytics.instance.setCrashlyticsCollectionEnabled(true);
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.