Uploading mapping files on Android

To reduce the size of an app, you can compress and obfuscate the code during a release build. In this case, information about crashes will be sent in an obfuscated form. It's difficult to extract data for analysis from these crash logs. To analyze crash logs, upload the mapping file to AppMetrica.

To upload mapping files to AppMetrica, use the special plugin. It automatically uploads mapping files when building an app.

Note. Mapping files should be uploaded if the app code is obfuscated using ProGuard or R8. If no code obfuscation is used, don't enable the plugin.
  1. Enabling the plugin
  2. Manual loading

Enabling the plugin

Attention. To use the plugin, you need to install the AppMetrica SDK with version 3.8.0 or higher.

To enable the plugin:

  1. Add the following dependency to the build.gradle root file:
    buildscript {
        ...
        dependencies {
            ...
            classpath 'com.yandex.android:appmetrica-build-plugin:0.1.2'
        }
     }
    Copied to clipboard
  2. Add the following to the app/build.gradle file:
    ...
    apply plugin: 'appmetrica-plugin'
    
    appmetrica {
        postApiKey = { applicationVariant -> "Post Api key for variant" }
        // or postApiKey = "Post Api key"
        enable = { applicationVariant -> true }    // Optional.
        mappingBuildTypes = ['release']            // Optional.
        offline = false                            // Optional.
    }
    ...
    Copied to clipboard
    postApiKey *
    Post API key or lambda function that returns a Post API key for ApplicationVariant. Read more about ApplicationVariant in the Android and Javadoc documentation.

    You can get the Post API key in the AppMetrica Settings. It's used to identify your app.

    If offline = true, the parameter is optional.

    enable
    Lambda function that accepts ApplicationVariant and returns whether to use the plugin for this build option.

    If the plugin is not used, apk does not change and the mapping file does not load.

    By default, it returns true only for buildType = 'release'.

    Note. Use one of the parameters to specify assembly types: enable or mappingBuildTypes.
    mappingBuildTypes
    The buildType list that the mapping file is sent for.

    Default value: ['release'].

    To disable the uploading of mapping files for a specific type of build, delete that buildType from the list.

    Note. Use one of the parameters to specify assembly types: enable or mappingBuildTypes.
    offline

    Enables the offline mode. Boolean or a lambda function that takes ApplicationVariant.

    Acceptable values:

    • true — Doesn't upload a file to AppMetrica. If enabled, it outputs the archive path to the log after the build is complete. You can upload it manually via the web interface.
    • false — Automatically uploads the mapping file.

    The default value is false.

    Required

Manual loading

To load manually, enable and use the plugin in offline mode. This is necessary to link the mapping file to the app build.

  1. In the app/build.gradle file, turn on offline mode and run the build.
    appmetrica {
        ...
        offline = true
    }
    Copied to clipboard
    offline
    Enables offline mode. Acceptable values:
    • true — Doesn't upload the mapping file to AppMetrica. If enabled, it outputs the archive path to the log after the build is complete.
    • false — Automatically uploads the mapping file.

    The default value is false.

  2. In the AppMetrica interface, go to the app settings from the menu on the left.
  3. Open Crashes → Android.
  4. Click Choose file and upload the ZIP archive.