Crashlytics setup

Firebase Crashlytics Setup

Instructions

Follow these steps to wire Firebase Crashlytics into a mobile app so that every crash, non-fatal, and ANR is captured, symbolicated, and attributable to a release.

1. Prerequisites

• A Firebase project with the app registered for every target platform (one app per bundle id / application id).
• google-services.json (Android) and GoogleService-Info.plist (iOS) checked into the project or injected at build time per flavor.
• Crashlytics enabled in the Firebase console for each app; ANR collection enabled under Android settings.
• A release pipeline that can upload mapping files / dSYMs per build (see the symbolication skill).

2. Android (Kotlin) Integration

Add Gradle plugins in settings.gradle.kts or the root build.gradle.kts:

plugins {
    id("com.google.gms.google-services") version "4.4.2" apply false
    id("com.google.firebase.crashlytics") version "3.0.2" apply false
}

App module build.gradle.kts:

plugins {
    id("com.android.application")
    id("org.jetbrains.kotlin.android")
    id("com.google.gms.google-services")
    id("com.google.firebase.crashlytics")
}

dependencies {
    implementation(platform("com.google.firebase:firebase-bom:33.5.1"))
    implementation("com.google.firebase:firebase-crashlytics-ktx")
    implementation("com.google.firebase:firebase-analytics-ktx") // required for user-level breadcrumbs
}

android {
    buildTypes {
        getByName("release") {
            isMinifyEnabled = true
            configure<com.google.firebase.crashlytics.buildtools.gradle.CrashlyticsExtension> {
                mappingFileUploadEnabled = true
                nativeSymbolUploadEnabled = true
                unstrippedNativeLibsDir = file("build/intermediates/merged_native_libs/release/out/lib")
            }
        }
        getByName("debug") {
            configure<com.google.firebase.crashlytics.buildtools.gradle.CrashlyticsExtension> {
                mappingFileUploadEnabled = false
            }
        }
    }
}

Initialize in Application.onCreate:

class App : Application() {
    override fun onCreate() {
        super.onCreate()
        FirebaseApp.initializeApp(this)
        val crashlytics = FirebaseCrashlytics.getInstance()
        crashlytics.isCrashlyticsCollectionEnabled = BuildConfig.BUILD_TYPE == "release"
        crashlytics.setCustomKey("flavor", BuildConfig.FLAVOR)
        crashlytics.setCustomKey("build_number", BuildConfig.VERSION_CODE)
    }
}

3. iOS (Swift) Integration

Add the Firebase SPM package (https://github.com/firebase/firebase-ios-sdk) and include FirebaseCrashlytics and FirebaseAnalytics.

Add a Run Script build phase after [CP] Embed Pods Frameworks that runs:

"${PODS_ROOT}/FirebaseCrashlytics/run"

with input files $(BUILT_PRODUCTS_DIR)/$(INFOPLIST_PATH) and $(DWARF_DSYM_FOLDER_PATH)/$(DWARF_DSYM_FILE_NAME)/Contents/Resources/DWARF/$(EXECUTABLE_NAME).

Initialize in AppDelegate:

import FirebaseCore
import FirebaseCrashlytics

@main
class AppDelegate: UIResponder, UIApplicationDelegate {
    func application(_ application: UIApplication,
                     didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
        FirebaseApp.configure()
        Crashlytics.crashlytics().setCustomValue(Bundle.main.infoDictionary?["CFBundleVersion"] ?? "?", forKey: "build_number")
        #if DEBUG
        Crashlytics.crashlytics().setCrashlyticsCollectionEnabled(false)
        #endif
        return true
    }
}

4. Flutter Integration

# pubspec.yaml
dependencies:
  firebase_core: ^3.6.0
  firebase_crashlytics: ^4.1.3

Future<void> main() async {
  WidgetsFlutterBinding.ensureInitialized();
  await Firebase.initializeApp(options: DefaultFirebaseOptions.currentPlatform);

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

  await FirebaseCrashlytics.instance
      .setCrashlyticsCollectionEnabled(!kDebugMode);

  runApp(const MyApp());
}

Obfuscated release builds must pass --obfuscate --split-debug-info=build/symbols and you must upload the resulting symbols (see symbolication).

5. React Native Integration

yarn add @react-native-firebase/app @react-native-firebase/crashlytics
cd ios && pod install

import crashlytics from '@react-native-firebase/crashlytics';

export async function initCrashReporting(userIdHash: string, appVersion: string) {
  await crashlytics().setCrashlyticsCollectionEnabled(!__DEV__);
  await crashlytics().setUserId(userIdHash);
  await crashlytics().setAttributes({
    build_number: appVersion,
    js_engine: 'hermes',
  });
}

Configure firebase.json for automatic JS error capture:

{
  "react-native": {
    "crashlytics_javascript_exception_handler_chaining_enabled": true,
    "crashlytics_auto_collection_enabled": true
  }
}

6. Custom Keys and User Ids

• User id: set a stable hashed user id (SHA-256(userId + app_salt)), never the raw id. Do not set emails or phone numbers.
• Standard keys: release_channel, feature_flags_hash, last_screen, network_type, locale, experiment_bucket.
• Breadcrumbs via logs: call log("navigated to /cart") at key state transitions; Crashlytics attaches the last 64 log lines to the crash.

7. Non-Fatals and ANRs

• Capture caught exceptions that represent bugs with recordError / recordException so they surface alongside crashes.
• Tag non-fatals with a severity custom key (low/med/high) so dashboards can filter.
• ANRs are auto-captured on Android; you cannot opt specific traces out, but you can improve attribution by setting last_screen before any long-running operation.

8. Dashboards and Alerts

• Pin the Crash-free users and Crash-free sessions panels for the last release.
• Create Velocity alerts per app for new issues affecting more than 1% of sessions in the last hour.
• Alert on ANR rate > 0.47% of daily users (Play Store bad-behavior threshold) with a burn-rate policy (see the alerting-sla skill).
• Every alert must deep-link to the Crashlytics issue URL and include the affected release.

Checklist

• Gradle plugin / SPM package / pub package added for the correct platform.
• Collection disabled in debug, enabled in release.
• Custom keys include release_channel, build_number, flavor.
• User id is hashed, never raw.
• Non-fatals use recordError/recordException with a severity key.
• ANR collection is enabled (Android) and exercised in a staging build.
• Mapping files / dSYMs upload in CI for every release build.
• Velocity alert and crash-free SLO dashboards are pinned.