firebase-crashlytics

# Firebase Crashlytics - Android Setup Guide (Kotlin)

This guide describes the SDK setup and basic usage patterns for Firebase
Crashlytics in an Android app using Kotlin DSL (`build.gradle.kts`) and Kotlin
code.

## Prerequisites

IMPORTANT: Before specifically working with Firebase Crashlytics, make sure to
use the skill and reference `firebase_basics/references/android_setup` to ensure
the following is done.

- The Firebase CLI is available and authenticated.
- An Android project exists and is registered with a Firebase Project.
- The Android project has a Firebase config file (`google-services.json`) and
  the Google services Gradle plugin (`google-services`).

______________________________________________________________________

## 1. Add dependencies to Gradle build files

> [!IMPORTANT] **[AGENT] RESOLVING THE SDK & PLUGIN VERSIONS DETERMINISTICALLY**
> Never guess or hardcode a memorized out-of-date SDK or plugin version. Before
> adding dependencies, you MUST query the latest available versions directly
> from the Google Maven Repository:
>
> ```bash
> # Find the latest Firebase Android BoM version
> curl -s https://dl.google.com/dl/android/maven2/com/google/firebase/firebase-bom/maven-metadata.xml | grep -oE '<latest>[^<]+' | cut -d'>' -f2
>
> # Find the latest Crashlytics Gradle plugin version
> curl -s https://dl.google.com/dl/android/maven2/com/google/firebase/firebase-crashlytics-gradle/maven-metadata.xml | grep -oE '<latest>[^<]+' | cut -d'>' -f2
>
> # Find the latest firebase-crashlytics version
> curl -s https://dl.google.com/dl/android/maven2/com/google/firebase/firebase-crashlytics/maven-metadata.xml | grep -oE '<latest>[^<]+' | cut -d'>' -f2
>
> # Find the latest firebase-crashlytics-ndk version
> curl -s https://dl.google.com/dl/android/maven2/com/google/firebase/firebase-crashlytics-ndk/maven-metadata.xml | grep -oE '<latest>[^<]+' | cut -d'>' -f2
> ```
>
> If the dependency is already declared, fetch the exact resolved version
> currently active in the workspace's build graph:
>
> ```bash
> ./gradlew -q :app:dependencyInsight --dependency firebase-crashlytics --configuration releaseRuntimeClasspath
> ```

These changes are made to the Android project's Gradle files.

### Project-level `build.gradle.kts` (`<project>/build.gradle.kts`)

Add the latest version of the Crashlytics Gradle plugin to the `plugins` block:

```kotlin
plugins {
    // ... other plugins

    // [AGENT] Fetch the latest resolved version using the Gradle command above
    id("com.google.firebase.crashlytics") version "<latest_plugin_version>" apply false
}
```

### Module (app-level) `build.gradle.kts` (`<project>/<app-module>/build.gradle.kts`)

1. Add the Crashlytics Gradle plugin to the `plugins` block:

   ```kotlin
   plugins {
       // ... other plugins

       id("com.google.firebase.crashlytics")
   }
   ```

1. Add the Firebase Crashlytics dependency to the `dependencies` block:

   ```kotlin
   dependencies {
       // ... other dependencies

       // [AGENT] Fetch the latest resolved version using the Gradle command above
       implementation(platform("com.google.firebase:firebase-bom:<latest_bom_version>"))

       // Add the dependency for the Firebase Crashlytics library
       // When using the BoM, don't specify versions in Firebase library dependencies
       implementation("com.google.firebase:firebase-crashlytics")
   }
   ```

______________________________________________________________________

## 2. *Optional:* Install the NDK SDK to capture native crashes

If the Android project uses native code (C/C++), or includes a library with
native code, configure Crashlytics to report native crashes.

App-level `build.gradle.kts` (`<project>/<app-module>/build.gradle.kts`)

1. Add the `firebase-crashlytics-ndk` dependency:

   ```kotlin
   dependencies {
       // ... other dependencies

       // [AGENT] Fetch the latest resolved version using the Gradle command above
       implementation(platform("com.google.firebase:firebase-bom:<latest_bom_version>"))

       // Add the dependency for the Firebase Crashlytics NDK library
       // When using the BoM, don't specify versions in Firebase library dependencies
       implementation("com.google.firebase:firebase-crashlytics-ndk")
   }
   ```

1. Enable the `nativeSymbolUpload` flag in the `buildTypes` configuration. This
   will automatically upload symbol files for the native code, which are
   required to symbolicate native crash reports.

   ```kotlin
   android {
       // ... other config
       buildTypes {
           getByName("release") {
               // ...
               firebaseCrashlytics {
                   nativeSymbolUploadEnabled = true
               }
           }
       }
   }
   ```

After these changes, Crashlytics will automatically report crashes in the app's
native code.

______________________________________________________________________

## 3. *Required:* Force a test crash

To verify that Crashlytics is correctly set up in the Android project, force a
test crash in the app.

1. Add code to the main activity (e.g., in `onCreate`) to trigger a crash a few
   seconds after app startup:

   ```kotlin
   import android.os.Handler
   import android.os.Looper

   // ... in the Activity's onCreate method or similar startup logic
   Handler(Looper.getMainLooper()).postDelayed({
       throw RuntimeException("Test Crash") // Force a crash after 3 seconds
   }, 3000)
   ```

1. Run the app on a device or emulator. The app should crash after a short
   delay.

1. Restart the app. The Crashlytics SDK will send the crash report to Firebase
   on the next app launch.

1. After a few minutes, the crash should be available in Firebase.

   - If the Firebase MCP server is installed, use the `get_report` tool to
     verify that a crash was received.
   - As a fallback, tell the human user to go to the Crashlytics dashboard in
     the Firebase console to verify the new crash report. Provide the human user
     with a constructed Firebase console URL using the Firebase PROJECT_ID and
     the PACKAGE_NAME:
     `https://console.firebase.google.com/u/0/project/PROJECT_ID/crashlytics/app/android:PACKAGE_NAME/issues`

1. After verifying that Firebase has received the crash report -- either using
   the `get_report` tool or manually viewing it in the Firebase console --
   remove the code that triggers the test crash.

______________________________________________________________________

## Optional additional steps

### Add custom debugging information

Customize reports to help better understand what's happening in the app and the
circumstances around events reported to Crashlytics. See
https://firebase.google.com/docs/crashlytics/android/customize-crash-reports.md.txt.

# Firebase Crashlytics iOS Setup Guide

Important references:

- Refer to the `firebase-basics` skills, particularly those for iOS setup,
  before proceeding.
- Refer to the `xcode-project-setup` skills.

## Project and App Setup

Use the `firebase-tools` CLI to set up the project if necessary.

1. **Find Bundle ID:** Read the Xcode project to find the iOS bundle ID. Check
   the `PRODUCT_BUNDLE_IDENTIFIER` value in the `.pbxproj` file or the
   `Info.plist` file.
1. **Create Firebase Project:** If no project exists, create one:
   `npx -y firebase-tools@latest projects:create <project-id> --display-name="My Awesome App"`
1. **Create Firebase App:** Register the iOS app with the discovered bundle ID:
   `npx -y firebase-tools@latest apps:create IOS <display-name> --bundle-id=<bundle-id>`
1. **Link the GoogleService-Info.plist file:** Use the script in the
   `xcode-project-setup` skill to obtain the config and link.

## Add Swift Package Dependencies

Install the Crashlytics SDK using the Swift package manager, or the script in
the `xcode-project-setup` skill.

Install the `FirebaseCrashlytics` package from the
`https://github.com/firebase/firebase-ios-sdk.git` repository.

## Initialize Firebase in App Code

Modify the application's entry point to initialize Firebase. Refer to the iOS
setup reference in the `firebase-basics` skill.

## Add dSYM Upload Script

Add a Run Script phase to the main app target in Xcode. This step is required to
upload dSYM files for crash symbolication.

1. **Debug Information Format**: The `Debug Information Format` in Build
   Settings must be set to `DWARF with dSYM File`.
1. **Run Script Content**: A new "Run Script Phase" should be added to the
   target's "Build Phases" with the following content:
   ```bash
   ${BUILD_DIR%/Build/*}/SourcePackages/checkouts/firebase-ios-sdk/Crashlytics/run
   ```

When using the `xcode-project-setup` skills, the above two steps will be done as
part of adding the `FirebaseCrashlytics` package. Once the skill has been
invoked and succeeded, verify that the app's project.pbxproj file contains a Run
Script Build phase where the shell script attribute value contains
'Crashlytics'. Specifically, there should be a `PBXShellScriptBuildPhase`
section with the attribute `shellScript` that is set to a value that contains
`Crashlytics/run` and an attribute `inputPaths` where one of the values contains
`GoogleService-Info.plist`. If verification is not successful, present the above
two options to be done manually.

## Follow up Steps

### Required: Force a Test Crash

1. Add code to trigger a crash a few seconds after app startup to verify
   Crashlytics setup.

**For SwiftUI Apps (in `AppDelegate.swift`):**

*File: `AppDelegate.swift`*

```swift
import UIKit
import FirebaseCore
import Dispatch // For DispatchQueue

// ...

class AppDelegate: NSObject, UIApplicationDelegate {
  func application(_ application: UIApplication,
                   didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey : Any]? = nil) -> Bool {
    FirebaseApp.configure()
    // Force a crash after a delay to test Crashlytics
    DispatchQueue.main.asyncAfter(deadline: .now() + 3) {
        fatalError("Test Crash")
    }
    return true
  }
}
```

2. Run your app on a device or simulator. If running in the iOS simulator, make
   sure that the Xcode debugger is disconnected, otherwise the crash will not
   make it to Crashlytics. The app should crash after a short delay.

1. Restart the app. The Crashlytics SDK will send the crash report to Firebase
   on the next app launch.

1. After a few minutes, the crash should be available in the Firebase console.
   Go to **DevOps & Engagement** > **Crashlytics** to view your dashboard and
   crash reports.

- If the Firebase MCP server is installed, use the `get_report` tool to check
  that a crash was received.
- As a fallback, visit the Crashlytics dashboard in the Firebase console to see
  the new crash report.

5. After verifying that Firebase has received the crash report - either using
   the `get_report` tool or manually viewing it in the Firebase console - remove
   the code from step 1 that triggers the crash. This prevents the application
   from always crashing on start up after a delay.

### Optional: Add custom debugging information

Customize reports to help you better understand what's happening in your app and
the circumstances around events reported to Crashlytics. See
[Customize Crash Reports for Apple Platforms](https://firebase.google.com/docs/crashlytics/ios/customize-crash-reports.md).

---
name: firebase-crashlytics
description: Comprehensive guide for Firebase Crashlytics, including provisioning and SDK usage. Use this skill when the user needs help setting up Crashlytics, adding crash reporting, or using the Crashlytics SDK in their application.
compatibility: This skill is best used with the Firebase CLI, but does not require it. Firebase CLI can be accessed through `npx -y firebase-tools@latest`.
metadata:
  author: Google LLC
  category: CloudObservabilityAndMonitoring
---

# Crashlytics

This skill provides a complete guide for getting started with Crashlytics on
Android or iOS. Crash data collected from client applications can be read using
the MCP server in the Firebase CLI.

## Prerequisites

Provisioning Crashlytics requires both a Firebase project and a Firebase app,
either Android or iOS. To read the data collected by Crashlytics, install the
MCP server in the Firebase CLI. See the `firebase-basics` skill for references.

## SDK Setup

To learn how to setup Crashlytics in your application code, choose your
platform:

- **Android**: [android_setup.md](references/android_setup.md)
- **iOS**: [ios_setup.md](references/ios_setup.md)

## SDK Usage

The SDK provides a number of features to make crash reports more actionable.

- Add custom keys
- Add custom logs
- Set user identifiers
- Report non-fatal exceptions

To learn how to customize crash reports and add additional debugging data,
consult the documentation for your platform.

- **Android**:
  [Customize Crash Reports for Android](https://firebase.google.com/docs/crashlytics/android/customize-crash-reports.md)
- **iOS**:
  [Customize Crash Reports for Apple Platforms](https://firebase.google.com/docs/crashlytics/ios/customize-crash-reports.md)