Personalizar relatórios de erros do Firebase Crashlytics

iOS Android Flutter Unity

Veja neste guia como personalizar seus relatórios de erros usando o SDK do Firebase Crashlytics. Por padrão, o Crashlytics coleta automaticamente relatórios de erros para todos os usuários do seu app. Se quiser, desative os relatórios de falhas automáticos e ative os relatórios de permissão para os usuários. O Crashlytics oferece quatro mecanismos de geração de registros prontos para uso: chaves personalizadas, registros personalizados, identificadores de usuários e exceções capturadas.

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. Observe que setCustomKey está sobrecarregado para o parâmetro value para aceitar qualquer argumento primitivo ou String. Veja alguns exemplos:

val crashlytics = Firebase.crashlytics
crashlytics.setCustomKeys {
    key("my_string_key", "foo") // String value
    key("my_bool_key", true)    // boolean value
    key("my_double_key", 1.0)   // double value
    key("my_float_key", 1.0f)   // float value
    key("my_int_key", 1)        // int value
}

FirebaseCrashlytics crashlytics = FirebaseCrashlytics.getInstance();

crashlytics.setCustomKey("my_string_key", "foo" /* string value */);

crashlytics.setCustomKey("my_bool_key", true /* boolean value */);

crashlytics.setCustomKey("my_double_key", 1.0 /* double value */);

crashlytics.setCustomKey("my_float_key", 1.0f /* float value */);

crashlytics.setCustomKey("my_int_key", 1 /* int value */);

Para modificar o valor de uma chave atual, chame a chave e defina-a com um valor diferente. Exemplo:

val crashlytics = Firebase.crashlytics
crashlytics.setCustomKeys {
    key("current_level", 3)
    key("last_UI_action", "logged_in")
}

FirebaseCrashlytics crashlytics = FirebaseCrashlytics.getInstance();

crashlytics.setCustomKey("current_level", 3);
crashlytics.setCustomKey("last_UI_action", "logged_in");

Adicione pares de chave-valor em massa transmitindo uma instância de CustomKeysAndValues para o método de instância setCustomKeys:

crashlytics.setCustomKeys {
  key("str_key", "hello")
  key("bool_key", true)
  key("int_key", 1)
  key("long_key", 1L)
  key("float_key", 1.0f)
  key("double_key", 1.0)
}

CustomKeysAndValues keysAndValues = new CustomKeysAndValues.Builder()
.putString("string key", "string value")
.putString("string key 2", "string  value 2")
.putBoolean("boolean key", True)
.putBoolean("boolean key 2", False)
.putFloat("float key", 1.01)
.putFloat("float key 2", 2.02)
.build();

FirebaseCrashlytics.getInstance().setCustomKeys(keysAndValues);

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 os exibe na página do Crashlytics do Console do Firebase, na guia Registros.

Use log para ajudar a identificar problemas. Exemplo:

Firebase.crashlytics.log("message")

FirebaseCrashlytics.getInstance().log("message");

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:

Firebase.crashlytics.setUserId("user123456789")

FirebaseCrashlytics.getInstance().setUserId("user123456789");

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.

(Somente Android NDK) Adicionar metadados aos relatórios de erros do NDK

Como opção, é possível incluir o cabeçalho crashlytics.h no código em C++ para adicionar metadados aos relatórios de erros do NDK, como chaves personalizadas, registros personalizados e identificadores de usuários. Todas essas opções estão descritas nesta página acima.

crashlytics.h está disponível como uma biblioteca de C++ somente de cabeçalho no Repositório do GitHub do SDK do Firebase para Android.

Leia os comentários no arquivo de cabeçalho para saber como usar as APIs de C++ do NDK.

Incluir relatórios do GWP-ASan para depurar problemas de corrupção de memória

O Crashlytics pode ajudar a depurar falhas causadas por erros de memória nativa coletando relatórios do GWP-ASan. Esses erros relacionados à memória podem ser associados à corrupção da memória no seu app, que é a principal causa de vulnerabilidades de segurança.

• É possível visualizar esses dados em uma nova guia "Stack traces da memória" ao clicar nos detalhes de um problema no painel do Crashlytics.

• Também é possível usar o novo sinal "Relatório do GWP-Asan" e filtrar para ter acesso rapidamente a todos os problemas com esses dados.

Você pode gerar relatórios de memória do GWP-ASan se ativar explicitamente o GWP-ASan no seu app e usar o SDK do Crashlytics para NDK v18.3.6+ (BoM do Firebase v31.3.0 ou superior). É possível testar a configuração do GWP-ASan usando o exemplo de código nativo na documentação do Android.

Reportar exceções não fatais

Além de reportar automaticamente as falhas do seu app, o Crashlytics permite registrar exceções não fatais e enviá-las para você na próxima vez que o app for iniciado.

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

try {
    methodThatThrows()
} catch (e: Exception) {
    Firebase.crashlytics.recordException(e)
    // handle your exception here
}

try {
    methodThatThrows();
} catch (Exception e) {
    FirebaseCrashlytics.getInstance().recordException(e);
    // handle your exception here
}

Todas as exceções registradas 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 Android e 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 Crashlytics agrupa exceções registradas e as envia na próxima vez que o app for iniciado.

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. 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 consegue 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.

   Kotlin+KTX

   Firebase.crashlytics.setCrashlyticsCollectionEnabled(true)

   Java

   FirebaseCrashlytics.getInstance().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.