自定义 Firebase Crashlytics 崩溃报告


在 Crashlytics 信息中心内，您可以点击进入某个问题并获取详细的事件报告。您可以自定义这些报告，以便更好地了解应用中发生的情况以及向 Crashlytics 报告事件的环境。

  • 如果您的应用使用 Firebase SDK for Google Analytics，会自动获取面包屑导航日志。借助这些日志，您可以了解导致应用中发生 Crashlytics 收集的事件的用户操作。

  • 关闭自动崩溃报告并为您的用户启用自选式报告。请注意，默认情况下，Crashlytics 会自动为应用的所有用户收集崩溃报告。

添加自定义键

自定义键可以帮助您获取导致崩溃的应用特定状态。 您可以将任意键值对与您的崩溃报告相关联，然后使用自定义键在 Firebase 控制台中搜索和过滤崩溃报告。

  • 在 Crashlytics 信息中心内，您可以搜索与自定义键匹配的问题。

  • 当您在控制台中查看某个特定问题时，可以查看每个事件关联的自定义键（在“键”子标签中），甚至可以按自定义键过滤事件（使用页面顶部的“过滤条件”菜单）。

使用 setCustomKey 实例方法设置键值对：请注意，setCustomKey 已重载，使得 value 形参可以接受任何基本实参或 String 实参。下面是一些示例：

Kotlin 

val crashlytics = Firebase.crashlytics
crashlytics.setCustomKeys {
    key("my_string_key", "foo") // String value
    key("my_bool_key", true) // boolean value
    key("my_double_key", 1.0) // double value
    key("my_float_key", 1.0f) // float value
    key("my_int_key", 1) // int value
}

Java 

FirebaseCrashlytics crashlytics = FirebaseCrashlytics.getInstance();

crashlytics.setCustomKey("my_string_key", "foo" /* string value */);

crashlytics.setCustomKey("my_bool_key", true /* boolean value */);

crashlytics.setCustomKey("my_double_key", 1.0 /* double value */);

crashlytics.setCustomKey("my_float_key", 1.0f /* float value */);

crashlytics.setCustomKey("my_int_key", 1 /* int value */);

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

Kotlin 

val crashlytics = Firebase.crashlytics
crashlytics.setCustomKeys {
    key("current_level", 3)
    key("last_UI_action", "logged_in")
}

Java 

FirebaseCrashlytics crashlytics = FirebaseCrashlytics.getInstance();

crashlytics.setCustomKey("current_level", 3);
crashlytics.setCustomKey("last_UI_action", "logged_in");

通过将 CustomKeysAndValues 实例传递给 setCustomKeys 实例方法，批量添加键值对：

Kotlin

对于 Kotlin，现有功能比使用 CustomKeysAndValues 构建器更简单：

crashlytics.setCustomKeys {
  key("str_key", "hello")
  key("bool_key", true)
  key("int_key", 1)
  key("long_key", 1L)
  key("float_key", 1.0f)
  key("double_key", 1.0)
}

Java 

CustomKeysAndValues keysAndValues = new CustomKeysAndValues.Builder()
.putString("string key", "string value")
.putString("string key 2", "string  value 2")
.putBoolean("boolean key", True)
.putBoolean("boolean key 2", False)
.putFloat("float key", 1.01)
.putFloat("float key 2", 2.02)
.build();

FirebaseCrashlytics.getInstance().setCustomKeys(keysAndValues);

添加自定义日志消息

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

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

Kotlin 

Firebase.crashlytics.log("message")

Java 

FirebaseCrashlytics.getInstance().log("message");

设置用户标识符

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

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

Kotlin 

Firebase.crashlytics.setUserId("user123456789")

Java 

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

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

（仅限 Android NDK）向 NDK 崩溃报告添加元数据

您可以视需要在 C++ 代码中包含 crashlytics.h 头文件，以将元数据（如自定义键、自定义日志和用户标识符）添加到 NDK 崩溃报告中。此页面中介绍了上述的所有选项。

Firebase Android SDK GitHub 代码库中提供了仅可作为头文件的 C++ 库形式的 crashlytics.h。

请阅读该头文件中的注释，了解有关使用 NDK C++ API 的说明。

添加 GWP-ASan 报告以调试内存损坏问题

Crashlytics 可以通过收集 GWP-ASan 报告，帮助您调试由原生内存错误引起的崩溃。这些内存相关错误可能与应用内的内存损坏有关，这也是导致应用安全漏洞的主要原因。

  • 在 Crashlytics 信息中心点击某个问题的详细信息后，系统便会打开一个新的“内存堆栈轨迹”标签页，您可在其中查看此数据。

  • 您还可以使用新的“GWP-ASan 报告”信号和过滤器，快速查看与此数据有关的所有问题。

如果您在应用中明确启用 GWP-ASan 并使用 Crashlytics SDK for NDK v18.3.6+ (Firebase BoM v31.3.0+)，则可以获取 GWP-ASan 内存报告。您可以使用 Android 文档中的原生代码示例测试 GWP-ASan 设置。

报告非严重异常

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

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

Kotlin 

try {
    methodThatThrows()
} catch (e: Exception) {
    Firebase.crashlytics.recordException(e)
    // handle your exception here
}

Java 

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

此外，您还可以将自定义键附加到特定的非严重异常。例如：

Kotlin 

try {
    methodThatThrows()
} catch (e: Exception) {
    Firebase.crashlytics.recordException(e) {
        key("string key", "string value")
        key("boolean key", true)
        key("float key", Float.MAX_VALUE)
    }
    // handle your exception here
}

Java 

try {
    methodThatThrows();
} catch (Exception e) {
    CustomKeysAndValues keysAndValues = new CustomKeysAndValues.Builder()
            .putString("string key", "string value")
            .putBoolean("boolean key", true)
            .putFloat("float key", Float.MAX_VALUE)
            .build();
    FirebaseCrashlytics.getInstance().recordException(e, keysAndValues);
    // handle your exception here
}

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

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

获取面包屑导航日志

面包屑导航日志可让您更好地了解用户与您的应用进行，导致崩溃、非严重或 ANR 事件的互动。在尝试重现和调试问题时，这些日志会很有用。

面包屑导航日志由 Google Analytics 提供支持，因此为了获取面包屑导航日志，您需要为 Firebase 项目启用 Google Analytics ，并添加 Firebase SDK for Google Analytics 到您的应用中。满足这些要求后，当您查看问题的详细信息时，面包屑导航日志便会随事件数据一起自动包含在日志标签页中。

Analytics SDK 会自动记录 screen_view 事件，从而使面包屑导航日志能够显示发生崩溃事件、非严重事件或 ANR 事件之前浏览过的屏幕的列表。screen_view 面包屑导航日志包含 firebase_screen_class 参数。

面包屑导航日志还会填充您在用户会话中手动记录的任何自定义事件，包括事件的参数数据。此数据有助于显示导致崩溃事件、非严重事件或 ANR 事件的一系列用户操作。

请注意，您可以控制 Google Analytics 数据的收集和使用，其中包括填充面包屑导航日志的数据。

启用自选式报告

默认情况下，Crashlytics 会自动为应用的所有用户收集崩溃报告。为了让用户对其发送的数据有更多的控制权，您可以启用自选式报告功能，方法是停用自动报告功能，并且仅当您在代码中进行选择后向 Crashlytics 发送数据。

  1. 在 AndroidManifest.xml 文件的 application 部分中，添加 meta-data 标记以关闭自动收集功能：

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

  2. 在运行时调用 Crashlytics 数据收集替换，从而为选定用户启用收集功能。 在应用的所有后续启动之间，替换值会保持不变，因此 Crashlytics 可以自动为该用户收集报告。

    Kotlin 

    Firebase.crashlytics.setCrashlyticsCollectionEnabled(true)

    Java 

    FirebaseCrashlytics.getInstance().setCrashlyticsCollectionEnabled(true);

    如果用户后来选择停用数据收集功能，您可以将 false 作为替换值传递，该值将在用户下次启动应用时生效，并在此后的每一次启动时自动沿用，而且仅对该用户有效。

管理 Crash Insights 数据

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

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