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 mapping files using the Console

You can also updload 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
• Delete an existing mapping file if you need to replace it.

Version Consistency Warning

Critical: One Symbol File Per Version

Each version can only have one mapping file. If you build the same version multiple times:

1. Latest upload wins — The newest mapping file overwrites the previous one
2. Previous crashes become unreadable — Crashes collected with the old build can no longer be de-obfuscated
3. Data is permanently lost — There's no way to recover symbolication for old crashes

Best Practices:

• Increment version for every release build — Even hotfixes should bump the version
• Archive mapping files locally — Keep backups alongside release artifacts
• CI/CD discipline — Ensure your pipeline increments versions automatically
• Don't rebuild releases — If you need to rebuild, bump the version number

Never Upload Debug Mapping Files Over Release

A common mistake is uploading a debug build's mapping file when a release is already deployed. This permanently breaks crash symbolication for your production users.

What happens:

1. You release v1.2.3 to production → mapping file uploaded
2. Later, you build v1.2.3 as debug for local testing → debug mapping uploaded → overwrites production mapping
3. All crashes from production v1.2.3 become unreadable

Prevention:

• Use distinct version names for debug vs release (e.g., 1.2.3 for release, 1.2.3-dev for debug)
• Disable automatic upload for debug builds in CI
• Consider using separate Kotzilla apps for debug and release if you need to test crash reporting

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	Beta	Works well; feedback welcome
JVM	❌ Not yet	Experimental	Obfuscated code shows obfuscated traces
JS/WASM	❌ Not yet	Experimental	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