Gradle (Android)

Upload ProGuard, DexGuard, and R8 mappings, NDK symbol files, React Native source maps, and report builds to Bugsnag using our Gradle plugin for Android.

Use our Gradle plugin to:

  • Upload JVM mappings (ProGuard, DexGuard, or R8), NDK shared object mappings, and source maps (for React Native).
  • 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.

Note: If you are building your Android project from Unity, our integration documentation is here.

Installation

Add the following dependency to <project_dir>/build.gradle:

buildscript {
    dependencies {
        // ...
        classpath "com.bugsnag:bugsnag-android-gradle-plugin:5.+"
    }
}

If you are using Android Gradle plugin version 7 (beta04+) in your project, use version 7.0.0-beta01 of our plugin.

Apply the plugin in your module’s build.gradle file, at <project_dir>/<module_name>/build.gradle:

apply plugin: "com.android.application"
// Apply the Bugsnag plugin
apply plugin: "com.bugsnag.android.gradle"
// ...

By default the Bugsnag plugin is disabled for debug build variants (specifically, any build variant with “debug” in the name). To improve your project’s build performance you should disable the plugin for any project-specific build variants that do not require deobfuscated stack traces in Bugsnag. This can be achieved by providing your own variant filter in your module’s build.gradle file:

bugsnag {
    variantFilter { variant ->
        // disables plugin for all variants of the 'staging' productFlavor
        def name = variant.name.toLowerCase()
        if (name.contains("staging") || name.contains("debug")) {
            enabled = false
        }
    }
}

Finally, 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.

DexGuard

If you are using DexGuard you must add the following to your project’s keep rules:

-keepresourcexmlelements AndroidManifest.xml

This prevents DexGuard from obfuscating a meta-data element that Bugsnag uses to identify the correct mapping file for each artefact.

Basic configuration

By default the plugin automatically uploads ProGuard, DexGuard, R8, NDK, and Unity library mapping files for each build variant. Bugsnag also reports build metadata such as version and source control information that is used to link to source code from the dashboard.

You can disable automatic upload via the bugsnag extension:

bugsnag {
    uploadJvmMappings = false // disables upload of ProGuard/DexGuard/R8 mapping files
    uploadNdkMappings = false // disables upload of NDK mapping files
    uploadNdkUnityLibraryMappings = false // disables upload of Unity library mapping files
    reportBuilds = false // disables upload of build metadata
}

Automatic upload of JS sourcemaps for React Native projects can also be enabled via the bugsnag extension:

bugsnag {
    uploadReactNativeMappings = true // enables upload of React Native source maps
}

Manual upload

It is possible to disable automatic upload if you wish to perform custom logic before uploading mapping files, such as running pre-release checks on an APK. In this scenario you can invoke upload tasks manually:

./gradlew uploadBugsnag${variantOutputName}Mapping # uploads JVM mapping files for a build variant
./gradlew uploadBugsnagNdk${variantOutputName}Mapping # uploads NDK mapping files for a build variant
./gradlew uploadBugsnag${variantOutputName}SourceMaps # uploads React Native source maps for a build variant
./gradlew bugsnagRelease${variantOutputName}Mapping # uploads build metadata for a build variant

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

./gradlew :example:uploadBugsnagJavaExample-x86-releaseMapping

Endpoint configuration

If you are using Bugsnag On-premise you should alter the Upload API and Build API endpoints.

bugsnag {
    endpoint = "https://upload.bugsnag.example.com" // configures the Upload API endpoint
    releasesEndpoint = "https://bugsnag-build.example.com" // configures the Build API endpoint
}

For further options see advanced configuration.

Additional configuration

Advanced ProGuard, DexGuard, and R8 mappings upload configuration

Retrying the file upload

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

bugsnag {
    retryCount = 5
}

Altering the HTTP request timeout

To alter the timeout of HTTP requests, set the requestTimeoutMs property:

bugsnag {
    requestTimeoutMs = 5000L
}

By default, requests timeout after 60000 milliseconds.

Project root

In NDK stacktraces the project’s root directory is used to highlight in-project stack frames and improves grouping. If you want code outside of your project root to be considered in-project, set the projectRoot property:

bugsnag {
    projectRoot = "/Users/joebloggs/my-app"
}

Shared object paths

The Bugsnag Plugin will automatically upload mapping files for shared objects in the default Android build directory. If you have additional shared object files in non-standard build directories, mapping files can be uploaded by adding them to the sharedObjectPaths property:

def paths = [
    new File("app/build/jni/libs"),
    new File("app/build/someOtherFolder")
]
bugsnag {
    sharedObjectPaths = paths
}

Objdump

The objdump command is used to generate symbol mappings for NDK. By default, the plugin will automatically calculate the paths of the executable and no additional configuration is needed. If necessary, the path can be overridden on a per ABI basis:

bugsnag {
    objdumpPaths = [
        "armeabi":     "/custom-location/ndk-bundle/armeabi-objdump",
        "armeabi-v7a": "/custom-location/ndk-bundle/armeabi-v7a-objdump",
        "arm64-v8a":   "/custom-location/ndk-bundle/arm64-v8a-objdump",
        "x86":         "/custom-location/ndk-bundle/x86-objdump",
        "x86_64":      "/custom-location/ndk-bundle/x86_64-objdump",
    ]
}

Fail On Upload Error

failOnUploadError stops the build when a mapping file fails to upload to Bugsnag successfully. By default, this value is set to true. If you wish to disable this behaviour, you should set the flag to false:

bugsnag {
    failOnUploadError = false
}

Overwrite mapping file

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

bugsnag {
    overwrite = true
}

Custom node_modules directory

If you upload React Native source maps and your node_modules are installed in a non-default directory, you should set the nodeModulesDir property as follows:

bugsnag {
    nodeModulesDir = new File("/custom-path/node_modules")
}

Advanced build reporting configuration

Builder

Set the name of the person or entity who built 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
}

Configuring a HTTP Proxy

To use a proxy you should configure the JVM’s networking properties in the gradle.properties file of your project:

systemProp.http.proxyHost=www.example.com
systemProp.http.proxyPort=8080
systemProp.http.proxyUser=my-user
systemProp.http.proxyPassword=my-password
systemProp.http.nonProxyHosts=*.example.com

After configuring this the plugin will route all its traffic through the proxy.

FAQ

Bugsnag Android Gradle Plugin throws a NoSuchMethodError

Some users have reported that the Bugsnag Android Gradle Plugin can throw a NoSuchMethodError:

Execution failed for task ':app:processBugsnagReleaseManifest'.
> okio.Okio.sink$default(Ljava/io/File;ZILjava/lang/Object;)Lokio/Sink;

This occurs when your project adds another gradle plugin to your buildscript classpath that itself has a dependency on a different version of the Okio library.

To resolve this issue (and any similar version mismatches), you should follow Gradle’s guide on altering the versions of transitive dependencies.