Crash plugin (AppMetrica Build 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 Build Plugin.
Note
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
from7.0.+
to8.2.+
(except for8.0.+
)- gradle from
7.0.2
to8.6
We don't guarantee that the plugin will work with other versions.
Connecting the plugin
To enable the plugin:
-
Add the following dependency to the Gradle root file:
build.gradle.ktsbuild.gradlebuildscript { repositories { mavenCentral() } dependencies { classpath("io.appmetrica.analytics:gradle:0.11.0") } }
buildscript { repositories { mavenCentral() } dependencies { classpath 'io.appmetrica.analytics:gradle:0.11.0' } }
-
Add connecting and configuring the plugin to the app's Gradle file:
build.gradle.ktsbuild.gradleplugins { id("com.android.application") id("appmetrica-plugin") } appmetrica { postApiKey = { applicationVariant -> "Post Api key for variant" } // or setPostApiKey("Post Api key") enable = { applicationVariant -> true } // Optional. setMappingBuildTypes(listOf("release")) // Optional. setOffline(false) // Optional. mappingFile = { applicationVariant -> null } // Optional. enableAnalytics = true // Optional. allowTwoAppMetricas = { applicationVariant -> false } // Optional. ndk { // Optional. enable = { applicationVariant -> false } soFiles = { applicationVariant -> listOfSoFiles } // Optional. additionalSoFiles = { applicationVariant -> listOfSoFiles } // Optional. addNdkCrashesDependency = { applicationVariant -> true } // Optional. } }
plugins { id 'com.android.application' id '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. mappingFile = { applicationVariant -> null } // Optional. enableAnalytics = true // Optional. allowTwoAppMetricas = { applicationVariant -> false } // Optional. ndk { // Optional. enable = { applicationVariant -> false } soFiles = { applicationVariant -> listOfSoFiles } // Optional. additionalSoFiles = { applicationVariant -> listOfSoFiles } // Optional. addNdkCrashesDependency = { applicationVariant -> true } // Optional. } }
Parameter
Description
postApiKey*
Post API key or lambda function that returns a Post API key for
ApplicationVariant
. Read more aboutApplicationVariant
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, the apk does not change and the mapping file does not load.By default, it returns
true
only forbuildType = 'release'
.Note
Use one of the parameters to specify assembly types:
enable
ormappingBuildTypes
.mappingBuildTypes
List of
buildType
build types 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 that
buildType
from the list.Note
Use one of the parameters to specify assembly types:
enable
ormappingBuildTypes
.offline
Enables the
offline
mode. Boolean or a lambda function that acceptsApplicationVariant
.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 isfalse
.
mappingFile
Lambda function that accepts
ApplicationVariant
and returns the mapping file to upload. If it returnsnull
, the default value is used.The default value is
ApplicationVariant.mappingFileProvider
.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 istrue
.
allowTwoAppMetricas
A lambda function that accepts
ApplicationVariant
and checks the use of two AppMetrica libraries at the same time.Acceptable values:
false
— The plugin checks that only one library version is used in the project:io.appmetrica.analytics:analytics
orcom.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
.ndk
This parameter is required to load characters from the SO file to track native crashes.
ndk.enable
A lambda function that accepts
ApplicationVariant
and returns whether to load the characters from the SO files for this build option.The default value is
false
.ndk.soFiles
A lambda function that accepts
ApplicationVariant
and returns a list of SO 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
A lambda function that accepts
ApplicationVariant
and returns a list of additional SO files to load the characters from.ndk.addNdkCrashesDependency
A lambda function that accepts
ApplicationVariant
and returns whether to include theio.appmetrica.analytics:analytics-ndk-crashes
dependency.The default value is
true
. -
If the
ndk
parameter is enabled, debug characters are sent using theupload${variant.name.capitalize()}Symbols
Gradle task. To call a task automatically, you can add it to a fileapp/build.gradle
the following code:build.gradle.ktsbuild.gradleandroid.applicationVariants.configureEach { val variant = this val uploadSymbolsTask = project.tasks.findByName("upload${variant.name.capitalize()}Symbols") if (uploadSymbolsTask != null) { variant.assembleProvider.configure { it.finalizedBy(uploadSymbolsTask) } // If you use apk project.tasks.named("bundle${variant.name.capitalize()}") { finalizedBy(uploadSymbolsTask) } // If you use aab } }
android.applicationVariants.configureEach { variant -> def uploadSymbolsTask = project.tasks.findByName("upload${variant.name.capitalize()}Symbols") if (uploadSymbolsTask != null) { variant.assembleProvider.configure { it.finalizedBy(uploadSymbolsTask) } // If you use apk project.tasks.named("bundle${variant.name.capitalize()}") { finalizedBy(uploadSymbolsTask) } // If you use aab } }
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.ktsbuild.gradleappmetrica { setOffline(true) }
appmetrica { offline = true }
Parameter
Description
offline
Enables the
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 isfalse
.
-
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.
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.