Mapping files for production builds

To enable the Kotzilla SDK to effectively handle obfuscated builds in production, it’s required to upload your mapping files. This step ensures that stack traces from release builds can be properly de-obfuscated for analysis in the Kotzilla Console.

This guide explains how to configure and run the upload task for mapping files.

Prerequisites

To upload mapping files, ensure that the Kotzilla Gradle plugin is configured in your project. For more information on setting up the plugin, refer to the section called Update Gradle files in the get started guide.

Automatic upload (since version 1.0.1)

Starting from SDK version 1.0.1, the Kotzilla Gradle plugin automatically uploads your mapping files after any assembleRelease build. This means you no longer need to manually run the upload task for release builds unless you’ve turned this off.

If you prefer to disable automatic uploads (for example, in CI environments or custom build setups), you can do so by updating uploadMappingFile = false in the Kotzilla Gradle config.

Uploading mapping files using Gradle

1. Run the upload task from the main application module in your project. The task can be executed for a specific build flavor by running the following command:

   ./gradlew uploadMappingFile<Flavour>

2. Example: To upload the mapping file for the release build flavour, use:

   ./gradlew uploadMappingFileRelease

Uploading and downloading mapping files using the Console

You can also manage generated mapping files directly from the Kotzilla Console.

1. Open the Dashboard for your application.
2. Click on Settings.
3. In the Mapping Files section, you’ll see the list of available mapping files for each version.

From here you can:

• Upload a new mapping file for a specific version after generating it locally.
• Download a mapping file so you can keep a local copy or inspect it.
• Delete an existing mapping file if you need to remove it.

Multiple mapping files per version (since SDK 2.2.1)

Starting with SDK 2.2.1, a single app version can keep several mapping files, and each crash resolves to the exact mapping that produced it.

The Kotzilla Gradle plugin generates a per-build Build ID (UUID v7), sends it on every session, and tags each mapping upload with it. So even when several builds share the same version name, the Console matches a crash to the mapping from the exact build it came from. On Android this is per-variant, so a release build and a minified staging build no longer overwrite each other's mappings.

No more partial deobfuscation

Earlier SDKs kept only one mapping file per version, so rebuilding the same version name overwrote the previous mapping. Component and dependency names, along with crash stack traces, could then come back only partially deobfuscated. With Build ID propagation this no longer happens: rebuilds and minified variants of the same version each keep their own mapping, so every signal stays fully de-obfuscated.

Best practices

• Keep automatic upload enabled so each release build's mapping is uploaded and tagged with its Build ID.
• Disable automatic upload for debug builds in CI if you don't want debug mappings sent to the Console.
• Archive mapping files locally alongside your release artifacts as an extra backup.

Cross-Platform Crash Reporting

The Kotzilla SDK captures crashes across multiple platforms. Symbol file support varies by platform:

Platform	Symbol Support	Status	Notes
Android	✅ Mapping files	Stable	Full ProGuard/R8 de-obfuscation
iOS	✅ dSYM files	Stable	Full dSYM symbolication with Kotlin stack traces
JVM	❌ Not yet	Stable	Obfuscated code shows obfuscated traces
JS/WASM	❌ Not yet	Stable	Minified code shows minified traces

For iOS dSYM upload setup, see the KMP Setup Guide.

Important notes

• When automatic upload is disabled, make sure this task is integrated into your production build process.

• The upload task is not triggered by default in all build variants.

• To see available upload tasks, run:

  ./gradlew tasks