AppMetrica Gradle Plugin

AppMetrica lets you collect information about native and Java crashes. You can analyze them in the Crashes report. See also Crashes/errors.

To reduce the size of an app, optimize the code during a release build.

If the code was compressed and obfuscated during the build of an Android application, information about crashes is transmitted in obfuscated form. To extract data for analysis from such crash logs, AppMetrica performs server-side deobfuscation.

To do this, upload the mapping files or debug symbols of SO files to AppMetrica, either automatically when building the app or manually via the web interface.

To send files, enable the AppMetrica Gradle Plugin.

Restrictions

Upload mapping files if you use ProGuard or R8. If you don't compress or obfuscate the code, don't enable the plugin.
The plugin's operation depends on the versions of com.android.tools.build:gradle (AGP) and gradle. The plugin is compatible with the following versions:
- com.android.tools.build:gradle from 7.2.0 to 8.13.+ (except for 8.0.+);
- gradle from 7.4 to 9.2.1. We don't guarantee that the plugin will work with other versions.
The plugin's functionality is not guaranteed when using Gradle 8.0 and AGP 7.4.* together.
It is recommended to disable the plugin for local builds. This will speed up the project build. The plugin must be enabled only for CI builds.

Connecting the plugin

To enable the plugin:

Add the following dependency to the Gradle root file:

build.gradle.kts

build.gradle

plugins {
    id("io.appmetrica.analytics") version "2.0.1" apply false
}

plugins {
    id "io.appmetrica.analytics" version "2.0.1" apply false
}

Enabling plugin using buildscript

Add the following dependency to the Gradle root file:

build.gradle.kts

build.gradle

buildscript {
    repositories {
        mavenCentral()
    }
    dependencies {
        classpath("io.appmetrica.analytics:gradle:2.0.1")
    }
}

buildscript {
    repositories {
        mavenCentral()
    }
    dependencies {
        classpath 'io.appmetrica.analytics:gradle:2.0.1'
    }
}

Add connecting and configuring the plugin to the app's Gradle file:

build.gradle.kts

build.gradle

plugins {
    id("com.android.application")
    id("io.appmetrica.analytics")
}

appmetrica {
    postApiKey.set("Post Api key")
    enable.set(true)                                    // Optional
    offline.set(false)                                   // Optional
    mappingFile.set(file("path/to/mapping.txt"))         // Optional
    enableAnalytics.set(true)                            // Optional
    allowTwoAppMetricas.set(false)                       // Optional
    ndk {                                                // Optional
        enable.set(false)
        soFiles.from(file("path/to/so"))                 // Optional
        additionalSoFiles.from(file("path/to/extra"))    // Optional
        addNdkCrashesDependency.set(true)                // Optional
    }
}

plugins {
    id 'com.android.application'
    id 'io.appmetrica.analytics'
}

appmetrica {
    postApiKey = "Post Api key"
    enable = true                                        // Optional
    offline = false                                      // Optional
    mappingFile = file("path/to/mapping.txt")            // Optional
    enableAnalytics = true                               // Optional
    allowTwoAppMetricas = false                          // Optional
    ndk {                                                // Optional
        enable = false
        soFiles.from(file("path/to/so"))                 // Optional
        additionalSoFiles.from(file("path/to/extra"))    // Optional
        addNdkCrashesDependency = true                   // Optional
    }
}

Tip

The plugin supports hierarchical per-buildType, per-flavor, and per-variant configuration. Configuration priority: global > variant > buildType > flavor > default.

Hierarchical configuration example

build.gradle.kts

build.gradle

// Global settings (highest priority)
appmetrica {
    postApiKey.set("default-key")
    enable.set(true)
}

// Per-buildType settings
android.buildTypes {
    named("release") {
        appmetrica {
            postApiKey.set("release-key")
        }
    }
    named("debug") {
        appmetrica {
            enable.set(false)
            offline.set(true)
        }
    }
}

// Per-flavor settings
android.productFlavors {
    named("prod") {
        appmetrica {
            postApiKey.set("prod-key")
        }
    }
}

// Global settings (highest priority)
appmetrica {
    postApiKey = "default-key"
    enable = true
}

// Per-buildType settings
android.buildTypes {
    release {
        appmetrica {
            postApiKey = "release-key"
        }
    }
    debug {
        appmetrica {
            enable = false
            offline = true
        }
    }
}

// Per-flavor settings
android.productFlavors {
    prod {
        appmetrica {
            postApiKey = "prod-key"
        }
    }
}

Parameter	Description
`postApiKey*`	Post API key. `String`. 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. Supports hierarchical per-buildType, per-flavor, and per-variant configuration.
`enable`	Enables or disables the plugin for the given build variant. `Boolean`. If the plugin is disabled, the apk does not change and the mapping file does not load. By default, `true` only for `buildType = 'release'`. Supports hierarchical per-buildType, per-flavor, and per-variant configuration.
`offline`	Enables the `offline` mode. `Boolean`. 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`. Supports hierarchical per-buildType, per-flavor, and per-variant configuration.
`mappingFile`	Path to the mapping file to upload. `File`. The default value is the mapping file from the build.
`enableAnalytics`	Lets plugin usage statistics be sent to AppMetrica. `Boolean`. Acceptable values: `true` — Sending statistics is enabled. `false` — Sending statistics is disabled. The default value is `true`.
`allowTwoAppMetricas`	Checks the use of two AppMetrica libraries at the same time. `Boolean`. Acceptable values: `false` — The plugin checks that only one library version is used in the project: `io.appmetrica.analytics:analytics` or `com.yandex.android:mobmetricalib`. If not, an exception is thrown. `true` — The plugin checks the use of two AppMetrica libraries at the same time, the check result is logged. The default value is `false`. Supports hierarchical per-buildType, per-flavor, and per-variant configuration.
`ndk`	This parameter is required to load symbols from the SO file to track native crashes.
`ndk.enable`	Enables or disables loading symbols from SO files. `Boolean`. If enabled, symbol upload tasks run automatically after the build. The default value is `false`. Supports hierarchical per-buildType, per-flavor, and per-variant configuration.
`ndk.soFiles`	SO files to process. `ConfigurableFileCollection`. Use `.from(...)` to add files. By default, the plugin searches for SO files in the Android Studio project folders. You need to redefine the path if your SO files are in an unusual location or the plugin can't find them.
`ndk.additionalSoFiles`	Additional SO files to load symbols from. `ConfigurableFileCollection`. Use `.from(...)` to add files.
`ndk.addNdkCrashesDependency`	Enables automatic addition of the `io.appmetrica.analytics:analytics-ndk-crashes` dependency. `Boolean`. The default value is `true`. Supports hierarchical per-buildType, per-flavor, and per-variant configuration.

Note

If the ndk.enable parameter is enabled, symbol upload tasks run automatically after the build. No manual configuration is required.

Manual loading

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

In the app/build.gradle file, turn on the offline mode and run the build.
build.gradle.kts

build.gradle
```
appmetrica {
    offline.set(true)
}
```
```
appmetrica {
    offline = true
}
```
In the AppMetrica interface, go to the app settings from the menu on the left.
Go to the Crashes → Android tab.
Click Choose file and upload the ZIP archive.

Description of generated files

The plugin for work generates files in the app/build/appmetrica folder.
The folder structure is given below.

app/build/appmetrica
└── release - the name of AndroidApplicationVariant
    ├── info.txt - the file with meta information for searching for a mapping file and symbols
    ├── res - the folder with resources that will be used to build the application
    │   ├── raw
    │   │   └── keep_appmetrica_resources.xml - rules for R8 on resource conservation
    │   └── values
    │       └── appmetrica_resources.xml - resources required for work
    ├── result - the folder with archives that you need to upload manually when using offline mode
    │   ├── mapping.zip - the final archive with mappings
    │   └── symbols.zip - the final archive with symbols
    └── symbols - a folder with symbols that came from so files
        ├── libmyapplication_0E6CC10E8293F1B2DF0293FBE44887AD0.ysym
        ├── libmyapplication_3CDE92724603DA3A59BC6E311625A4000.ysym
        ├── libmyapplication_6F5C61C0E96CAEFD1E7ED491F806DA100.ysym
        └── libmyapplication_F3E083A014DD2840F0E730B6BB138E4A0.ysym

Build errors

Possible errors during a build:

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

If you encounter further errors, please contact technical support.

Learn more

If you didn't find the answer you were looking for, you can use the feedback form to submit your question. Please describe the problem in as much detail as possible. Attach a screenshot if possible.

Contact support Suggest an improvement for documentation

Was the article helpful?

Analyzing crashes

Deferred deeplinks support