Gradle (Android)

Upload ProGuard mappings, NDK symbol files, and report builds to Bugsnag using our Gradle plugin for Android.

Use our Gradle plugin to:

  • Upload ProGuard and DexGuard mappings as well as shared object file mappings (for C and C++) to deobfuscate stack traces and get human-readable function names, file paths, and line numbers.
  • Report information when you deploy your app to enable linking to code in your source control provider from the releases dashboard, timeline annotations, and stack traces.

Installation

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

buildscript {
    repositories {
        google()
        jcenter()
    }
    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

The current version of the Bugsnag plugin requires version 3.X of the Android Plugin for Gradle. We recommend that you migrate to 3.X, but if you still need to use 2.X, you will need to use v2.4.2 of the Bugsnag plugin for compatibility.

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

Basic configuration

By default, the Bugsnag Gradle plugin will read your API key from your manifest file.

Ensure your API key is present in the <application> section of your AndroidManifest.xml:

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

You can find your API key when creating a project in your Bugsnag dashboard, or later from your project settings page.

If you want to use a different API key than the one in your manifest file, you can override the value:

bugsnag {
    apiKey "your_api_key"
}

Uploading ProGuard mappings

By default, this plugin will automatically upload any ProGuard mapping file generated for every 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

For further options see advanced configuration.

Uploading NDK symbols

Bugsnag supports uploading NDK shared object symbol mappings as well as ProGuard mappings. If you are using the Native Development Kit, these are uploaded automatically for projects using externalNativeBuild.

To enable symbol map upload manually, set ndk to true in your bugsnag configuration block, and set the target path for your compiled shared object files using sharedObjectPath:

bugsnag {
    ndk true
    sharedObjectPath "app/build/jni/libs"
}

If you’d prefer to disable automatic uploading, set the ndk property in your app’s build.gradle:

bugsnag {
    ndk false
}

Reporting builds

By default, this plugin will automatically report builds to Bugsnag when you assemble a signed APK. This includes automatically detected version and source control information so Bugsnag can generate links to your source code from the dashboard.

If you’d prefer to disable this automatic uploading, set the autoReportBuilds property in your app’s build.gradle:

bugsnag {
    autoReportBuilds false
}

For further options see advanced configuration.

Additional configuration

Advanced ProGuard mappings upload configuration

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 configuration to avoid this:

-keepattributes SourceFile,LineNumberTable
-keep class com.bugsnag.android.NativeInterface { *; }
-keep class com.bugsnag.android.Breadcrumb { *; }
-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
}

Upload endpoint

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
        }
    }
}

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.

Overwrite mapping file

To overwrite when there is an existing mapping file, you can set the overwrite property as follows:

bugsnag {
    overwrite true
}

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 it yourself in your applications.

Advanced build reporting configuration

Builder

Set the name of the person or entity who build the app (defaults to whoami):

bugsnag {
    builderName "Joe Bloggs"
}

Source control

Source control values are automatically detected if Git is installed. If you want to override them you can set the following values:

Config Type Description
provider String The source control provider. This will be automatically detected from the repository URL where possible. If your provider is on-premise it can be set to one of ‘github-enterprise’, 'bitbucket-server’ or 'gitlab-onpremise’
repository String The repository URL.
revision String The commit hash of the code used to generate this build.
bugsnag {
    sourceControl {
        provider 'github-enterprise'
        repository 'https://github.com/org/repo'
        revision 'abcdef1'
    }
}

Metadata

Set the any metadata associated with the build that is useful to see against releases in Bugsnag. By default, Java, Gradle, and other data are captured, using the following keys:

"os_arch"
"os_name"
"os_version"
"java_version"
"gradle_version"
"git_version"

Additional metadata can be added via the metadata property:

bugsnag {
    def map = new HashMap()
    map.put("MyKey", "MyValue")
    metadata map
}

This will be added in addition to the default data. If you wish to override a default value, you can add a different value for its key in the Map:

bugsnag {
    def map = new HashMap()
    map.put("java_version", "[REDACTED]")
    metadata map
}

Build endpoint

By default, we’ll notify Bugsnag of new builds via the build.bugsnag.com endpoint. If you are using Bugsnag On-premise you can configure the endpoint as follows:

bugsnag {
    releasesEndpoint 'https://bugsnag-build.example.com'
}