Upload Mapping File

To get unminified stack traces for Android code in your app, ProGuard mapping files must be generated and uploaded using the Pulse Gradle plugin.

Overview

The Pulse Gradle plugin provides a simple way to upload mapping files directly from your build process. The uploadSourceMaps task uploads the mapping file generated during an obfuscation build to the Pulse mapping API.

The task requires you to provide the API URL, app version, version code, and path to the mapping file. All values can be configured in your build.gradle.kts or provided via command line options. Command-line options will override any configured values.

Setup

Include Plugin

If the plugin is part of your project (e.g., in a monorepo), include it in your root settings.gradle.kts:

includeBuild("path/to/pulse-upload-plugin")

Or if published to a Maven repository, add it to pluginManagement:

pluginManagement {
    repositories {
        google()
        mavenCentral()
        gradlePluginPortal()
        maven {
            url = uri("https://your-maven-repo.com/releases")
        }
    }
}

Apply Plugin

In your app module's build.gradle.kts:

plugins {
    id("com.android.application")
    id("org.jetbrains.kotlin.android")
    id("pulse.plugin")
}

Note: The Pulse plugin only activates for Android application projects. When applied to an Android app, it creates the pulse extension and registers the uploadSourceMaps task.

Configure ProGuard

Ensure your release build type has minification enabled:

android {
    buildTypes {
        release {
            isMinifyEnabled = true
            isShrinkResources = true
            proguardFiles(
                getDefaultProguardFile("proguard-android-optimize.txt"),
                "proguard-rules.pro"
            )
        }
    }
}

Configure Pulse Extension (Optional)

You can configure default values in your build.gradle.kts:

pulse {
    sourcemaps {
        apiUrl.set("https://your-backend-url.com/v1/symbolicate/file/upload")
        mappingFile.set(file("app/build/outputs/mapping/release/mapping.txt"))
        appVersion.set("1.0.0")
        versionCode.set(123)
    }
}

Note: Command-line options will override these values if provided.

Upload Mapping Files

Using Gradle Task

The uploadSourceMaps task uploads the ProGuard mapping file that was generated during your release build.

Example Usage

Upload mapping file:

By running the following command, you upload the ProGuard mapping file to enable deobfuscation of native Android stack traces in crash reports:

./gradlew uploadSourceMaps \
  --api-url=https://your-backend-url.com/v1/symbolicate/file/upload \
  --mapping-file=./app/build/outputs/mapping/release/mapping.txt \
  --app-version=1.0.0 \
  --version-code=123

The uploadSourceMaps task only uploads the mapping file. See Finding the Mapping File section for details on building and locating the mapping file.

Task Options

Option	Required	Description
--api-url	Yes	URL for uploading mapping files to the Pulse mapping API endpoint
--mapping-file	Yes	Path to ProGuard mapping file (relative or absolute path).
--app-version	Yes	App version string that matches your app's version name (e.g., 1.0.0).
--version-code	Yes	Version code as a positive integer (e.g., 123).

Finding the Mapping File

Mapping files are generated automatically during release builds when ProGuard obfuscation is enabled. The exact location depends on your build configuration, project structure, and build variants. The path listed below is the common default location, but your project may have a different path based on custom build configurations.

Building the Release APK

Before you can upload a mapping file, you must first build your release APK. This build process generates the ProGuard mapping file. To build the release APK, run:

./gradlew assembleRelease

ProGuard Mapping File Location

Default Location:

• app/build/outputs/mapping/release/mapping.txt

For Custom Build Variants: If you're using custom build variants (e.g., releaseStaging, releaseProduction), the mapping file will be in a variant-specific directory:

• app/build/outputs/mapping/releaseVariantName/mapping.txt

For Flavor-specific Builds: If you have product flavors configured, the path may include the flavor name:

• app/build/outputs/mapping/flavorName/release/mapping.txt

Troubleshooting

Getting Help

View all available task options and their descriptions:

./gradlew help --task uploadSourceMaps

This command shows detailed information about the uploadSourceMaps task, including all available options and their requirements.

Debug Mode

For detailed error information and verbose output during the upload process, use Gradle's built-in debug flag:

./gradlew uploadSourceMaps --debug

This will show detailed logging that can help identify issues with file paths, network connectivity, or API endpoint configuration.