Android integration guide

Add Bugsnag to your Android projects to automatically capture and report crashes in released applications.

Installation

Using Android Studio or Gradle

Add bugsnag-android to the dependencies section of your Module Gradle Settings, usually found at <project_dir>/app/build.gradle:

compile 'com.bugsnag:bugsnag-android:3.6.0'

Don’t forget to run Sync Project with Gradle Files after updating this file.

Using Maven

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

<dependency>
    <groupId>com.bugsnag</groupId>
    <artifactId>bugsnag-android</artifactId>
</dependency>

Manual AAR installation

Download the latest release and place it in your app’s libs folder.

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="com.bugsnag.android.API_KEY" android:value="your-api-key-here "/>
</application>

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

Import the Bugsnag package in your Application subclass:

import com.bugsnag.android.*;

In your application’s onCreate function, initialize Bugsnag:

Bugsnag.init(this);

Further configuration

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

Configuring ProGuard

If you are using ProGuard to shrink your app, this will cause method and class names to become obfuscated, which makes debugging harder, and causes error grouping problems for Bugsnag.

In order to replace the obfuscated data with a human-readable stack trace, Bugsnag can use a ProGuard mapping file, check out our ProGuard guide for more details.

Reporting unhandled exceptions

After completing installation and basic configuration, unhandled exceptions 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) {
    Bugsnag.notify(exception);
}

Addding 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 as follows:

Bugsnag.beforeNotify(new BeforeNotify() {
    @Override
    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@acme.co", "James Smith");

For more information, see configuration options.

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.

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:

HashMap<String, String> metadata = new HashMap<String, String>();
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.

Next steps

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