BugSnag is now Insight Hub - we're making some changes to how the product looks, but this won't impact the way you use BugSnag or any of your integrations.

Gradle plugin

Upload ProGuard, DexGuard, and R8 mappings, NDK symbol files and report builds to BugSnag using our lightweight Gradle plugin.

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 replaces the BugSnag Android Gradle plugin and is recommended for most apps.

Installation

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

plugins {
    id("com.android.application")
    id("com.bugsnag.gradle") version "0.+"
}
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"
}
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
}
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"
        }
    }
}
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()
// 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 native API in your native Android code, we recommend using Prefabs to link the library and header files required to build your app against.

If you are unable to use Prefabs, the enableLegacyNativeExtraction option will perform the extraction of the library and header files for use in your build. See Native API configuration for further details.