Add a mapping file

Your uploaded mapping file enables Splunk RUM to convert stack traces back into a human-readable form.

When you set the minifyEnabled property to true in your Android application source code, your build process minifies, optimizes, and obfuscates the code and generates a single mapping file, mapping.txt. This mapping file contains the information Splunk RUM needs to convert stack traces containing obfuscated classes and filenames back into a human readable form. This conversion is called deobfuscation in Android.

In order to associate a specific mapping file with a specific application build, Splunk RUM compares the applicationId and versionCode properties of the application to the parameters that you specify for the mapping file upload. You specify these parameters either as --app-id and --version-code in the splunk-rum android upload command or by including your application's merged or packaged manifest (AndroidManifest.xml), which includes these properties by default, in the splunk-rum android upload-with-manifest command.

Note:

Splunk recommends that you follow the steps on this page to upload your mapping files to Splunk RUM before you distribute corresponding binaries. To ensure that the mapping files you upload to Splunk RUM match the binaries you deploy to production, the best practice is to integrate the splunk-rum commands below into your CI pipeline so that whenever you re-build your Android application, you automatically re-upload its mapping file. Alternatively, you can upload source maps on demand.

This feature is not available in the us2 region at this time.

Splunk RUM stores your mapping files permanently. You cannot delete them from Splunk RUM at this time.

Prerequisites

To support de-obfuscation of your application's stack traces, ensure that your proguard-rule.pro has the following two lines enabled:
```
-keepattributes LineNumberTable,SourceFile
-renamesourcefileattribute SourceFile
```
Upgrade the following Splunk components:
- splunk-otel-android: v1.10.0
Install the splunk-rum CLI

Uploads for production builds

Upload your application's mapping file and specify its applicationID and versionCode properties.
You can do this in either of these ways:
- Run the upload command with the --app-id and --version-code parameters:
```
splunk-rum android upload \
--app-id=applicationID --version-code=versionCode \
--path=path-to-mapping-file \
[optional-parameters]
```
  Note: If you didn't set the SPLUNK_REALM and SPLUNK_ACCESS_TOKEN environment variables, you must also add the --realm value and --token your-splunk-org-access-token parameters to this command.
- Run the upload-with-manifest command with the path to the application's merged or packaged AndroidManifest.xml file, along with path to the mapping file. Be sure to include the correct manifest, which is the one that's created when your application is built, and is located in the build output directory:
  
  Note: If you didn't set the SPLUNK_REALM and SPLUNK_ACCESS_TOKEN environment variables, you must also add the --realm value and --token your-splunk-org-access-token parameters to this command.
```
splunk-rum android upload-with-manifest \
--manifest path-to-merged-manifest \
--path path-to-mapping-file \
[optional-parameters]
```

(Optional) Verify that your upload succeeded:

splunk-rum android list --app-id=applicationID

Uploads for pre-production builds

If you're instrumenting pre-production builds where versionCode isn't updated for each build, add a unique identifier as metadata to the AndroidManifest.xml file in your source directory before building the application binary. This identifier must be named splunk.build_id. To add this identifier, follow the steps below:

Add this snippet to the <application> block of the AndroidManifest.xml file in your source directory:
```
<meta-data
android:name="splunk.build_id"
android:value="${splunkBuildId}" />
```

Add the following code to the android {} block of the Gradle build script of your application. This code generates a new UUID for every application variant and adds it to the merged manifest file after the variant is assembled, where the Splunk RUM agent will retrieve it:

If you use Kotlin add this to build.gradle.kts:

applicationVariants.configureEach {
    val uniqueBuildId = UUID.randomUUID().toString()
    this.mergedFlavor.manifestPlaceholders["splunkBuildId"] = uniqueBuildId

    logger.lifecycle("Splunk: Variant $name assigned build ID: $uniqueBuildId")

    val capitalizedVariantName = name.replaceFirstChar { it.uppercase() }
    tasks.named("process${capitalizedVariantName}Manifest").configure {
        outputs.upToDateWhen { false }
    }
}

If you use Groovy add this to build.gradle:

applicationVariants.configureEach { variant ->
    def uniqueBuildId = UUID.randomUUID().toString()
    variant.mergedFlavor.manifestPlaceholders.put("splunkBuildId", uniqueBuildId)

    project.logger.lifecycle("Splunk: Variant ${variant.name} assigned build ID: ${uniqueBuildId}")

    def capitalizedVariantName = variant.name.capitalize()
    tasks.named("process${capitalizedVariantName}Manifest").configure {
        outputs.upToDateWhen { false }
    }
}

Upload your application's mapping file and specify its applicationID , versionCode, and splunk.build_id properties. You can do this in either of these ways:
- Run the upload command with the --app-id, --version-code, and --splunk-build-id parameters. This option only works if you added splunk.build_id to your Gradle build script (in step 1). Get the build ID from the Gradle build output or from the merged manifest:
```
splunk-rum android upload \
--app-id=applicationID --version-code=versionCode \
--splunk-build-id value \
--path=path-to-mapping-file \
[optional-parameters]
```
- Run the upload-with-manifest command with the path to the application's merged or packaged AndroidManifest.xml file, along with path to the mapping file. Be sure to include the correct manifest, which is the one that's created when your application is built, and is located in the build output directory:
```
splunk-rum android upload-with-manifest \
--manifest path-to-merged-manifest \
--path path-to-mappping-file \
[optional-parameters]
```