Edit

Android Deobfuscation

  • Article

Important

Visual Studio App Center is scheduled for retirement on March 31, 2025. While you can continue to use Visual Studio App Center until it is fully retired, there are several recommended alternatives that you may consider migrating to.

Learn more about support timelines and alternatives.

ProGuard, DexGuard and R8 are tools to optimize and obfuscate the code of Android apps. It removes unused code, renames classes, fields, and methods with semantically obscure names, making the code base smaller and harder to reverse engineer. To enable obfuscation with ProGuard or R8 in your Android app, follow the official Android Developer documentation.

With ProGuard, DexGuard or R8 enabled in your Android app, your stack traces must be deobfuscated. App Center automatically deobfuscates stack traces for your Java, Kotlin, and React Native Android apps when you upload the mapping.txt file created on each build. This file maps the original class, method, and field names to the obfuscated names making the stack traces readable.

The App Center Build and Distribution service can automatically generate mapping files and upload them to the Diagnostics service. If you use App Center to build and auto distribute your app to your end users, you don't need to manually obtain and upload the mapping files as detailed in the steps below.

Uploading the mapping.txt file

App Center Portal

  1. Download the mapping.txt file from your app module's build directory
  2. Log into App Center and select your app
  3. In the left menu, navigate to the Diagnostics section
  4. Select Mappings
  5. Click the Upload mappings button in the upper right
  6. Fill in the Version Name and Version Code (these must match that build's Gradle configuration in order for the mapping to work for a particular build)
  7. Upload the mapping.txt file from your app module's build directory.
  8. Click the Save button.

App Center API

The process for uploading mapping files through the API involves a series of three API calls: one to allocate space on our backend, one to upload the file, and one to update the status of the upload. The body of the first API call should set symbol_type to AndroidProguard, build and version properties that correspond to the Version Code and Version Name, respectively, as well as a file_name.

  1. Trigger a POST request to the symbol_uploads API. This call allocates space on our backend for your file and returns a symbol_upload_id and an upload_url property.
curl -X POST 'https://api.appcenter.ms/v0.1/apps/{owner_name}/{app_name}/symbol_uploads' \
    -H 'accept: application/json' \
    -H 'X-API-Token: {API TOKEN}' \
    -H 'Content-Type: application/json' \
    -d '{JSON BODY}'
  1. Using the upload_url property returned from the first step, make a PUT request with the header: "x-ms-blob-type: BlockBlob" and supply the location of your file on disk. This call uploads the file to our backend storage accounts. Learn more about PUT Blob request headers .
curl -X PUT '{upload_url}' \
    -H 'x-ms-blob-type: BlockBlob' \
    --upload-file '{path to file}'
  1. Make a PATCH request to the symbol_uploads API using the symbol_upload_id property returned from the first step. In the body of the request, specify whether you want to set the status of the upload to committed (successfully completed) the upload process, or aborted (unsuccessfully completed).
curl -X PATCH 'https://api.appcenter.ms/v0.1/apps/{owner_name}/{app_name}/symbol_uploads/{symbol_upload_id}' \
    -H 'accept: application/json' \
    -H 'X-API-Token: {API TOKEN}' \
    -H 'Content-Type: application/json' \
    -d '{ "status": "committed" }'

Note

The symbol uploads API doesn't work for files that are larger than 256MB. Use the App Center CLI to upload these files. You can install the App Center CLI by following the instructions in our App Center CLI repo.

App Center CLI

You can also use the CLI to upload mapping files:

appcenter crashes upload-mappings --mapping {mapping file} --version-name {version name} --version-code {version code}

Note

App Center can't check if you've uploaded the right mapping.txt file. We recommend uploading the file directly after you create the .apk file, or push it to your code repository if you want to upload it later.

Forwarding the mapping from a build in App Center

If a build is configured to produce a mapping.txt file, App Center builds produce the file as an available download. Automatically distributing the build or manually distributing it later will forward the mapping.txt file onto Diagnostics to deobfuscate incoming crash reports. It isn't needed to manually upload the mapping.txt file after distributing a build.

Deleting a mapping file

  1. Make a GET request to the symbols_list API. This retrieves the IDs for the mapping files you uploaded.
  2. Make a DELETE request to the symbols_upload API with the mapping file ID. This deletes the specified mapping file.