Android SDK integration

Add Bugsnag to your Android SDK projects to automatically capture and report crashes in Java and Kotlin applications.

New to Bugsnag? Create an account now.


Using Android Studio or Gradle

Add the following dependency to your Project Gradle Settings in <project_dir>/build.gradle:

buildscript {
    dependencies {
        // ...
        classpath 'com.bugsnag:bugsnag-android-gradle-plugin:4.+'

Note: If you are using version 2.x of the Android Plugin for Gradle you must use v2.5.0 of the Bugsnag plugin for compatibility.

Add the following dependencies to your Module Gradle Settings, usually found at <project_dir>/app/build.gradle:

apply plugin: ''
apply plugin: ''

dependencies {
    // ...
    implementation 'com.bugsnag:bugsnag-android:4.+'

Using Maven

Add bugsnag-android as a dependency in your pom.xml:


Manual AAR installation

Download the latest release and place it in your app’s libs folder. Then add flatDirs as a repository and the archives to your module-level gradle settings:

repositories {
    flatDir {
        dirs 'libs'
dependencies {
    compile(name:'bugsnag-android', ext:'aar')

Basic configuration

Set your API key

Configure your integration API key in the <application> tag of your App Manifest file.

<application ...>
    <meta-data android:name="" android:value="your-api-key-here"/>

You can find your integration API key immediately after creating a new project from your Bugsnag dashboard, or later on your project’s settings page.

Initialize the Bugsnag client

Initialize Bugsnag in the onCreate callback of your Application subclass:

public class MyApp extends Application {
    public void onCreate() {

If you’re creating a custom Application class for the first time, make sure to specify the subclass name in your AndroidManifest.xml:


Further configuration

If you’d like to configure Bugsnag further, check out the configuration options reference.

Showing full stacktraces

If you use a tool to minifiy and optimize your application you will need to upload a mapping file to see full debugging information in error reports including the original class and method names.

Mapping files generated by ProGuard, DexGuard, and R8 are supported.

By default the Gradle plugin will automatically upload the mapping file for every build. See the Android mapping guide for more details.

Reporting unhandled exceptions

After completing installation and basic configuration, unhandled exceptions and ANRs will be automatically reported to your Bugsnag dashboard.

Reporting handled exceptions

If you would like to send handled exceptions to Bugsnag, you can pass any Throwable object to the Bugsnag.notify method:

try {
    // Some potentially crashy code
} catch (Throwable exception) {

Adding diagnostics or adjusting severity

It can often be helpful to adjust the severity or attach custom diagnostics to handled exceptions. For more information, see reporting handled errors.

Sending diagnostic data

Automatically captured diagnostics

Bugsnag will automatically capture and attach the following diagnostic data to every exception report:

  • A full stacktrace
  • Application information (package name, app name, version)
  • Application state (time in foreground, active screen, memory usage)
  • Device information (manufacturer, brand, model, total memory)
  • Screen information (density, dpi, resolution, orientation)
  • System information (android version, locale, rooted state, free memory, free disk space)
  • Battery status (battery level, charging state)
  • Network status (network type, network state)

Attaching custom diagnostics

It can often be helpful to attach application-specific diagnostic data to exception reports. This can be accomplished by setting a callback which will be invoked before any reports are sent to Bugsnag:

Bugsnag.beforeNotify(new BeforeNotify() {
    public boolean run(Error error) {
        // Attach customer information to every error report
        error.addToTab("account", "name", "Acme Co.");
        error.addToTab("account", "paying_customer", true);

        return true;

For more information, see customizing error reports.

Identifying users

In order to correlate errors with customer reports, or to see a list of users who experienced each error, it is helpful to capture and display user information.

This can be accomplished as follows:

Bugsnag.setUser("123456", "", "James Smith");

For more information, see configuration options.

Session tracking

Bugsnag tracks the number of “sessions” that happen within your application. This allows you to compare stability scores between releases and helps you to understand the quality of your releases.

Sessions are captured and reported by default. This behaviour can be disabled using the setAutoCaptureSessions configuration option.

Bugsnag will automatically report a session each time an Activity is in the Started state, 30 seconds after all Activities have remained in the Stopped state.

If you want control over what is deemed a session, you can switch off automatic session tracking with the setAutoCaptureSessions option, and manage the session lifecycle using startSession(), stopSession() and resumeSession().

Logging breadcrumbs

In order to understand what happened in your application before each crash, it can be helpful to leave short log statements that we call breadcrumbs. The last several breadcrumbs are attached to a crash to help diagnose what events lead to the error.

Automatically captured breadcrumbs

By default, Bugsnag captures common events including:

  • Activity Lifecycle callbacks
  • Network connectivity changes
  • Bluetooth connectivity changes
  • Battery state changes
  • Device rotation
  • Media Scanner events
  • Telephony events
  • Other device metrics and more

Attaching custom breadcrumbs

Leaving breadcrumbs can be accomplished as follows:

Bugsnag.leaveBreadcrumb("App loaded");
Bugsnag.leaveBreadcrumb("User clicked a button");

When logging breadcrumbs, we’ll keep track of the timestamp, and show both the message and timestamp on your dashboard.

Additional data can be attached to breadcrumbs by using the longer form of leaveBreadcrumb:

Map<String, String> metadata = new HashMap<>();
metadata.put("from", "moka");
metadata.put("to", "french press");
Bugsnag.leaveBreadcrumb("Preference updated", BreadcrumbType.STATE, metadata);

Individual breadcrumb size is limited to 4kb after serialization. Any larger breadcrumbs will be dropped from the payload while logging a warning.

Filtering breadcrumbs

You can register a callback which is executed each time a breadcrumb is captured using beforeRecordBreadcrumb. This can be helpful if you wish to filter out certain automatic breadcrumbs from your application, for example:

Bugsnag.beforeRecordBreadcrumb(new BeforeRecordBreadcrumb() {
    public boolean shouldReport(@NonNull Breadcrumb breadcrumb) {
        if (breadcrumb.getName().equals("Noisy breadcrumb")) {
            return false; // ignore the breadcrumb
        } else {
            return true; // capture the breadcrumb

Fragment Lifecycles

If you wish to log Breadcrumbs for the Fragment Lifecycle, we suggest that you use FragmentLifecycleCallbacks for all the activities which you wish to track.

public class MyActivity extends FragmentActivity {
    protected void onStart() {
            .registerFragmentLifecycleCallbacks(new FragmentBreadcrumbLogger(), true);

public class FragmentBreadcrumbLogger extends FragmentManager.FragmentLifecycleCallbacks {

    private static final String FRAG_LIFECYCLE_CALLBACK = "FragmentLifecycleCallback";

    public void onFragmentCreated(FragmentManager fm, Fragment f, Bundle savedInstanceState) {
        leaveLifecycleBreadcrumb(f, "onFragmentCreated()");

    // leave Breadcrumbs in other lifecycle callbacks if needed

    private void leaveLifecycleBreadcrumb(Fragment fragment, String lifecycleCallback) {
        // note - if proguard is enabled you may want to use a different method of obtaining
        // the current fragment's name
        String fragmentName = fragment.getClass().getSimpleName();

        Map<String, String> metadata = new HashMap<>();
        metadata.put(FRAG_LIFECYCLE_CALLBACK, lifecycleCallback);
        Bugsnag.leaveBreadcrumb(fragmentName, BreadcrumbType.NAVIGATION, metadata);

Next steps

  • View bugsnag-android, the library powering Bugsnag for Android, on GitHub
  • Get support for your questions and feature requests