Android mapping support

Upload your Android mapping files to Bugsnag.

Overview

If you are using ProGuard or DexGuard to shrink your app, this will cause method and class names to become obfuscated, which makes debugging harder as the original file names, line numbers, and method names are not available.

Bugsnag can use a mapping file to replace the obfuscated data with a human-readable stack trace. The Android gradle plugin automatically uploads your mapping file for each release build.

For NDK applications, a shared object mapping file is used to display the original code locations.

Gradle Plugin Setup

Add the following dependency to your buildscript classpath, at <project_dir>/build.gradle:

buildscript {
    dependencies {
        classpath 'com.bugsnag:bugsnag-android-gradle-plugin:3.+'
    }
}

Apply the plugin on the last line of your module’s build.gradle file, at <project_dir>/<module_name>/build.gradle:

apply plugin: 'com.bugsnag.android.gradle' // apply on last line

Don’t forget to run Sync Project with Gradle Files after updating these files.

Further Configuration

In most situations, the basic installation steps above will suffice, but you can manually configure further settings as follows:

API Key

By default this plugin will read your API key from your manifest. You should ensure that you have the following code in AndroidManifest.xml.

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

Alternatively, you can set your API key in your app’s build.gradle as follows:

bugsnag {
    apiKey 'your-api-key-here'
}

Automatic Upload

By default, this plugin will automatically upload the ProGuard mapping file generated for every non-debug build. If you’d prefer to disable this automatic uploading, set the autoUpload property in your app’s build.gradle:

bugsnag {
    autoUpload false
}

If you disable automatic uploading, you can still run the upload task manually, with the uploadBugsnagVariantOutputMapping task.

./gradlew clean build uploadBugsnag${variantOutputName}Mapping

For example, the following command would upload the release mapping file for the x86 split of the javaExample productFlavor in the example module:

./gradlew clean build :example:uploadBugsnagJavaExample-x86-releaseMapping

Automatic ProGuard Config

In order for Bugsnag to de-duplicate errors correctly, it needs to know the file and line number for every crash. ProGuard strips this information by default, so we’ll automatically add the following line into your ProGuard configuation to avoid this:

-keepattributes SourceFile,LineNumberTable
-keep class com.bugsnag.android.NativeInterface { *; }
-keep class com.bugsnag.android.Breadcrumbs { *; }
-keep class com.bugsnag.android.Breadcrumbs$Breadcrumb { *; }
-keep class com.bugsnag.android.BreadcrumbType { *; }
-keep class com.bugsnag.android.Severity { *; }
-keep class com.bugsnag.android.ndk.BugsnagObserver { *; }

If you’d prefer to add this into your ProGuard configuration yourself, you can disable our automatic configuration in your app’s build.gradle as follows:

bugsnag {
    autoProguardConfig false
}

Custom Endpoints

By default, we’ll upload mapping files to upload.bugsnag.com, if you are using Bugsnag On-premise, you can configure your upload endpoint in your app’s build.gradle as follows:

bugsnag {
    endpoint 'https://upload.bugsnag.example.com'
}

Disabling Bugsnag

To completely disable the Bugsnag plugin, use the extension property enableBugsnag, for example:

android {
    buildTypes {
        debug {
            ext.enableBugsnag = false
        }
    }
}

NDK Support

Bugsnag supports uploading NDK shared object symbol mappings as well as ProGuard mappings. If you are using the Native Development Kit, enable symbol upload as follows:

bugsnag {
  ndk true
}

Overwrite mapping file

To overwrite a mapping file, you can set the overwrite property as follows:

bugsnag {
    overwrite false
}

You can also declare this inside a product flavor. Conflicting values (between multiple flavors or a flavor and a build-type) are ignored and the plugin will be disabled if false was set anywhere.

You may want to do this to speed up build types or flavors where you don’t require Bugsnag’s functionality. Bugsnag’s generation of a UUID for each build into your manifest (see Build UUIDs) causes the resources task to be run for each build, introducing a small delay if your build’s changes don’t involve resources.

Retrying the file upload

To enable retrying the file upload, set the retryCount property:

bugsnag {
    retryCount 5
}

Build UUIDs

This plugin automatically generates a UUID for each build (excluding Instant Run builds, which is inserted into your AndroidManifest.xml during the build process. This UUID is used to uniquely identify each build, along with your appId and versionCode, to help us determine which ProGuard mapping file to use with each crash report.

This UUID is available as com.bugsnag.BUILD_UUID in a meta-data element in case you’d like to use yourself it in your applications.

Manually uploading mapping files

In cases where you are not using Gradle, you’ll need to manually upload your mapping file to Bugsnag using our API. See the Android Mapping Upload API reference for more details.

Proguard Settings

If you are using proguard-android-optimize.txt settings then Bugsnag will convert the stack traces to a human-readable format, but the original file names might not be available (class name will be used instead of file name in this case).

If the stack traces provided to Bugsnag do not contain a valid file, then we will use the unqualified class name in place of the file name.