What a mapping file holds
A mapping file lists the original name of each class, method and field beside the name the shipped build uses. It is produced by the shrinker during the build and is not part of the distributed APK, so it reaches you only when the developer keeps it or a build system stores it. Newer formats also carry line numbers and inline frame information, which lets a retrace tool place a stack frame inside the method that absorbed it.
That makes the file useful in two directions. From a shipped name you can recover the original, and from an original you can find what it became. Both directions matter when you connect a readable crash report from the developer's own logs to an APK that contains none of those names.
What a mapping file does not hold
It does not reverse the optimizer's work. R8 inlines short methods, merges classes and removes code it cannot reach, and a mapping file describes the names of what remains rather than restoring the program's original shape. A method that was inlined has no shipped method to point at, and the mapping's line entries may point only at the call site that absorbed it.
It does not describe behaviour. A name tells you what the developer called something, and a class called a signer in the source can hold unrelated logic after a refactor. The name is a hypothesis to test against the call site and the data flow, not a conclusion.
It does not transfer between builds. A mapping from a different version can map a shipped name onto an original that never existed in the APK in front of you, and the result reads plausibly while being wrong. It also covers only the Java and Kotlin program, so native code stays outside its reach.
Matching a mapping to a build
Confirm the pairing before you rely on the file. Version code, build fingerprint, the release channel and any checksum recorded with the mapping all help. When those are missing, test the pairing on something you already know: retrace a stack trace whose cause you established from behaviour, or map a class you identified independently, and check whether the returned name matches the role.
A partial mapping is common. Obfuscation settings can leave some classes untouched, and a file that covers only part of the build still helps if you know which part. Where a name you need is absent, treat the absence as information about the build rather than as a gap in the tool.
Using a mapping while reading a request
- Retrace the crash or log you already have. A readable report from the developer translates into shipped names that can be searched in the decompiled output.
- Map the hook target. When an interceptor records a shipped class name, the mapping tells you which source class performs that call, which is usually enough to decide whether it belongs to the request path.
- Map names in the other direction. If documentation or an old report names a source class, the mapping finds the shipped name to search for in the APK.
- Confirm each name by data flow. Read the call site and the arguments. A mapped name that does not fit the values it receives is pointing at the wrong thing, or the optimizer moved the code.
Where mapping work goes wrong
The common mistakes are mechanical. Applying a mapping from the wrong build, retracing a stack from a different version, or trusting a name whose class was merged into another. Inlining produces frames that look like they belong to the caller, so a retraced trace can name a method that never contained the failing statement. Synthetic frames and compiler-generated classes can also map to entries that did not exist in the source at all.
Handle those by treating the mapping as evidence about the build and the decompiled code as evidence about behaviour. Where the two disagree, the decompiled code is the one that runs.
What the client keeps from this work
The mapping is analysis material, not a deliverable. The client you deliver uses names your own team can read, and the mapping only supports the investigation that produced it. What carries forward is the description of the request pipeline: the endpoint, the payload shape, the derived values and the session rules, each recorded with the evidence that established it.
Send the APK together with any mapping file and build metadata you hold. We confirm the pairing, map the request path, and reconstruct the calls in names your team can maintain. R8 reverse engineering covers the optimizer's effect on a build, and Android obfuscation reverse engineering covers the wider set of techniques that accompany it.
Related work
Reviewed 28 September 2026 · SReverse research desk