获取我们在 Firebase 峰会上发布的所有信息,了解 Firebase 可如何帮助您加快应用开发速度并满怀信心地运行应用。了解详情

自定义您的 Firebase Crashlytics 崩溃报告

本指南介绍如何使用 Crashlytics API 自定义崩溃报告。默认情况下,Crashlytics 会自动为您应用的所有用户收集平台原生崩溃报告(您也可以关闭自动崩溃报告并为您的用户启用选择加入报告)。 Crashlytics 提供了五种开箱即用的日志记录机制:自定义键自定义日志用户标识符捕获未捕获异常。

对于 Flutter 应用程序,致命报告会实时发送到 Crashlytics,而无需用户重新启动应用程序。非致命报告被写入磁盘,与下一个致命报告一起发送或在应用程序重新启动时发送。

报告未捕获的异常

您可以通过使用FirebaseCrashlytics.instance.recordFlutterFatalError覆盖FlutterError.onError来自动捕获 Flutter 框架内引发的所有“致命”错误。或者,要捕获“非致命”异常,请使用FirebaseCrashlytics.instance.recordFlutterError覆盖FlutterError.onError

void main() async {
  WidgetsFlutterBinding.ensureInitialized();

  await Firebase.initializeApp();
  bool weWantFatalErrorRecording = true;
  FlutterError.onError = (errorDetails) {
    if(weWantFatalErrorRecording){
      FirebaseCrashlytics.instance.recordFlutterFatalError(errorDetails);
    } else {
      FirebaseCrashlytics.instance.recordFlutterError(errorDetails);
    }
  };

  runApp(MyApp());
}

异步错误

Flutter 框架不会捕获异步错误:

ElevatedButton(
  onPressed: () async {
    throw Error();
  }
  ...
)

要捕获此类错误,您可以使用PlatformDispatcher.instance.onError处理程序:

Future<void> main() async {
    WidgetsFlutterBinding.ensureInitialized();
    await Firebase.initializeApp();
    FlutterError.onError = (errorDetails) {
      FirebaseCrashlytics.instance.recordFlutterFatalError(errorDetails);
    };
    // Pass all uncaught asynchronous errors that aren't handled by the Flutter framework to Crashlytics
    PlatformDispatcher.instance.onError = (error, stack) {
      FirebaseCrashlytics.instance.recordError(error, stack, fatal: true);
      return true;
    };
    runApp(MyApp());

}

Flutter 之外的错误

要捕获在 Flutter 上下文之外发生的错误,请在当前Isolate上安装一个错误侦听器:

Isolate.current.addErrorListener(RawReceivePort((pair) async {
  final List<dynamic> errorAndStacktrace = pair;
  await FirebaseCrashlytics.instance.recordError(
    errorAndStacktrace.first,
    errorAndStacktrace.last,
    fatal: true,
  );
}).sendPort);

报告捕获的异常

除了自动报告应用程序的崩溃之外,Crashlytics 还允许您记录非致命异常,并在下次报告致命事件或应用程序重新启动时将它们发送给您。

使用recordError方法在应用程序的 catch 块中记录非致命异常。例如:

await FirebaseCrashlytics.instance.recordError(
  error,
  stackTrace,
  reason: 'a non-fatal error'
);

// Or you can use:
await FirebaseCrashlytics.instance.recordFlutterError(errorDetails);

您可能还希望记录有关可能使用information属性的错误的更多信息:

await FirebaseCrashlytics.instance.recordError(
  error,
  stackTrace,
  reason: 'a non-fatal error',
  information: ['further diagnostic information about the error', 'version 2.0'],
);

这些异常在 Firebase 控制台中显示为非致命问题。问题摘要包含您通常从崩溃中获得的所有状态信息,以及按版本和硬件设备分类的故障。

Crashlytics 在专用后台线程上处理异常,以尽量减少对您的应用程序的性能影响。为了减少用户的网络流量,Crashlytics 将在必要时限制从设备发送的报告数量。

添加自定义键

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

  • Crashlytics 仪表板中,您可以搜索与自定义键匹配的问题。

  • 当您在控制台中查看特定问题时,您可以查看每个事件的关联自定义键(子选项卡),甚至可以通过自定义键过滤事件(页面顶部的过滤器菜单)。

使用setCustomKey实例方法设置键/值对。这里有些例子:

// Set a key to a string.
FirebaseCrashlytics.instance.setCustomKey('str_key', 'hello');

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

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

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

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

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

添加自定义日志消息

要为导致崩溃的事件提供更多背景信息,您可以将自定义 Crashlytics 日志添加到您的应用程序。 Crashlytics 将日志与您的崩溃数据相关联,并将它们显示在Firebase 控制台的 Crashlytics日志选项卡下。

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

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

设置用户标识符

要诊断问题,了解哪些用户遇到了给定的崩溃通常很有帮助。 Crashlytics 包括一种在您的崩溃报告中匿名识别用户的方法。

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

FirebaseCrashlytics.instance.setUserIdentifier("12345");

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

启用选择加入报告

默认情况下,Crashlytics 会自动为您应用的所有用户收集崩溃报告。为了让用户更好地控制他们发送的数据,您可以通过禁用自动报告并仅在您选择在代码中将数据发送到 Crashlytics 来启用选择报告:

  1. 本机关闭自动收集:

    苹果平台

    Info.plist文件中添加一个新密钥:

    • 键: FirebaseCrashlyticsCollectionEnabled
    • 值: false

    安卓

    AndroidManifest.xml文件的application块中,添加meta-data标签以关闭自动收集:

    <meta-data
        android:name="firebase_crashlytics_collection_enabled"
        android:value="false" />
    
  2. 通过在运行时调用 Crashlytics 数据收集覆盖来为选定用户启用收集。

    覆盖值在您的应用程序启动期间保持不变,因此 Crashlytics 可以自动收集报告。要选择退出自动崩溃报告,请将false作为覆盖值传递。当设置为false时,新值将在应用程序的下一次运行之前应用。

    FirebaseCrashlytics.instance.setCrashlyticsCollectionEnabled(true);
    

管理崩溃洞察数据

Crash Insights 通过将匿名堆栈跟踪与来自其他 Firebase 应用的跟踪进行比较,并让您知道您的问题是否属于更大趋势的一部分,从而帮助您解决问题。对于许多问题,Crash Insights 甚至提供资源来帮助您调试崩溃。

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