自定义 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 问题列表顶部。