Fazer upgrade para o SDK do Firebase Crashlytics

Agora, é possível configurar o Crashlytics no seu app usando o novo SDK oficial do Firebase Crashlytics, que oferece APIs aprimoradas que são mais intuitivas e consistentes com outros produtos Firebase.

Neste guia, você verá como fazer upgrade para o novo SDK usando o SDK do Fabric legado. Ele descreve as alterações que acompanham as novas APIs, o motivo das alterações e como atualizar seu código, se necessário.

Antes de começar

O SDK do Firebase Crashlytics usa o AndroidX como uma dependência. Portanto, se seu app usar versões mais antigas da Biblioteca de suporte do aplicativo, primeiro migre o app para o AndroidX.

Etapa 1: adicionar um arquivo de configuração do Firebase

  1. Abra suas Configurações do projeto. No cartão Seus apps, selecione o nome do pacote do app que precisa de um arquivo de configuração.

  2. Clique em Fazer o download do google-services.json para receber o arquivo de configuração do Firebase para Android (google-services.json).

  3. Mova seu arquivo de configuração para o diretório de módulos do seu app.

Etapa 2: adicionar o SDK do Firebase Crashlytics

  1. No nível raiz do seu app (nível do projeto) build.gradle:

    • Substitua o repositório Maven do Fabric pelo repositório Maven do Google.

    • Substitua o plug-in do Gradle para Fabric pelo plug-in do Gradle para Firebase Crashlytics. Se você estiver usando o Android Studio 4.1 Canary, adicione o plug-in do Gradle para Crashlytics versão 2.0.0 ou posterior.

    buildscript {
      // ...
    
      repositories {
        // ...
    
        // Remove Fabric's Maven repository
        maven { url 'https://maven.fabric.io/public' }
    
        // Add Google's Maven repository (if it's not there already)
        google()
      }
    
      dependencies {
        // ..
    
        // Add the Google Services Gradle plugin (if it's not there already)
        classpath 'com.google.gms:google-services:4.3.10'
    
        // Remove the Fabric Gradle plugin
        classpath 'io.fabric.tools:gradle:1.31.2'
    
        // Add the Crashlytics Gradle plugin (use v2.0.0+ if you built
        // your app with Android Studio 4.1).
        classpath 'com.google.firebase:firebase-crashlytics-gradle:2.8.1'
      }
    }
    
  2. No build.gradle no nível do app, substitua o plug-in do Fabric pelo plug-in do Firebase Crashlytics:

    apply plugin: 'com.android.application'
    
    // Apply the Google Services plugin (if it's not there already)
    apply plugin: 'com.google.gms.google-services'
    
    // Remove the Fabric plugin
    apply plugin: 'io.fabric'
    
    // Add the Firebase Crashlytics plugin
    apply plugin: 'com.google.firebase.crashlytics'
    
  3. Por fim, adicione o SDK do Firebase Crashlytics. No build.gradle no nível do app, substitua o SDK legado do Fabric Crashlytics pelo novo SDK do Firebase Crashlytics. Adicione a versão 17.0.0 ou posterior. Desde 15 de novembro de 2020, essa etapa passou a ser necessária para que seus relatórios de erros sejam exibidos no Console do Firebase.

    dependencies {
      // Remove the Fabric Crashlytics SDK
      implementation 'com.crashlytics.sdk.android:crashlytics:2.10.1'
    
      // Add the Firebase Crashlytics SDK
      implementation 'com.google.firebase:firebase-crashlytics:18.2.7'
    
      // Recommended: Add the Google Analytics SDK
      implementation 'com.google.firebase:firebase-analytics:20.0.2'
    }
    

(Opcional) Configurar o relatório de erros do NDK

O Firebase Crashlytics oferece um relatório de erros para apps criados com o Kit de desenvolvimento nativo (NDK, na sigla em inglês) do Android.

Para detectar e reportar falhas nativas:

  1. No build.gradle no nível do app, substitua a dependência do NDK do Fabric pela dependência do NDK do Firebase Crashlytics. Em seguida, adicione a extensão firebaseCrashlytics e ative a sinalização nativeSymbolUploadEnabled. Isso permite que o app processe e faça upload de símbolos nativos no Crashlytics, o que possibilita visualizar os stack traces corretamente simbolizados no painel do Crashlytics.

    dependencies {
      // Remove the Fabric NDK dependency
      implementation 'com.crashlytics.sdk.android:crashlytics-ndk:2.1.1'
    
      // Add the Firebase Crashlytics NDK dependency
      implementation 'com.google.firebase:firebase-crashlytics-ndk:18.2.7'
    }
    // ...
    
    android {
        // ...
    
        buildTypes {
            release {
                /* Add the firebaseCrashlytics extension (by default,
                * it's disabled to improve build speeds) and set
                * nativeSymbolUploadEnabled to true. */
    
                firebaseCrashlytics {
                    nativeSymbolUploadEnabled true
                }
            }
        }
    }
    
    // Remove this extension (it previously enabled Crashlytics NDK reporting in Fabric)
    crashlytics {
      enableNdk true
    }
    
  2. Execute as seguintes tarefas do Gradle específicas do NDK:

    > ./gradlew app:assembleBUILD_VARIANT
    > ./gradlew app:uploadCrashlyticsSymbolFileBUILD_VARIANT
    

Para mais informações sobre como usar o Crashlytics para relatório de erros do NDK, consulte a documentação do NDK do Crashlytics.

Etapa 3: atualizar seu código

Revise as seguintes alterações do SDK e faça as atualizações adequadas no seu código:


O Crashlytics agora alterna os IDs com base nos IDs de instalação do Firebase.

O Crashlytics usa o UUID de instalação dele para identificar instâncias do app e associar os dados dos usuários aos dispositivos. Antes, o Crashlytics alternava o UUID de instalação do usuário quando o ID de publicidade do dispositivo era alterado. Agora, o Crashlytics alterna o UUID de instalação com base no ID de instalação do Firebase (FID, na sigla em inglês) do usuário. Para mais informações, acesse Gerenciar IDs de instalação do Firebase.

Motivo para a alteração

O uso de FIDs (IDs de instalação do Firebase, na sigla em inglês) é consistente com outros SDKs do Firebase.


O novo pacote e o nome de classe do Crashlytics é com.google.firebase.crashlytics.FirebaseCrashlytics.

Agora, é possível invocar recursos do Crashlytics usando métodos de instância no singleton FirebaseCrashlytics em vez de funções estáticas na classe FirebaseCrashlytics. O singleton FirebaseCrashlytics pode ser acessado em todo o mundo por meio da função estática getInstance().

SDK do Fabric

Java

import com.crashlytics.android.Crashlytics;

// ...

// Operations on Crashlytics.
Crashlytics.someAction()

Kotlin+KTX

import com.crashlytics.android.Crashlytics

// ...

// Operations on Crashlytics.
Crashlytics.someAction()

SDK do Firebase Crashlytics

Java

import com.google.firebase.crashlytics.FirebaseCrashlytics;

// ...

// Operations on FirebaseCrashlytics.
FirebaseCrashlytics crashlytics = FirebaseCrashlytics.getInstance();
crashlytics.someAction();

Kotlin+KTX

import com.google.firebase.crashlytics.FirebaseCrashlytics

// ...

// Operations on FirebaseCrashlytics.
val crashlytics = FirebaseCrashlytics.getInstance()
crashlytics.someAction()

Motivo para a alteração

O pacote raiz e o ponto de entrada do novo SDK agora são consistentes com outros SDKs do Firebase. Além disso, os métodos de instância são mais fáceis de simular do que as funções estáticas, além de criarem menos desafios de teste.


O FirebaseCrashlytics não funciona mais com o SDK do Fabric.

Agora, o Crashlytics é iniciado automaticamente usando um ContentProvider definido no novo SDK do Firebase Crashlytics, que não usa mais a chave de API do Fabric. O Crashlytics agora usa o arquivo google-services.json do app para associar o aplicativo ao projeto do Firebase e manter os dados históricos de falha.

Remova a chave de API do Fabric (io.fabric.ApiKey) se ela estiver declarada no arquivo AndroidManifest.xml:

<manifest xmlns:android="http://schemas.android.com/apk/res/android"
   package="com.example.your_app_package">

   <application>
      <activity android:name=".MainActivity"/>

      <!-- Remove this line if it exists -->
      <meta-data android:name="io.fabric.ApiKey"
          android:value="xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" />

   </application>
</manifest>

Por padrão, o Crashlytics coleta e relata automaticamente falhas em todas as instâncias do seu app, mas é possível ativá-lo somente para usuários que autorizam a coleta. Para desativar os relatórios de falhas automáticos, no bloco <application> do arquivo AndroidManifest.xml, defina firebase_crashlytics_collection_enabled como false:

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

Motivo para a alteração

Para ficar consistente com outros SDKs do Firebase, o Crashlytics agora é iniciado automaticamente por meio de um ContentProvider. Assim como acontece com outros SDKs, agora ele fornece uma sinalização de manifesto para desativar a coleta de dados automática, que pode ser substituída a qualquer momento usando setCrashlyticsCollectionEnabled. O método oferece mais controle sobre o comportamento do relatório de erros do seu app.


O Crashlytics.log agora é um método de instância.

O novo SDK não inclui mais um método Crashlytics.log estático. Para adicionar mensagens de registro personalizadas, use o novo método de instância crashlytics.log. Observe que o novo método não gera mais novos registros para o logcat. Recomendamos que você grave um wrapper se quiser manter esse comportamento. Para mais informações, acesse adicionar mensagens de registro personalizadas.

SDK do Fabric

Java

Crashlytics.log("my message");

Crashlytics.log(
 Log.ERROR,
 "TAG",
 "my message");

Kotlin+KTX

Crashlytics.log("my message")

Crashlytics.log(
 Log.ERROR,
 "TAG",
 "my message")

SDK do Firebase Crashlytics

Java

FirebaseCrashlytics crashlytics = FirebaseCrashlytics.getInstance();

crashlytics.log("my message");

// To log a message to a crash report, use the following syntax:
crashlytics.log("E/TAG: my message");

Kotlin+KTX

val crashlytics = FirebaseCrashlytics.getInstance()

crashlytics.log("my message")

// To log a message to a crash report, use the following syntax:
crashlytics.log("E/TAG: my message")

Motivo para a alteração

Conforme solicitado, interrompemos a geração de registros do Crashlytics para o logcat. O uso de métodos de instância também facilita o teste do código.


setBool, setDouble, setFloat, setInt, setLong e setString são agregados no setCustomKey.

Agregamos os setters de chaves personalizadas ao método setCustomKey. Antes, era possível usar os configuradores de chave personalizados para definir pares de chave/valor a serem enviados com seu relatório de erros. Agora, é possível usar setCustomKey(String, value), que é sobrecarregado para aceitar tipos primitivos e de string. Para mais informações, acesse Adicionar chaves personalizadas.

SDK do Fabric

Java

Crashlytics.setBool("bool_key",true);

Crashlytics.setDouble("double_key",42.0);

Crashlytics.setFloat("float_key",42.0F);

Crashlytics.setInt("int_key",42);

Crashlytics.setLong("long_key",42L);

Crashlytics.setString("str_key","str_value");

Kotlin+KTX

Crashlytics.setBool("bool_key",true)

Crashlytics.setDouble("double_key",42.0)

Crashlytics.setFloat("float_key",42.0F)

Crashlytics.setInt("int_key",42)

Crashlytics.setLong("long_key",42L)

Crashlytics.setString("str_key","str_value")

SDK do Firebase Crashlytics

Java

FirebaseCrashlytics crashlytics = FirebaseCrashlytics.getInstance();

crashlytics.setCustomKey("bool_key",true);

crashlytics.setCustomKey("double_key",42.0);

crashlytics.setCustomKey("float_key",42.0F);

crashlytics.setCustomKey("int_key",42);

crashlytics.setCustomKey("long_key",42L);

crashlytics.setCustomKey("str_key","42");

Kotlin+KTX

FirebaseCrashlytics crashlytics = FirebaseCrashlytics.getInstance()

crashlytics.setCustomKey("bool_key",true)

crashlytics.setCustomKey("double_key",42.0)

crashlytics.setCustomKey("float_key",42.0F)

crashlytics.setCustomKey("int_key",42)

crashlytics.setCustomKey("long_key",42L)

crashlytics.setCustomKey("str_key","42")

Motivo para a alteração

O novo nome do método é exclusivo ao Crashlytics e deixa claro que o Crashlytics não é compatível com chaves-valor.


O setUserIdentifier agora é setUserId. O setUserName e setUserEmail foram removidos.

Antes, era possível definir um nome ou e-mail associado a uma falha usando setUserName e setUserEmail, mas esses métodos não são mais definidos. O novo método preferencial para definir IDs para seus usuários é usar setUserId. Para mais informações, acesse Definir identificadores de usuário.

SDK do Fabric

Java

Crashlytics.setUserIdentifier("myAppUserId");

Crashlytics.setUserEmail("abc@example.com");

Crashlytics.setUserName("John Doe");

Kotlin+KTX

Crashlytics.setUserIdentifier("myAppUserId")

Crashlytics.setUserEmail("abc@example.com")

Crashlytics.setUserName("John Doe")

SDK do Firebase Crashlytics

Java

crashlytics.setUserId("myAppUserId");

Kotlin+KTX

crashlytics.setUserId("myAppUserId")

Motivo para a alteração

Adotamos o nome do método setUserId para que fique consistente com outras APIs do Firebase. Além disso, removemos setUserName e setUserEmail para desestimular o registro de PII pelo Crashlytics.


O Crashlytics.logException(Throwable) foi substituído por FirebaseCrashlytics.recordException(Throwable).

O Crashlytics agora também oferece suporte à geração de registros de erros e tipos de exceção integrados para apps Apple e Android.

SDK do Fabric

Java

try {
/* Code that can throw checked
exceptions. */

// ...

} catch (Exception e) {
Crashlytics.logException(e);
}

Kotlin+KTX

try {
/* Code that can throw checked
exceptions. */

// ...

catch (e: Exception) {
Crashlytics.logException(e)
}

SDK do Firebase Crashlytics

Java

try {
/* Code that can throw checked
exceptions. */

// ...

} catch (Exception e) {
FirebaseCrashlytics.getInstance().recordException(e);
}

Kotlin+KTX

try {
/* Code that can throw checked
exceptions. */

// ...

catch (e: Exception) {
FirebaseCrashlytics.getInstance().recordException(e)
}

Motivo para a alteração

O novo método recordException(Throwable) é mais facilmente distinguível de log(String), que se comporta de maneira diferente. Além disso, renomeamos a nova API para ficar mais consistente em todas as plataformas.


O CrashlyticsListener foi substituído pelo didCrashOnPreviousExecution().

Antes, o CrashlyticsListener permitia que o Crashlytics indicasse quando uma sessão anterior do app terminava com uma falha, o que é útil para apps que exibem mensagens pós-falha na reinicialização. Agora, o retorno de chamada é substituído pela chamada de API síncrona didCrashOnPreviousExecution().

SDK do Fabric

Java

CrashlyticsListener crashlyticsListener =
new CrashlyticsListener() {
  @Override
  public void crashlyticsDidDetectCrashDuringPreviousExecution() {
    // ...App code to execute if a crash occurred during previous execution.
  }
};

CrashlyticsCore crashlyticsCore = new CrashlyticsCore.Builder()
                                      .listener(crashlyticsListener)
                                      .build();

Crashlytics crashlytics = new Crashlytics.Builder().core(crashlyticsCore).build();

Fabric.with(getContext(), crashlytics);

Kotlin+KTX

val crashlyticsListener = CrashlyticsListener {
  // ...App code to execute if a crash occurred during previous execution.
}
val crashlyticsCore = CrashlyticsCore.Builder()
  .listener(crashlyticsListener)
  .build()
val crashlytics = Crashlytics.Builder().core(crashlyticsCore).build()
Fabric.with(getContext(), crashlytics)

SDK do Firebase Crashlytics

Java

if (FirebaseCrashlytics.getInstance().didCrashOnPreviousExecution()) {
// ...App code to execute if a crash occurred during previous execution.
}

Kotlin+KTX

if (FirebaseCrashlytics.getInstance().didCrashOnPreviousExecution()) {
// ...App code to execute if a crash occurred during previous execution.
}

Motivo para a alteração

A nova API é menos detalhada e menos desafiadora do que o CrashlyticsListener, porque não requer texto padrão nem um retorno de chamada. Antes, o retorno de chamada assíncrono não garantia quando o retorno de chamada seria invocado.


O método de falha foi removido.

O novo SDK não inclui mais o método de falha, que podia ser usado para validar a configuração do Crashlytics ao forçar uma falha no app. Lance um RuntimeException para forçar uma falha.

SDK do Fabric

Java

Crashlytics.getInstance().crash();

Kotlin+KTX

Crashlytics.getInstance().crash()

SDK do Firebase Crashlytics

Java

throw new RuntimeException("Test Crash");

Kotlin+KTX

throw RuntimeException("Test Crash")

Motivo para a alteração

Os novos métodos especificam claramente se as falhas resultantes do seu app ocorreram durante o tempo de execução ou no SDK nativo do app.


O plug-in do Gradle para Crashlytics contém novas sinalizações.

O plug-in do Gradle continua a configurar e executar tarefas do Gradle específicas do Crashlytics automaticamente. Se a compilação exigir a invocação de tarefas do plug-in do Gradle para Crashlytics, consulte as tarefas do Firebase Crashlytics disponíveis. Para isso, execute ./gradlew app:tasks. Se o app usar um NDK, você precisará invocar explicitamente a tarefa uploadCrashlyticsSymbolFile[BUILD_VARIANT] do Gradle para continuar fazendo upload de símbolos nativos para o Crashlytics.

As sinalizações de versão específicas do Crashlytics ext.alwaysUpdateBuildId e ext.enableCrashlytics não são mais compatíveis. Remova-as da configuração do Gradle, se houver. Se o app usar um ofuscador de bytecode (por exemplo, R8 ou Proguard) e não você quiser fazer upload do arquivo de mapeamento da sua versão para o Crashlytics, use a nova sinalização mappingFileUploadEnabled na extensão firebaseCrashlytics do Gradle. Quando definido como falso, o Crashlytics não pode desofuscar os stack traces do app. Em configurações de ofuscação não padrão, use o parâmetro mappingFile para definir um novo local para o arquivo de mapeamento. Essas sinalizações podem ser usadas para defaultConfig, bem como para qualquer tipo de versão ou variação.

SDK do Firebase Crashlytics

apply plugin: 'com.android.application'
apply plugin: 'com.google.firebase.crashlytics'
apply plugin: 'com.google.gms.google-services'

android {
    // ...

    buildTypes {
        debug {
            minifyEnabled true
            firebaseCrashlytics {
                // If you don't need crash reporting for your debug build,
                // you can speed up your build by disabling mapping file uploading.
                mappingFileUploadEnabled false
            }
        }

        release {
            minifyEnabled true
            // When minifyEnabled is set to true, Crashlytics automatically
            // uploads mapping files because the plugin detects that obfuscation
            // is enabled. mappingFileUploadEnabled defaults to true if
            // minifyEnabled is true.
        }
    }
}

Motivo para a alteração

Atualizamos as tarefas e as opções de configuração do Gradle para serem mais consistentes com as convenções do Gradle.


O Crashlytics só pode usar dados coletados pelo Google Analytics.

Não é mais possível coletar dados com o Fabric Answers após o upgrade para o SDK do Firebase Crashlytics. Para ver métricas de usuários sem falhas e navegações estruturais, mude para o Google Analytics. Não é possível migrar seus dados históricos do Answers para o Firebase.

Acesse Começar a usar o Google Analytics para saber como adicionar o Google Analytics ao seu aplicativo.

Motivo para a alteração

Agora oferecemos o Google Analytics para ajudar você a conseguir mais informações sobre seus dados de falhas. O Analytics permite que você continue coletando estatísticas para seu app no Console do Firebase.


Próximas etapas