Android mapping upload

Upload Android mapping files to allow Bugsnag to de-obfuscate your Android stack traces.

Overview

For Android applications, developers have the option to use ProGuard or the Jack Toolchain to reduce app size and to prevent others from reverse engineering source code.

This will cause class names, method names, and variable names to become obfuscated, which makes debugging harder and causes error grouping problems for Bugsnag.

In order to replace the obfuscated data with a human-readable stack trace, Bugsnag can use a mapping file.

ProGuard or Jack

By default Android applications are shrunk/obfuscated using ProGuard which has been the primary Android optimizer for some time. It is possible to control the way that ProGuard operates by using ProGuard configuration files.

Jack is a new Android toolchain that compiles Java source directly into Android dex bytecode. There are a few advantages to using Jack including the ability to use Java 8 Language Features. The Jack toolchain optimizes code in a similar way to ProGuard, using the same configuration files (but it does not support all of the options), and producing similar mapping files.

Gradle plugin

If you’re using Android Studio/Gradle to build your Android projects, the best way to send your mapping files to Bugsnag is to use the Bugsnag Android Gradle plugin.

ProGuard settings

We use the line numbers of crashes to help with error grouping. You’ll need explicitly to tell ProGuard to not strip this information by adding the following line to your ProGuard configuration:

-keepattributes LineNumberTable,SourceFile

If you are using our Gradle plugin, this will automatically be added to your ProGuard config.

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).

Jack settings

When configuring using Jack add the following lines to your gradle configuration:

jackOptions {
    enabled true
    additionalParameters("jack.dex.debug.lines": "true")
    additionalParameters("jack.dex.debug.source": "true")
}

and the following to your ProGuard configuration:


-keepattributes LineNumberTable,SourceFile

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.

Uploading mapping files

In cases where you cannot use our Gradle plugin, you’ll need to manually upload your mapping file to Bugsnag using our API.

To send mapping files to Bugsnag, simply POST them to https://upload.bugsnag.com with the following parameters:

For ProGuard

  • proguard - the path to the ProGuard mapping file.
  • apiKey - your Bugsnag integration API key for this application.
  • appId - the Android applicationId for this application.
  • versionCode - the Android versionCode for this application release.
  • versionName (optional) - the Android versionName for this application release, used when displaying the version.
  • buildUUID (optional) - a UUID to identify this builds. This is required if you build multiple different apps with the same appId and versionCode. If you use this, you’ll also need to use setBuildUUID() in your app.
  • overwrite (optional) - overwrite any existing ProGuard mappings for this version of your app.

For the Jack Toolchain

  • jack - the path to the Jack mapping file.
  • apiKey - your Bugsnag integration API key for this application.
  • appId - the Android applicationId for this application.
  • versionCode - the Android versionCode for this application release.
  • versionName (optional) - the Android versionName for this application release, used when displaying the version.
  • buildUUID (optional) - a UUID to identify this builds. This is required if you build multiple different apps with the same appId and versionCode. If you use this, you’ll also need to use setBuildUUID() in your app.
  • overwrite (optional) - overwrite any existing ProGuard mappings for this version of your app.

cURL example

Here’s an example request with curl:

$ curl https://upload.bugsnag.com/ \
    -F proguard=@/path/to/mapping.txt \
    -F apiKey=YOUR_API_KEY_HERE \
    -F versionCode=123 \
    -F appId=com.example.android.app \
    -F versionName=2.3.0

Response codes

If the file is accepted then an HTTP 200 response will be returned with the body “OK”.

If not, there are several possible problems which will be indicated with an HTTP 4XX response:

  • duplicate proguard file - indicates that Bugsnag already has a file. You can ignore this error by using the buildUUID parameter, or by using the overwrite parameter.
  • proguard file generated without -keepattributes LineNumberTable - indicates that your ProGuard configuration will not work with Bugsnag. See the Mapping settings section of the Android guide.
  • invalid apiKey - indicates that the provided apiKey doesn’t correspond to a Bugsnag project.
  • missing param - indicates that the appId or versionCode parameters are missing.