Deobfuscation for Android

This guide explains how to deobfuscate crashes in your Android apps to get fully readable stack traces for Java, Kotlin and C++.

Deobfuscation requires uploading the ProGuard/R8 mapping files (mapping.txt) and .so corresponding to your release builds.

Deobfuscating Java/Kotlin Crashes

You can upload mapping files using one of these ways:

1. Manually via the Luciq Dashboard

2. Automated via Gradle Plugin (Straightforward & Recommended)

3. Automated via Script

4. Automated via API

Recovering Mapping Files from Google Play Console

When uploading your .aab to the Google Play Console (or any other store), it's a good practice to keep a backup of the mapping file in case automated upload methods fail.

If you need to upload the mapping file after the AAB has already been published, you can still retrieve it from the Google Play Console by following these steps:

1. Go to Google Play Console → Test and release → Production

2. Open App bundles and select Details

   
3. Download the published app bundle

   
4. Rename the file from app-release.aab to app-release.zip then extract the ZIP file

5. Navigate to: BUNDLE-METADATA/com.android.tools.build.obfuscation/

6. Locate the proguard.map file then rename it to proguard.txt

7. Upload the file manually via the Luciq Dashboard

This allows you to recover and upload the correct mapping file even after your app has already been released.

1. Uploading Manually via the Dashboard

1. Open your Luciq Dashboard.

2. Go to Settings → Upload Mapping Files.

3. Upload your mapping.txt file.

Multiple mapping files can be uploaded for different app versions.

2. Uploading via Gradle Plugin

Using the Luciq plugin ensures that mapping files are uploaded automatically.

If you're using Gradle Version Catalog TOML, please check out this page for adding 'luciq-plugin'.

Step 1: Add the Plugin to your buildscript

Gradle

buildscript {
    dependencies {
        classpath "ai.luciq.library:luciq-plugin:x.y.z"
    }
}

Step 2: Apply the plugin in your app module

Add apply plugin: 'luciq-crash' to your app's Gradle file.

Step 3: Configure the plugin

Ready to go example:

Gradle

luciq {
    crashReporting {
        autoUploadEnabled = true
        appToken = "YOUR_APP_TOKEN"
    }
}

Full example:

Gradle

luciq {
    crashReporting {
        /**
         * Application token
         * Required: Yes (when autoUploadEnabled = true, otherwise build fails)
         */
        appToken = "YOUR_APP_TOKEN"

        /**
         * Controls whether mapping files should be automatically uploaded.
         * Required: No
         * Default: false
         * Purpose: When enabled, attaches upload tasks to whitelisted variant build flows.
         *          When disabled, upload tasks are skipped entirely.
         */
        autoUploadEnabled = true

        /**
         * Enables experimental support for GuardSquare's obfuscation tools (ProGuard/DexGuard).
         * Required: No
         * Default: false
         * Purpose: Allows detection and processing of minification from GuardSquare tools
         *          in addition to AGP's built-in minification.
         */
        experimentalGuardSquareSupportEnabled = false

        /**
         * Custom upload URL for mapping files.
         * Required: No
         * Purpose: Allows overriding the default upload endpoint for on-premise
         *          or custom backend deployments.
         */
        uploadUrl = "https://your-custom-url.com"

        /**
         * Lambda function to configure per-variant settings.
         * Required: No
         * Default: Debug variants are not whitelisted by default
         * Purpose: Provides fine-grained control over which variants get upload tasks
         *          and allows custom mapping file paths per variant.
         */
        variantConfigurations { configurations ->
            // The name of the variant being configured.
            def variantName = configurations.name

            /**
             * Controls whether this variant should have upload tasks created.
             * Required: No
             * Default: true (except debug variants which are false by default)
             * Purpose: Whitelists a variant for the plugin to create and attach
             *          upload task to its build flow.
             */
            configurations.setWhitelisted(true)

            /**
             * Path to a custom mapping file for this variant.
             * Required: No
             * Default: null (automatic mapping file detection is used)
             * Purpose: Allows specifying an alternative mapping file location
             *          instead of the auto-detected one from the build.
             */
            configurations.setCustomMappingFilePath("FILE_PATH")
        }
    }
}

This ensures mapping files are uploaded automatically during your build process.

3. Uploading via Script

Automating uploads ensures that mapping files are uploaded every time a release build is generated.

Step 1: Create the Upload Script

Create a file called upload_mapping.sh at the root of your project:

Shell

#!/bin/bash
echo "Luciq mapping files uploader"

APP_TOKEN="$1"
VERSION_CODE="$2"
VERSION_NAME="$3"
PATH_TO_MAPPING_FILE="$4"
VERSION='{"code":"'"$VERSION_CODE"'","name":"'"$VERSION_NAME"'"}'

if [ ! -f "$PATH_TO_MAPPING_FILE" ]; then
    echo "File not found: $PATH_TO_MAPPING_FILE"
    exit 1
fi

echo "Mapping file found! Uploading..."

ENDPOINT="https://api.instabug.com/api/sdk/v3/symbols_files"
STATUS=$(curl "${ENDPOINT}" \
  --write-out %{http_code} \
  --silent \
  --output /dev/null \
  -F os=android \
  -F app_version="${VERSION}" \
  -F symbols_file=@"${PATH_TO_MAPPING_FILE}" \
  -F application_token="${APP_TOKEN}")

if [ "$STATUS" -ne 200 ]; then
  echo "Error while uploading mapping files (HTTP $STATUS)"
  exit 1
fi

echo "Success! Your mapping files got uploaded successfully"

Step 2: Add the Gradle Task

Add the following to your app module's build.gradle (Groovy DSL):

Gradle

tasks.register('uploadMappingFiles') {
    doLast {
        android.applicationVariants.all { variant ->
            if (variant.buildType.name == "release") {
                def mappingFile = variant.mappingFile
                if (mappingFile == null || !mappingFile.exists()) {
                    logger.lifecycle("No mapping file for ${variant.name}")
                    return
                }
                exec {
                    commandLine(
                        "/bin/sh",
                        "${rootDir}/upload_mapping.sh",
                        "YOUR_APP_TOKEN",
                        variant.versionCode.toString(),
                        variant.versionName,
                        mappingFile.absolutePath
                    )
                }
            }
        }
    }
}

Notes:

• Use absolute paths (${rootDir}) for the script.

• Mapping files are generated only after assembling a release variant.

Step 3: Run the Task

First, build your release variant: ./gradlew :app:assembleRelease

Then upload the mapping file: ./gradlew :app:uploadMappingFiles

Tip: For CI/CD, you can attach the upload task directly to the release build to ensure mapping files always exist.

4. Uploading via API

You can also upload mapping files directly via API. Mapping files must be uploaded as a .txt file.

cURL

curl --location --request POST 'https://api.instabug.com/api/sdk/v3/symbols_files' \
--form 'os="android"' \
--form 'application_token="YOUR_APP_TOKEN"' \
--form 'app_version="{\"code\":\"7\",\"name\":\"7.7\"}"' \
--form 'symbols_file=@"./mapping.txt"'

Deobfuscating NDK/C++ Crashes

By default, native crashes are obfuscated. In order to deobfuscate them, you'll need to upload the relevant .so files and we'll take care of the rest.

Locating .so Files

The .so files are usually found in specific directories related to the different app architectures. You can find below the different files, as well as their related architecture.

Uploading Manually via the Dashboard

Once you have the .so files, you can upload them directly to the dashboard through Upload NDK DSYMs page found in the Settings menu of your Luciq dashboard. You'll only need to upload the file, while selecting the correct app version and app architecture.

Uploading via API

We have an API endpoint that you can use to upload your symbol files directly from the console or from the CI.

cURL

curl --location --request POST 'https://api.instabug.com/api/web/public/so_files' \
--form 'application_token="YOUR_APP_TOKEN"' \
--form 'api_key="API_KEY"' \
--form 'app_version="1.1"' \
--form 'arch="x86"' \
--form 'so_file=@"so-files.zip"'

Please contact support to obtain your API Key