Firebase Crashlytics Skill

When to Use

• Setting up Crashlytics in a Flutter project.
• Configuring fatal and non-fatal error handling.
• Customizing crash reports with keys, logs, and user identifiers.
• Testing crash reporting or configuring opt-in data collection.

1. Setup and Configuration

flutter pub add firebase_crashlytics
flutter pub add firebase_analytics  # enables breadcrumb logs for better crash context

flutterfire configure

import 'package:firebase_crashlytics/firebase_crashlytics.dart';

• For apps built with

  --split-debug-info

  and/or

  --obfuscate

  , upload symbol files for readable stack traces.
• iOS: Flutter 3.12.0+ and Crashlytics Flutter plugin 3.3.4+ handle symbol upload automatically.
• Android: Use Firebase CLI (v11.9.0+) to upload Flutter debug symbols before reporting crashes:

firebase crashlytics:symbols:upload --app=FIREBASE_APP_ID PATH/TO/symbols

2. Error Handling

void main() async {
  WidgetsFlutterBinding.ensureInitialized();
  await Firebase.initializeApp();

  // Pass all uncaught fatal errors from the framework to Crashlytics
  FlutterError.onError = FirebaseCrashlytics.instance.recordFlutterFatalError;

  runApp(MyApp());
}

recordFlutterError

recordFlutterFatalError

PlatformDispatcher.instance.onError = (error, stack) {
  FirebaseCrashlytics.instance.recordError(error, stack, fatal: true);
  return true;
};

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

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

• Crashlytics only stores the most recent 8 non-fatal exceptions per session — older ones are discarded.

3. Crash Report Customization

FirebaseCrashlytics.instance.setCustomKey('str_key', 'hello');
FirebaseCrashlytics.instance.setCustomKey('bool_key', true);
FirebaseCrashlytics.instance.setCustomKey('int_key', 1);

FirebaseCrashlytics.instance.log("User tapped on payment button");

FirebaseCrashlytics.instance.setUserIdentifier("user-123");
// Clear by setting to blank string
FirebaseCrashlytics.instance.setUserIdentifier("");

• Avoid putting unique values (user IDs, timestamps) directly in exception messages — use custom keys instead.

4. Performance and Optimization

• Crashlytics processes exceptions on a dedicated background thread to minimize performance impact.
• Fatal reports are sent in real-time without requiring an app restart.
• Non-fatal reports are written to disk and sent with the next fatal report or on app restart.
• Crashlytics rate-limits reports from a device to reduce network traffic if necessary.
• Use breadcrumb logs (requires Firebase Analytics) to understand user actions leading up to a crash.

if (kReleaseMode) {
  await FirebaseCrashlytics.instance.setCrashlyticsCollectionEnabled(true);
} else {
  await FirebaseCrashlytics.instance.setCrashlyticsCollectionEnabled(false);
}

5. Testing and Debugging

FirebaseCrashlytics.instance.crash();

• Test both fatal and non-fatal error reporting.
• Verify stack traces are properly symbolicated when using code obfuscation.
• Check that custom keys, logs, and user identifiers are associated with crash reports.
• Monitor the Crashlytics dashboard regularly and set up alerts for new issues or regressions.

6. Opt-in Reporting

• Disable automatic reporting and enable it only via

  setCrashlyticsCollectionEnabled(true)

  when users opt in.
• The override value persists across all subsequent app launches.
• To opt a user out, pass

  false

  — this applies from the next app launch.
• When disabled, crash info is stored locally; if later enabled, locally stored crashes are sent to Crashlytics.

References

• Firebase Crashlytics Flutter documentation
• Customize crash reports