Bugsnag Notifier for Android

Bugsnag for Android automatically detects crashes in your Android apps, collecting diagnostic information and immediately notifying your development team.

Create a free account to start capturing exceptions from your applications.

Installation

Using Android Studio or Gradle

Add bugsnag-android to the dependencies section in your build.gradle:

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

Using Maven

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

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

Using a Jar

• Download the latest bugsnag-android.jar
• Place it in your Android app's libs/ folder

Configuring Your AndroidManifest

• Configure your Bugsnag API key as meta-data in your manifest's <application> tag:

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

• Enable the INTERNET, ACCESS_NETWORK_STATE and GET_TASKS permissions:

  <!-- Required: Used to deliver Bugsnag crash reports -->
  <uses-permission android:name="android.permission.INTERNET"/>
  <!-- Optional: To provide network connectivity information to Bugsnag -->
  <uses-permission android:name="android.permission.ACCESS_NETWORK_STATE"/>
  <!-- Optional: To see which Activity was active at the time of a crash -->
  <uses-permission android:name="android.permission.GET_TASKS"/>

For a full example, see our example AndroidManifest.xml.

Initializing Bugsnag

• Import the Bugsnag package in your Application subclass:

  import com.bugsnag.android.*;

• In your application's onCreate function, initialize Bugsnag to begin capturing exceptions:

  Bugsnag.init(this);

Sending Custom Data With Exceptions

It is often useful to send additional meta-data about your app, such as information about the currently logged in user, along with any exceptions, to help debug problems. To add custom data to every exception you can use addToTab:

Bugsnag.addToTab("User", "Name", "Bob Hoskins");
Bugsnag.addToTab("User", "Paying Customer?", true);

You can also add custom data or modify error information before each exception is sent to Bugsnag using BeforeNotify callbacks. See beforeNotify below for details.

Logging Breadcrumbs

Bugsnag allows you to leave developer-defined log messages called "breadcrumbs" to help understand exactly what was happening in your application in the time before each crash.

When logging a breadcrumb, we'll keep track of the timestamp associated with the log message, and show both the message and timestamp on your dashboard.

To leave breadcrumbs, you can use leaveBreadcrumb:

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

By default, we'll store and send the last 20 breadcrumbs you leave before errors are sent to Bugsnag. If you'd like to increase this number, you can call setMaxBreadcrumbs:

Bugsnag.setMaxBreadcrumbs(50);

Sending Handled Exceptions

If you would like to send non-fatal exceptions to Bugsnag, you can pass any Throwable object to the notify method:

Bugsnag.notify(new Exception("Non-fatal"));

With Custom Data

You can also send additional meta-data with this exception:

import com.bugsnag.android.MetaData;

MetaData metaData = new MetaData();
metaData.addToTab("User", "username", "bob-hoskins");
metaData.addToTab("User", "email", "bob@example.com");

Bugsnag.notify(new Exception("Non-fatal"), metaData);

With a Severity

You can set the severity of an error in Bugsnag by including the severity option when notifying bugsnag of the error,

import com.bugsnag.android.Severity;

Bugsnag.notify(new Exception("Non-fatal"), Severity.INFO)

Valid severities are Severity.ERROR, Severity.WARNING and Severity.INFO.

Severity is displayed in the dashboard and can be used to filter the error list. By default all crashes (or unhandled exceptions) are set to Bugsnag.ERROR and all Bugsnag.notify calls default to Bugsnag.WARNING.

With Custom Data and Severity

You can send handled exceptions with both custom data and severity as follows:

import com.bugsnag.android.*;

MetaData metaData = new MetaData();
metaData.addToTab("User", "username", "bob-hoskins");

Bugsnag.notify(new Exception("Non-fatal"), Severity.INFO, metaData);

Configuration

###setContext

Bugsnag uses the concept of "contexts" to help display and group your errors. Contexts represent what was happening in your application at the time an error occurs. In an android app, it is useful to set this to be your currently active Activity.

If you enable the GET_TASKS permission, then this is set automatically for you. If you would like to set the bugsnag context manually, you can call setContext:

Bugsnag.setContext("MyActivity");

###setUser

Bugsnag helps you understand how many of your users are affected by each error. In order to do this, we need to send along user information with every exception.

If you would like to enable this, set the user. You can set the user id, which should be the unique id to represent that user across all your apps, the user's email address and the user's name:

Bugsnag.setUser("userId", "user@email.com", "User Name");

###setReleaseStage

If you would like to distinguish between errors that happen in different stages of the application release process (development, production, etc) you can set the releaseStage that is reported to Bugsnag.

Bugsnag.setReleaseStage("testing");

If you are running a debug build, we'll automatically set this to "development", otherwise it is set to "production".

###setNotifyReleaseStages

By default, we will notify Bugsnag of exceptions that happen in any releaseStage. If you would like to change which release stages notify Bugsnag of exceptions you can call setNotifyReleaseStages:

Bugsnag.setNotifyReleaseStages("production", "development", "testing");

###setFilters

Sets which values should be removed from any MetaData objects before sending them to Bugsnag. Use this if you want to ensure you don't send sensitive data such as passwords, and credit card numbers to our servers. Any keys which contain these strings will be filtered.

Bugsnag.setFilters(new String[]{"password", "credit_card_number"});

By default, filters is set to new String[] {"password"};

###setProjectPackages

Sets which package names Bugsnag should consider as "inProject". We mark stacktrace lines as in-project if they originate from any of these packages.

Bugsnag.setProjectPackages("com.company.package1", "com.company.package2");

By default, projectPackages is set to be the package you called Bugsnag.init from.

###setIgnoreClasses

Sets for which exception classes we should not send exceptions to Bugsnag.

Bugsnag.setIgnoreClasses("java.net.UnknownHostException", "com.example.Custom");

###setAppVersion

We'll automatically pull your app version from the versionName field in your AndroidManifest.xml file. If you'd like to override this you can call setAppVersion:

Bugsnag.setAppVersion("1.0.0-alpha");

Note: Bugsnag uses Semantic Versioning for app version sorting and filtering on the Bugsnag dashboard.

###setSendThreads

Sets if we should collect and send thread state along with errors.

Bt default sendThreads is set to true.

Bugsnag.setSendThreads(false);

###setEndpoint

Set the endpoint to send data to. By default we'll send reports to our standard https://notify.bugsnag.com endpoint, but you can override this if you are using Bugsnag Enterprise, to point to your own Bugsnag endpoint:

Bugsnag.setEndpoint("http://bugsnag.internal.example.com");

###beforeNotify

Add a "before notify" callback, to execute code before every notification to Bugsnag.

You can use this to add or modify information attached to an error before it is sent to your dashboard. You can also return false from any callback to halt execution.

Bugsnag.beforeNotify(new BeforeNotify() {
    public boolean run(Error error) {
        error.setSeverity(Severity.INFO);
        return true;
    }
});

Proguard

Bugsnag supports retracing Proguard stacktraces. This can be configured to work automatically using the bugsnag-android-gradle-plugin, or manually using the Bugsnag Proguard API.

Reporting Bugs or Feature Requests

Please report any bugs or feature requests on the github issues page for this project here:

https://github.com/bugsnag/bugsnag-android/issues

Contributing

We'd love to see your contributions! For information on how to build, test and release bugsnag-android, see our contributing guide.

License

The Bugsnag Android notifier is free software released under the MIT License. See LICENSE.txt for details.