Gradle plugin (New)

Upload ProGuard, DexGuard, and R8 mappings, NDK symbol files and report builds to BugSnag using our lightweight Gradle plugin. (For AGP version 8+.)

Use our Gradle plugin to:

Upload JVM mappings (ProGuard, DexGuard, or R8) and NDK shared object mappings.
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.

The plugin is a thin wrapper for the BugSnag CLI executable and provides tasks and configuration hooks that your build tasks can depend on in order to incorporate BugSnag into your Gradle build. For more information on using the CLI directly, see our BugSnag CLI docs.

This plugin will soon be replacing our existing Android Gradle plugin, for apps using AGP v8.x+.

Installation

Apply the plugin in your app module, in <project_dir>/<module_name>/build.gradle:

plugins {
    id("com.android.application")
    id("com.bugsnag.gradle") version "0.+"
}

You can also apply the plugin project wide with the apply false syntax in the project level build script, avoiding the need to declare the versions in the module level build scripts.

Basic configuration

Ensure that your API key is present in the <application> section of your AndroidManifest.xml (see also the Basic configuration of the BugSnag Android SDK):

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

You can find your API key in Project Settings from your BugSnag dashboard.

Alternatively you can configure the API key via the bugsnag object in your Gradle scripts:

bugsnag {
    apiKey = "your-api-key-here"
}

See Configuration options for the full set of options configurable in this way.

Usage

The plugin provides the following tasks that you can add to the appropriate task dependencies in your project:

Upload ProGuard mapping

If you have obfuscation enabled in your app use the bugsnagUpload<Variant>ProguardMapping task to upload mapping files:

./gradlew assembleRelease bugsnagUploadReleaseProguardMapping

For further information, including available configuration options, see the Upload Android Proguard Mapping CLI command reference.

Upload NDK symbols

If there are native components in the build use the bugsnagUpload<Variant>NativeSymbols task to upload symbols from your native .so files:

./gradlew assembleRelease bugsnagUploadReleaseNativeSymbols

For further information, including available configuration options, see the Upload Android NDK CLI command reference.

Upload AAB

Use bugsnagUpload<Variant>Bundle task to upload ProGuard mappings and NDK symbols from an Android App Bundle (AAB), avoiding the need for separate commands:

./gradlew bundleRelease bugsnagUploadReleaseBundle

For further information, including available configuration options, see the Upload Android AAB CLI command reference.

Create build

Use bugsnagCreate<Variant>Build task to register a new release in your BugSnag dashboard:

./gradlew assembleRelease bugsnagCreateReleaseBuild

For further information, including available configuration options, see the Create Build CLI command reference.

Configuration options

Each of the above tasks passes configuration options from a bugsnag object in your Gradle script through to the BugSnag CLI. Please see the respective command reference page in our docs for a list of these options and how they are used.

bugsnag {
    overwrite = true
}

To set different configuration values for different build variants, add a variants object:

bugsnag {
    apiKey = "your-api-key-here"
    variants {
        release {
            apiKey = "second-api-key-here"
        }  
    }
}

Advanced options

CLI executable (`cliPath`)

Path to the BugSnag CLI binary to use. By default the executable bundled as part of the plugin is used, but this can be installed separately.

// use a bugsnag-cli bundled within your project:
bugsnag.cliPath = file("tools/bugsnag-cli").absolutePath

// use whatever bugsnag-cli is installed system-wide:
bugsnag.cliPath = bugsnag.systemCli()

Legacy native library extraction (`enableLegacyNativeExtraction`)

If you use the BugSnag NDK API but are not yet upgraded to bugsnag-android v6.x+, the libraries will need to be extracted from the BugSnag Android SDK for linking. This is no longer required in v6, but you can use the enableLegacyNativeExtraction option to perform this extraction if you are using v5.x or below. See Native API configuration for further details.