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 the crash logs, upload the mapping file to AppMetrica.

A special plugin is used in AppMetrica for uploading mapping files. 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 connect the plugin.
  1. Connecting the plugin
  2. Manual loading

Connecting the plugin

Attention. To use the plugin, you need to install the AppMetrica SDK version not lower than 3.8.0.

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.0.1'
        }
     }
    Copied to clipboard
  2. Add to the app/build.gradle file:
    ...
    apply plugin: 'appmetrica-plugin'
    
    appmetrica {
        postApiKey = "Post Api key"
        mappingBuildTypes = ['release']      // Optional.
        offline = false                      // Optional.
    }
    ...
    Copied to clipboard
    postApiKey *
    Post API key. You can get the Post API key in the Settings of AppMetrica. It's used to identify your app.

    If offline = true, the parameter is optional.

    mappingBuildTypes
    The list of build types, buildType, for which the mapping file will be sent.

    Default value: ['release'].

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

    offline
    Enables offline mode. 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

Build errors

Possible errors during a build:

  • IllegalStateException — Enable code obfuscation using ProGuard or R8 Compiler.
  • HttpResponseException — Check your internet connection.

Manual loading

For manual loading, you need to connect 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.