Check out what’s new from Firebase@ Google I/O 2021, and join our alpha program for early access to the new Remote Config personalization feature. Learn more

升級到 Firebase Crashlytics SDK

您現在可以使用新的官方 Firebase Crashlytics SDK 在您的應用中設置 Crashlytics,該 SDK 提供了改進的 API,與其他 Firebase 產品更加一致,使用起來更加直觀。本指南介紹瞭如何從舊版 Fabric SDK 升級到新 SDK。它描述了新 API 帶來的更改、更改的原因以及如何更新代碼(如果需要)。

在你開始之前

Firebase Crashlytics SDK 使用 AndroidX 作為依賴項,因此如果您的應用使用舊版本的應用支持庫,請先將您的應用遷移到AndroidX

第 1 步:添加 Firebase 配置文件

將 Firebase Android 配置文件添加到您的應用:

  1. 打開您的項目設置。您的應用程序卡中,選擇您需要配置文件的應用程序的包名稱。
  2. 單擊下載 google-services.json以獲取您的 Firebase Android 配置文件。
    • 您可以隨時再次下載 Firebase Android 配置文件。
    • 確保配置文件沒有附加其他字符,例如(2)
  3. 將您的配置文件移動到您的應用程序的模塊(應用程序級)目錄中。

第 2 步:添加 Firebase Crashlytics SDK

  1. 在您的應用程序的根級(項目級) build.gradle
    • 將 Fabric 的 Maven 存儲庫替換為 Google 的 Maven 存儲庫。
    • 將 Fabric Gradle 插件替換為 Firebase Crashlytics Gradle 插件。如果您使用的是 Android Studio 4.1 Canary,請務必添加 Crashlytics Gradle 插件版本 2.0.0或更高版本。
    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.8'
    
        // 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.7.0'
      }
    }
  2. 在您的應用級build.gradle ,將 Fabric 插件替換為 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. 最後,添加 Firebase Crashlytics SDK。在您的應用級build.gradle ,將舊版 Fabric Crashlytics SDK 替換為新的 Firebase Crashlytics SDK。確保添加版本 17.0.0 或更高版本(從 2020 年 11 月 15 日開始,這是您的崩潰報告顯示在 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.0.1'
    
      // Recommended: Add the Google Analytics SDK.
      implementation 'com.google.firebase:firebase-analytics:19.0.0'
    }

可選步驟:設置 NDK 崩潰報告

Firebase Crashlytics 為使用 Android Native Development Kit (NDK) 構建的應用程序提供崩潰報告。請注意,Crashlytics NDK v17.3.0+ 需要 Crashlytics Gradle 插件 v2.4.0+。

要檢測和報告本機崩潰:

  1. 在您的應用級build.gradle ,將 Fabric NDK 依賴項替換為 Firebase Crashlytics NDK 依賴項。然後,添加nativeSymbolUploadEnabled擴展並確保啟用nativeSymbolUploadEnabled標誌。這允許您的應用程序處理本地符號並將其上傳到 Crashlytics,以便您可以在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.0.1'
    }
    // ...
    
    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. 運行以下特定於 NDK 的 Gradle 任務:
    > ./gradlew app:assembleBUILD_VARIANT
    > ./gradlew app:uploadCrashlyticsSymbolFileBUILD_VARIANT
      
  3. 有關使用 Crashlytics 進行 NDK 崩潰報告的更多信息,請參閱Crashlytics NDK 文檔

第 3 步:更新您的代碼

查看以下 SDK 更改並對您的代碼進行適當更新:


Crashlytics 現在根據 Firebase 安裝 ID 輪換 ID。

Crashlytics 使用 Crashlytics 安裝 UUID 來識別您的應用程序實例並將您的用戶數據與其設備相關聯。以前,當用戶設備的廣告 ID 發生變化時,Crashlytics 會輪換用戶的安裝 UUID。現在,Crashlytics 根據用戶的 Firebase 安裝 ID (FID) 輪換安裝 UUID。有關更多信息,請訪問管理 Firebase 安裝 ID

改變的理由

使用 FID 與其他 Firebase SDK 一致。


Crashlytics 的新包和類名是 com.google.firebase.crashlytics.FirebaseCrashlytics。

您現在可以使用 FirebaseCrashlytics 單例中的實例方法而不是 FirebaseCrashlytics 類中的靜態函數來調用 Crashlytics 功能。 FirebaseCrashlytics 單例可通過getInstance()靜態函數全局訪問。

面料 SDK

爪哇

import com.crashlytics.android.Crashlytics;

// ...

// Operations on Crashlytics.
Crashlytics.someAction()

科特林+KTX

import com.crashlytics.android.Crashlytics

// ...

// Operations on Crashlytics.
Crashlytics.someAction()

Firebase Crashlytics SDK

爪哇

import com.google.firebase.crashlytics.FirebaseCrashlytics;

// ...

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

科特林+KTX

import com.google.firebase.crashlytics.FirebaseCrashlytics

// ...

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

改變的理由

新 SDK 的根包和入口點現在與其他 Firebase SDK 一致。此外,實例方法比靜態函數更容易模擬,並且產生的可測試性挑戰更少。


FirebaseCrashlytics 不再適用於 Fabric SDK。

現在,Crashlytics 使用新 Firebase Crashlytics SDK 中定義的 ContentProvider 自動啟動,該 SDK 不再使用 Fabric API 密鑰。 Crashlytics 現在使用您應用的google-services.json文件將應用與您的 Firebase 項目相關聯,並保留您的歷史崩潰數據。

如果您在AndroidManifest.xml文件中聲明了 Fabric API 密鑰 ( io.fabric.ApiKey ),請將其刪除:

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

默認情況下,Crashlytics 會自動收集和報告應用程序所有實例的崩潰,但您可以選擇僅為選擇加入的用戶啟用它。要關閉自動崩潰報告,請在AndroidManifest.xml文件的<application>塊中,將firebase_crashlytics_collection_enabled設置為false

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

改變的理由

為了與其他 Firebase SDK 保持一致,Crashlytics 現在通過 ContentProvider 自動啟動。與其他 SDK 一樣,它現在提供了一個清單標誌來禁用自動數據收集,您可以隨時使用setCrashlyticsCollectionEnabled覆蓋該setCrashlyticsCollectionEnabled 。該方法使您可以更好地控制應用程序的崩潰報告行為。


Crashlytics.log 現在是一個實例方法。

新 SDK 不再包含靜態Crashlytics.log方法。要添加自定義日誌消息,請改用新的實例方法crashlytics.log 。請注意,新方法不再與 logcat 相呼應(如果您想保留此行為,我們建議編寫包裝器)。有關更多信息,請訪問添加自定義日誌消息

面料 SDK

爪哇

Crashlytics.log("my message");

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

科特林+KTX

Crashlytics.log("my message")

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

Firebase Crashlytics SDK

爪哇

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");

科特林+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")

改變的理由

應您的要求,我們已停止將 Crashlytics 日誌回顯到 logcat。使用實例方法還可以更輕鬆地測試您的代碼。


setBool、setDouble、setFloat 和 setInt、setLong 和 setString 聚合為 setCustomKey。

我們將自定義鍵設置器聚合到方法setCustomKey 。以前,您可以使用自定義鍵設置器來設置鍵/值對與崩潰報告一起發送。現在,您可以使用setCustomKey(String, value) ,它被重載以接受原始類型和字符串類型。有關更多信息,請訪問添加自定義鍵。

面料 SDK

爪哇

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");

科特林+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")

Firebase Crashlytics SDK

爪哇

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");

科特林+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")

改變的理由

新方法名稱是 Crashlytics 獨有的,並明確表明 Crashlytics 不符合鍵值對。


setUserIdentifier 現在是 setUserId。 setUserName 和 setUserEmail 被刪除。

以前,您可以使用setUserNamesetUserEmail設置與崩潰關聯的名稱或電子郵件,但不再定義這些方法。為用戶設置 ID 的新首選方法是使用setUserId 。有關更多信息,請訪問設置用戶標識符。

面料 SDK

爪哇

Crashlytics.setUserIdentifier("myAppUserId");

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

Crashlytics.setUserName("John Doe");

科特林+KTX

Crashlytics.setUserIdentifier("myAppUserId")

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

Crashlytics.setUserName("John Doe")

Firebase Crashlytics SDK

爪哇

crashlytics.setUserId("myAppUserId");

科特林+KTX

crashlytics.setUserId("myAppUserId")

改變的理由

我們採用了方法名稱setUserId以與其他 Firebase API 保持一致,並刪除了setUserNamesetUserEmail以阻止通過 Crashlytics 記錄 PII。


Crashlytics.logException(Throwable) 被 FirebaseCrashlytics.recordException(Throwable) 取代。

Crashlytics 現在還支持記錄 Android 和 iOS 的內置錯誤和異常類型。

面料 SDK

爪哇

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

// ...

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

科特林+KTX

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

// ...

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

Firebase Crashlytics SDK

爪哇

第0616章

科特林+KTX

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

// ...

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

改變的理由

新方法recordException(Throwable)更容易與行為不同的log(String)區分開來。此外,我們對新 API 進行了重命名,以使其跨平台更加一致。


CrashlyticsListener 被 didCrashOnPreviousExecution() 取代。

CrashlyticsListener 之前允許 Crashlytics 指示前一個應用會話何時以崩潰結束,這對於在重新啟動時顯示崩潰後消息的應用非常有用。現在,它的回調被同步 API 調用didCrashOnPreviousExecution()取代。

面料 SDK

爪哇

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);

科特林+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)

Firebase Crashlytics SDK

爪哇

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

科特林+KTX

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

改變的理由

與 CrashlyticsListener 相比,新 API 不那麼冗長,使用起來也更簡單,因為它既不需要樣板文本也不需要回調。以前,異步回調不能保證何時調用回調。


刪除了崩潰方法。

新 SDK 不再包含 crash 方法,您以前可以使用該方法通過強制應用崩潰來驗證 Crashlytics 配置。拋出RuntimeException以強制崩潰。

面料 SDK

爪哇

Crashlytics.getInstance().crash();

科特林+KTX

Crashlytics.getInstance().crash()

Firebase Crashlytics SDK

爪哇

throw new RuntimeException("Test Crash");

科特林+KTX

throw RuntimeException("Test Crash")

改變的理由

新方法明確指定您的應用程序導致崩潰是發生在運行時還是在應用程序的本機 SDK 中。


Crashlytics Gradle 插件包含新標誌。

Gradle 插件會繼續自動配置和執行 Crashlytics 特定的 Gradle 任務。如果您的構建需要從 Crashlytics Gradle 插件調用任務,請通過運行./gradlew app:tasks來引用可用的 Firebase Crashlytics ./gradlew app:tasks 。如果您的應用使用 NDK,您必須顯式調用uploadCrashlyticsSymbolFile[ BUILD_VARIANT ] Gradle 任務才能繼續將本機符號上傳到 Crashlytics。

不再支持 Crashlytics 特定的構建標誌ext.alwaysUpdateBuildIdext.enableCrashlytics 。如果它們存在,請從您的 Gradle 配置中刪除它們。如果應用程序使用一個字節碼混淆(例如,R8或Proguard的),你不想上傳您構建的映射文件Crashlytics,使用新mappingFileUploadEnabled國旗在firebaseCrashlytics搖籃擴展。設置為 false 時,Crashlytics 無法對應用的堆棧跟踪進行反混淆處理。對於非標準混淆器配置,請使用mappingFile參數為映射文件設置新位置。這些標誌可用於 defaultConfig,以及任何構建類型或風格。

Firebase Crashlytics SDK

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

改變的理由

我們更新了 Gradle 任務和配置選項,使其與 Gradle 約定更加一致。


Crashlytics 只能使用 Google Analytics 收集的數據。

升級到 Firebase Crashlytics SDK 後,您將無法再使用 Fabric Answers 收集數據。要獲取無崩潰用戶和麵包屑的指標,請改用 Google Analytics。請注意,您的歷史答案數據無法遷移到 Firebase。

訪問開始使用 Google Analytics ,了解如何將 Google Analytics 添加到您的應用程序。

改變的理由

我們現在提供 Google Analytics 來幫助您更深入地了解您的崩潰數據。借助 Analytics,您可以繼續在 Firebase 控制台中為您的應用收集統計信息。


下一步