This guide contains instructions for the latest version of the Firebase Crashlytics SDK. If you migrated your app from Fabric, make sure it's been upgraded and no longer uses the deprecated legacy Fabric SDK.

自定义 Firebase Crashlytics 崩溃报告

本指南介绍如何使用 Firebase Crashlytics SDK 自定义崩溃报告。默认情况下,Crashlytics 会自动为您应用的所有用户收集崩溃报告(您可以关闭自动崩溃报告,并为您的用户启用自选式报告)。Crashlytics 提供了四种日志记录机制:自定义键自定义日志用户标识符捕获的异常

添加自定义键

自定义键可以帮助您获取导致崩溃的应用的特定状态。您可以将任意键值对与您的崩溃报告相关联,然后在 Firebase 控制台中查看这些键值对。

使用 setCustomKey 实例方法设置键值对:

Java

setCustomKey 已重载,使得 value 形参可以接受任何基本实参或字符串实参。例如:

// Set a key to a string.
FirebaseCrashlytics.getInstance().setCustomKey("str_key", "hello");

// Set a key to a boolean.
FirebaseCrashlytics.getInstance().setCustomKey("bool_key", true);

// Set a key to an int.
FirebaseCrashlytics.getInstance().setCustomKey("int_key", 1);

// Set a key to a long.
FirebaseCrashlytics.getInstance().setCustomKey("int_key", 1L);

// Set a key to a float.
FirebaseCrashlytics.getInstance().setCustomKey("float_key", 1.0f);

// Set a key to a double.
FirebaseCrashlytics.getInstance().setCustomKey("double_key", 1.0);
Kotlin
// Set a key to a string.
FirebaseCrashlytics.getInstance().setCustomKey("str_key", "hello")

// Set a key to a boolean.
FirebaseCrashlytics.getInstance().setCustomKey("bool_key", true)

// Set a key to an int.
FirebaseCrashlytics.getInstance().setCustomKey("int_key", 1)

// Set a key to an long.
FirebaseCrashlytics.getInstance().setCustomKey("int_key", 1L)

// Set a key to a float.
FirebaseCrashlytics.getInstance().setCustomKey("float_key", 1.0f)

// Set a key to a double.
FirebaseCrashlytics.getInstance().setCustomKey("double_key", 1.0)

您还可以通过调用现有键并将其设置为不同的值来修改现有键的值。例如:

Java
FirebaseCrashlytics.getInstance().setCustomKey("int_key", 50);

// Set int_key from 50 to 100.
FirebaseCrashlytics.getInstance().setCustomKey("int_key", 100);
Kotlin
FirebaseCrashlytics.getInstance().setCustomKey("int_key", 50)

// Set int_key from 50 to 100.
FirebaseCrashlytics.getInstance().setCustomKey("int_key", 100)

添加自定义日志消息

为了了解导致崩溃的事件的更多背景信息,您可以向应用添加自定义 Crashlytics 日志。Crashlytics 会将日志与您的崩溃数据相关联,并将其显示在 Firebase 控制台的 Crashlytics 页面的日志标签页下。

使用 log 可以帮助查明问题。例如:

Java

FirebaseCrashlytics.getInstance().log("Higgs-Boson detected! Bailing out");

Kotlin+KTX

FirebaseCrashlytics.getInstance().log("Higgs-Boson detected! Bailing out")

设置用户标识符

为了诊断某个问题,了解哪些用户遇到了特定的崩溃通常很有帮助。Crashlytics 提供了一种在崩溃报告中以匿名方式标识用户的方法。

要将用户 ID 添加到报告中,请以 ID 编号、令牌或哈希值的形式为每个用户分配一个唯一标识符:

Java

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

Kotlin+KTX

FirebaseCrashlytics.getInstance().setUserId("12345")

如果您在设置某个用户标识符后需要将其清除,请将该值重置为空白字符串。清除用户标识符不会移除现有的 Crashlytics 记录。如果您需要删除与用户 ID 关联的记录,请与 Firebase 支持团队联系

报告非严重异常

除了自动报告您的应用中出现的崩溃,Crashlytics 还可让您记录非严重异常,并在应用下次启动时将这些异常记录发送给您。

使用 recordException 方法在您应用的 catch 块中记录非严重异常。例如:

Java

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

Kotlin+KTX

try {
    methodThatThrows()
} catch (e: Exception) {
    FirebaseCrashlytics.getInstance().recordException(e)
    // ...handle the exception.
}
警告:如果您想在异常消息中包含唯一值(例如用户 ID 或时间戳),请使用自定义键,而不是直接在异常消息中添加值。直接添加值可能会导致一些问题,并可能导致 Crashlytics 在您的应用中对报告错误的功能进行限制。

所记录的所有异常在 Firebase 控制台中均显示为非严重问题。问题摘要中会包含您通常可以从崩溃中获得的所有状态信息,以及按 Android 版本和硬件设备细分的数据。

Crashlytics 在一个专用的后台线程中处理异常,所以对您的应用性能的影响极小。为了减少用户的网络流量,Crashlytics 会一并批量处理已记录的异常,并在应用下次启动时发送这些异常。

启用自选式报告

默认情况下,Crashlytics 会自动为您的应用的所有用户收集崩溃报告。为了让用户对其发送的数据有更多的控制权,您可以为用户启用自选式报告功能,为此,请停用自动收集功能,并且仅为选定用户初始化 Crashlytics:

  1. AndroidManifest.xml 文件的 application 部分中,添加 meta-data 标记以停用自动收集功能:

    <meta-data
        android:name="firebase_crashlytics_collection_enabled"
        android:value="false" />
    
  2. 在运行时调用 Crashlytics 数据收集替换,从而为选定用户启用收集功能。在您的应用的多次启动之间,替换值会保持不变,因此 Crashlytics 可以自动收集相关报告。如需停用自动崩溃报告功能,请将 false 作为替换值传递。将此设置为 false 时,新值要等到应用下次运行时才会生效。

    Java

    FirebaseCrashlytics.getInstance().setCrashlyticsCollectionEnabled(true);

    Kotlin+KTX

    FirebaseCrashlytics.getInstance().setCrashlyticsCollectionEnabled(true)

管理 Crash Insights 数据

Crash Insights 会比较您的匿名堆栈轨迹和来自其他 Firebase 应用的跟踪数据,并让您知道您的问题是否属于个例,从而帮助您解决问题。对于许多问题,Crash Insights 甚至会提供资源来帮助您调试崩溃。

Crash Insights 使用汇总的崩溃数据来识别常见的稳定性趋势。 如果您不想分享应用的数据,则可以在 Crash Insights 菜单中选择停用 Crash Insights。此菜单位于 Firebase 控制台的 Crashlytics 问题列表顶部。