Android mapping upload

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

Overview

If you use a tool to minify and optimize your application you will need to upload a mapping file to see full debugging information in error reports including the original class and method names.

Mapping files generated by ProGuard, DexGuard and R8 are supported.

Automating uploads using BugSnag tools

See the Showing full stacktraces guide for instructions on setting up this upload in your build system using the BugSnag CLI or our Gradle plugin.

Manually uploading mapping files

In cases where you cannot use our tools, 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/proguard (or your on-premise equivalent) with the following parameters:

• proguard – the path to the ProGuard, DexGuard, or R8 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 set the com.bugsnag.android.BUILD_UUID value in your AndroidManifest.xml.
• overwrite (optional) – overwrite any existing ProGuard mappings for this version of your app.

cURL example

Here’s an example request with curl:

$ curl --http1.1 https://upload.bugsnag.com/proguard \
    -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 Proguard settings section above.
• 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.

ProGuard settings

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

-keepattributes LineNumberTable,SourceFile

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

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.