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.

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 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.0.1'
        }
     }
    Copied to clipboard
  2. Add the following 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 AppMetrica Settings. It's used to identify your app.

    If offline = true, the parameter is optional.

    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.

    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

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.