Get Android NDK crash reports

If your Android app contains native libraries, you can enable full stack traces and detailed crash reports for your native code from Firebase Crashlytics with a few small updates to your app's build configuration.

This guide describes how to configure crash reporting with the Firebase Crashlytics SDK for NDK.

If you're looking for how to get started with Crashlytics in your Unity projects, check out the Unity Getting Started guide.

Before you begin

1. If you haven't already, add Firebase to your Android project. If you don't have an Android app, you can download a sample app.

2. Recommended: To get features like crash-free users, breadcrumb logs, and velocity alerts, you need to enable Google Analytics in your Firebase project.

   • If your existing Firebase project doesn't have Google Analytics enabled, you can enable Google Analytics from the Integrations tab of your settings > Project settings in the Firebase console.

   • If you're creating a new Firebase project, enable Google Analytics during the project creation workflow.

Step 1: Add the Firebase Crashlytics SDK for NDK to your app

For an optimal experience with Crashlytics, we recommend enabling Google Analytics in your Firebase project and adding the Firebase SDK for Google Analytics to your app.

dependencies {
    // Import the BoM for the Firebase platform
    implementation platform('com.google.firebase:firebase-bom:30.1.0')

    // Declare the dependencies for the Crashlytics NDK and Analytics libraries
    // When using the BoM, you don't specify versions in Firebase library dependencies
    implementation 'com.google.firebase:firebase-crashlytics-ndk'
    implementation 'com.google.firebase:firebase-analytics'
}

dependencies {
    // Declare the dependencies for the Crashlytics NDK and Analytics libraries
    // When NOT using the BoM, you must specify versions in Firebase library dependencies
    implementation 'com.google.firebase:firebase-crashlytics-ndk:18.2.11'
    implementation 'com.google.firebase:firebase-analytics:21.0.0'
}

dependencies {
    // Import the BoM for the Firebase platform
    implementation platform('com.google.firebase:firebase-bom:30.1.0')

    // Declare the dependencies for the Crashlytics NDK and Analytics libraries
    // When using the BoM, you don't specify versions in Firebase library dependencies
    implementation 'com.google.firebase:firebase-crashlytics-ndk'
    implementation 'com.google.firebase:firebase-analytics-ktx'
}

dependencies {
    // Declare the dependencies for the Crashlytics NDK and Analytics libraries
    // When NOT using the BoM, you must specify versions in Firebase library dependencies
    implementation 'com.google.firebase:firebase-crashlytics-ndk:18.2.11'
    implementation 'com.google.firebase:firebase-analytics-ktx:21.0.0'
}

Step 2: Add the Firebase Crashlytics plugin to your app

1. In your project-level build.gradle file, add the Crashlytics Gradle plugin as a buildscript dependency.

   buildscript {
       repositories {
           // Check that you have Google's Maven repository (if not, add it).
           google()
       }
   
       dependencies {
           // ...
   
           // Check that you have the Google services Gradle plugin v4.3.2 or later
           // (if not, add it).
           classpath 'com.google.gms:google-services:4.3.12'
   
           // Add the Crashlytics Gradle plugin
           classpath 'com.google.firebase:firebase-crashlytics-gradle:2.9.1'
       }
   }
   
   allprojects {
       repositories {
           // Check that you have Google's Maven repository (if not, add it).
           google()
       }
   }

2. In your app-level build.gradle file, apply the Crashlytics Gradle plugin:

   apply plugin: 'com.android.application'
   apply plugin: 'com.google.gms.google-services' // Google services Gradle plugin
   
   // Apply the Crashlytics Gradle plugin
   apply plugin: 'com.google.firebase.crashlytics'
   

Step 3: Add the firebaseCrashlytics extension to your build

In your module (app-level) Gradle file (usually app/build.gradle), add the firebaseCrashlytics extension.

// ...

android {
  // ...
  buildTypes {
      release {
          // Add this extension
          firebaseCrashlytics {
              // Enable processing and uploading of native symbols to Firebase servers.
              // By default, this is disabled to improve build speeds.
              // This flag must be enabled to see properly-symbolicated native
              // stack traces in the Crashlytics dashboard.
              nativeSymbolUploadEnabled true
          }
      }
  }
}

// ...

android {
  // ...
  buildTypes {
      release {
          // Add this extension
          firebaseCrashlytics {
              // Enable processing and uploading of native symbols to Firebase servers.
              // By default, this is disabled to improve build speeds.
              // This flag must be enabled to see properly-symbolicated native
              // stack traces in the Crashlytics dashboard.
              nativeSymbolUploadEnabled true
          }
      }
  }
}

Step 4: Set up automatic uploading of native symbols

To produce readable stack traces from NDK crashes, Crashlytics needs to know about the symbols in your native binaries. The Crashlytics Gradle plugin includes the uploadCrashlyticsSymbolFileBUILD_VARIANT task to automate this process.

1. So that you can access the task for automated symbol uploading, make sure that nativeSymbolUploadEnabled is set to true in your module (app-level) Gradle file.

2. For method names to appear in your stack traces, you must explicitly invoke the uploadCrashlyticsSymbolFileBUILD_VARIANT task after each build of your NDK library. For example:

   >./gradlew app:assembleBUILD_VARIANT\
              app:uploadCrashlyticsSymbolFileBUILD_VARIANT
   

3. Both the Crashlytics SDK for NDK and the Crashlytics Gradle plugin depend on the presence of the GNU build ID within the native shared objects.

   You can verify the presence of this ID by running readelf -n on each binary. If the build ID is absent, add -Wl,--build-id to your build system's flags to fix the problem.

Step 5: Force a test crash to finish setup

To finish setting up Crashlytics and see initial data in the Crashlytics dashboard of the Firebase console, you need to force a test crash.

1. Add code to your app that you can use to force a test crash.

   You can use the following code in your app's MainActivity to add a button to your app that, when pressed, causes a crash. The button is labeled "Test Crash".

   Java

   Button crashButton = new Button(this);
   crashButton.setText("Test Crash");
   crashButton.setOnClickListener(new View.OnClickListener() {
      public void onClick(View view) {
          throw new RuntimeException("Test Crash"); // Force a crash
      }
   });
   
   addContentView(crashButton, new ViewGroup.LayoutParams(
          ViewGroup.LayoutParams.MATCH_PARENT,
          ViewGroup.LayoutParams.WRAP_CONTENT));
   

   Kotlin+KTX

   val crashButton = Button(this)
   crashButton.text = "Test Crash"
   crashButton.setOnClickListener {
      throw RuntimeException("Test Crash") // Force a crash
   }
   
   addContentView(crashButton, ViewGroup.LayoutParams(
          ViewGroup.LayoutParams.MATCH_PARENT,
          ViewGroup.LayoutParams.WRAP_CONTENT))
   

2. Build and run your app.

3. Force the test crash in order to send your app's first crash report:

   1. Open your app from your test device or emulator.

   2. In your app, press the "Test Crash" button that you added using the code above.

   3. After your app crashes, restart it so that your app can send the crash report to Firebase.

4. Go to the Crashlytics dashboard of the Firebase console to see your test crash.

   If you've refreshed the console and you're still not seeing the test crash after five minutes, enable debug logging to see if your app is sending crash reports.

And that's it! Crashlytics is now monitoring your app for crashes, and you can view and investigate crash reports and statistics in the Crashlytics dashboard.

Alternative options for uploading symbols

The main workflow on this page above is applicable for standard Gradle builds. However, some apps use a different configuration or tooling (for example a build process other than Gradle). In these situations, the following options might be helpful for successfully uploading symbols.

Option: Upload symbols for library modules and external dependencies

This option can be helpful in the following situations:

• If you use a customized NDK build process within Gradle
• If your native libraries are built in a library/feature module or provided by a third-party
• If the automatic symbol uploading task is failing or you're seeing unsymbolicated crashes in the dashboard

Option: Upload symbols for non-Gradle builds or inaccessible unstripped native libraries

This option can be helpful in the following situations:

• If you use a build process other than Gradle

• If your unstripped native libraries are provided to you in some way that they're not accessible during Gradle builds

Troubleshooting

If you're seeing different stack traces in the Firebase console and in the logcat, refer to the Troubleshooting guide.

Next steps

• Customize your crash report setup by adding opt-in reporting, logs, keys, and tracking of non-fatal errors.

• Integrate with Google Play so that you can filter your Android app's crash reports by Google Play track directly in the Crashlytics dashboard. This allows you to better focus your dashboard on specific builds.