/

Deobfuscate Stack Traces

When your application is protected with Shield, exception messages and stack traces will contain obfuscated names. ByteHide automatically handles deobfuscation so you can debug production issues with the original class and method names.

How It Works

Every time you build your application with Shield, a mapping file is generated and automatically uploaded to the ByteHide Cloud Panel. This mapping file contains the relationship between the original names and the obfuscated names.

When you encounter an obfuscated stack trace from a crash report or exception log, you can decode it instantly from the Cloud Panel or via the API. No additional setup is required: if your project has a valid token, mappings are uploaded and available automatically.

Requirements

To decode stack traces, you will need:

  • Your Project Token
  • Your Protection Secret (set in your Shield configuration, or auto-generated if not specified)

Finding the Protection Secret

The protectionSecret is set in your shield { } block. If you did not set one explicitly, Shield generates one automatically for each build. You can find it in the ByteHide Cloud Panel under your project's build history.

Groovy
shield {
    projectToken = "your-project-token"
    protectionSecret = "your-secret"  // Optional: auto-generated if omitted
}

Decoding via the Cloud Panel

The simplest way to decode a stack trace:

  1. Go to your project in the ByteHide Cloud Panel
  2. In the history section, click the three dots (actions) for the build you want to decode
  3. Select Deobfuscate trace
  4. Paste your obfuscated stack trace and click Deobfuscate Trace

Deobfuscate trace configurationClick to expand

The panel returns the original, readable stack trace with the real class and method names:

Deobfuscated stack trace resultClick to expand

Obfuscated input:

CODE
java.lang.NullPointerException
    at a.b.c(Unknown Source)
    at a.e.g(Unknown Source)
    at a.f.onCreate(Unknown Source)

Decoded output:

CODE
java.lang.NullPointerException
    at com.example.payment.PaymentProcessor.chargeCustomer(PaymentProcessor.java)
    at com.example.auth.AuthManager.isAuthenticated(AuthManager.java)
    at com.example.ui.MainActivity.onCreate(MainActivity.java)

Decoding via the API

Shield also provides an API endpoint to decode stack traces from any tool or script:

Endpoint:

HTTP
GET https://shield.microservice.bytehide.com/api/applications/<project-token>/<protection-secret>?trace=<obfuscated-trace>
  • <project-token>: Your Project Token
  • <protection-secret>: Your Protection Secret
  • <obfuscated-trace>: The obfuscated stack trace (URL-encoded)

Response codes:

CodeMeaning
200Original stack trace returned (plain text)
404Application or secret not found

This makes it easy to integrate deobfuscation into your CI/CD pipeline, crash reporting workflow, or support tools.

Mapping File Format

Shield generates mappings in the standard ProGuard format, which means they are compatible with all Android crash reporting tools (Firebase Crashlytics, Bugsnag, Sentry, etc.):

CODE
com.example.payment.PaymentProcessor -> a.b:
    java.lang.String apiKey -> d
    com.example.payment.PaymentGateway gateway -> f
    void <init>() -> <init>
    com.example.payment.PaymentResult chargeCustomer(java.lang.String,double) -> c
com.example.auth.AuthManager -> a.e:
    boolean isAuthenticated() -> g
    void logout() -> h

Firebase Crashlytics Integration

If you use Firebase Crashlytics, mapping files are also compatible with the Crashlytics Gradle plugin. When both Shield and the Crashlytics plugin are applied, crash reports in the Firebase console can be deobfuscated automatically.

Build History

All builds and their mapping files are stored in the Cloud Panel. You can browse previous builds, compare protection configurations, and decode stack traces from any past build:

Shield build historyClick to expand

Previous
Annotations
Next
Cloud Integration