升级到 Firebase Crashlytics SDK

现在，您可以使用全新官方 Firebase Crashlytics SDK 在应用中设置 Crashlytics，该 SDK 提供了与其他 Firebase 产品更为一致、更加直观易用的改进版 API。

本指南介绍了如何从旧版 Fabric SDK 升级为新 SDK。其中说明了新 API 中的更改、更改的原因，以及如何更新代码（如果需要）。

准备工作

Firebase Crashlytics SDK 使用 AndroidX 作为依赖项，因此，如果您的应用使用旧版应用支持库，请先将应用迁移到 AndroidX。

第 1 步：添加 Firebase 配置文件

  1. 打开您的项目设置。在您的应用卡片中，选择您需要为其添加配置文件的应用的软件包名称。

  2. 点击下载 google-services.json 以获取 Firebase Android 配置文件 (google-services.json)。

  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.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. 在您的应用级 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 日开始，只有添加 17.0.0 或更高版本后，您的崩溃报告才会显示在 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'
}

（可选）设置 NDK 崩溃报告

对于使用 Android 原生开发套件 (NDK) 构建的应用，Firebase Crashlytics 会提供崩溃报告功能。

如需检测和报告原生代码崩溃问题，请执行以下操作：

  1. 在您的应用级 build.gradle 文件中，将 Fabric NDK 依赖项替换为 Firebase Crashlytics NDK 依赖项。然后，添加 firebaseCrashlytics 扩展程序，并确保启用 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.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. 运行以下特定于 NDK 的 Gradle 任务：

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

如需详细了解如何使用 Crashlytics 获取 NDK 崩溃报告，请参阅 Crashlytics NDK 文档。

第 3 步：更新您的代码

查看以下 SDK 更改，并对您的代码进行适当的更新：

Crashlytics 现在会根据 Firebase 安装 ID 来轮替 ID。

Crashlytics 使用 Crashlytics 安装 UUID 来标识应用的实例，并将用户数据与其设备相关联。 以前，Crashlytics 会在设备的广告 ID 发生更改时轮替用户的安装 UUID。现在，Crashlytics 会根据用户的 Firebase 安装 ID (FID) 来轮替安装 UUID。如需了解详情，请访问管理 Firebase 安装 ID。

更改的原因

使用 FID，以便与其他 Firebase SDK 保持一致。

Crashlytics 的新软件包和类名称是 com.google.firebase.crashlytics.FirebaseCrashlytics。

您现在可以使用 FirebaseCrashlytics 单例中的实例方法（而非 FirebaseCrashlytics 类中的静态函数）调用 Crashlytics 功能。FirebaseCrashlytics 单例可通过 getInstance() 静态函数在全局范围内进行访问。

Fabric SDK

Java

import com.crashlytics.android.Crashlytics;

// ...

// Operations on Crashlytics.
Crashlytics.someAction()

Kotlin+KTX 

import com.crashlytics.android.Crashlytics

// ...

// Operations on Crashlytics.
Crashlytics.someAction()

Firebase Crashlytics SDK

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

更改的原因

新 SDK 的 root 软件包和入口点现在与其他 Firebase SDK 一致。此外，与静态函数相比，实例方法更易于模拟，会造成的可测试性问题也更少。

FirebaseCrashlytics 不再支持 Fabric SDK。

现在，Crashlytics 会自动使用全新 Firebase Crashlytics SDK（该 SDK 不再使用 Fabric API 密钥）中定义的 ContentProvider 启动。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 替换该标志。通过这种方法，您就可以更好地控制应用的崩溃报告行为。

Crashlytics.log 现在是一个实例方法。

新 SDK 不再包含静态 Crashlytics.log 方法。如需添加自定义日志消息，请改用新实例方法 crashlytics.log。请注意，新方法不再回送到 logcat（如果您希望保留此行为，建议您编写封装容器）。如需了解详情，请访问 添加自定义日志消息。

Fabric SDK

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

Firebase Crashlytics SDK

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

更改的原因

应大家的要求，我们不再将 Crashlytics 日志回送到 logcat。使用实例方法还可以让您更轻松地测试代码。

setBool、setDouble、setFloat、setInt、setLong 和 setString 都已聚合到 setCustomKey 中。

我们已将自定义键 setter 方法聚合到 setCustomKey 方法中。 以前，您可以使用自定义键 setter 来设置键值对，以便随崩溃报告一起发送。现在，您可以使用 setCustomKey(String, value)，它已重载，可接受基本类型和字符串类型。 如需了解详情，请访问添加自定义键。

Fabric SDK

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

Firebase Crashlytics SDK

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

更改的原因

新方法名称是 Crashlytics 所独有的，明示了 Crashlytics 不遵循键值对格式。

setUserIdentifier 现已更改为 setUserId。setUserName 和 setUserEmail 已移除。

以前，您可以使用 setUserName 和 setUserEmail 设置与崩溃相关联的名称或电子邮件地址，但现在已经不再有这些方法的定义。如需为用户设置 ID，新的首选方法是使用 setUserId。如需了解详情，请访问设置用户标识符。

Fabric SDK

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

Firebase Crashlytics SDK

Java

crashlytics.setUserId("myAppUserId");

Kotlin+KTX 

crashlytics.setUserId("myAppUserId")

更改的原因

我们采用了方法名称 setUserId 以便与其他 Firebase API 保持一致，此外由于不建议通过 Crashlytics 记录个人身份信息 (PII)，我们移除了 setUserName 和 setUserEmail。

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

Crashlytics 现在还支持记录 Apple 和 Android 应用的内置错误和异常类型。

Fabric SDK

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

Firebase Crashlytics SDK

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

更改的原因

新方法 recordException(Throwable) 与 log(String) 的行为不同，因此更容易区分。此外，我们还为新 API 进行了重命名，使其在不同平台上更加一致。

CrashlyticsListener 已被 didCrashOnPreviousExecution() 所取代。

过去，CrashlyticsListener 允许 Crashlytics 指示先前的应用会话何时在崩溃状态下结束，这对于在重新启动时显示崩溃后消息的应用非常有用。现在，其回调已被同步 API 调用 didCrashOnPreviousExecution() 所取代。

Fabric SDK

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)

Firebase Crashlytics SDK

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

更改的原因

与 CrashlyticsListener 相比，新 API 的详细程度更低、使用难度也更低，因为它既不需要样板文本，也不需要回调。 以前，异步回调无法保证调用回调的时间。

crash 方法已被删除。

新 SDK 不再包含 crash 方法，该方法之前可通过在应用中强制造成崩溃来验证 Crashlytics 配置。抛出 RuntimeException 即可强制造成崩溃。

Fabric SDK

Java

Crashlytics.getInstance().crash();

Kotlin+KTX 

Crashlytics.getInstance().crash()

Firebase Crashlytics SDK

Java

throw new RuntimeException("Test Crash");

Kotlin+KTX 

throw RuntimeException("Test Crash")

更改的原因

新方法明确指出应用最终的崩溃是在运行时还是应用的原生 SDK 中发生的。

Crashlytics Gradle 插件增加了新的标志。

Gradle 插件会照旧自动配置和执行特定于 Crashlytics 的 Gradle 任务。如果您的 build 需要从 Crashlytics Gradle 插件调用任务，请运行 ./gradlew app:tasks 查看可用的 Firebase Crashlytics 任务。如果您的应用使用的是 NDK，则必须明确调用 uploadCrashlyticsSymbolFile[BUILD_VARIANT] Gradle 任务以继续将原生符号上传到 Crashlytics。

特定于 Crashlytics 的 build 标志 ext.alwaysUpdateBuildId 和 ext.enableCrashlytics 已不再受支持。如果您的 Gradle 配置中有这些标志，请将其移除。如果您的应用使用字节码混淆器（例如，R8 或 ProGuard），并且您不想将 build 的映射文件上传到 Crashlytics，请在 firebaseCrashlytics Gradle 扩展程序中使用新的 mappingFileUploadEnabled 标志。将其设置为 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（分析）。请注意，您的 Answers 历史解答数据无法迁移到 Firebase。

访问开始使用 Google Analytics（分析），以了解如何将 Google Analytics（分析）添加到您的应用中。

更改的原因

我们现在提供 Google Analytics（分析），以帮助您更深入地了解崩溃数据。借助 Analytics（分析），您可以继续在 Firebase 控制台中收集应用的统计信息。

后续步骤