AppMetrica Gradle Plugin

AppMetrica позволяет собирать информацию о нативных и java-крэшах. Их можно анализировать в отчете Крэши. См. также раздел Крэши/ошибки.

Чтобы уменьшить размер приложения, код оптимизируют во время релизной сборки.

Если во время сборки Android-приложения сжимали и обфусцировали код, то информация о крэшах передается в обфусцированном виде. Чтобы извлечь данные для анализа из таких крэш-логов, AppMetrica выполняет деобфускацию на стороне сервера.

Для этого загрузите mapping-файлы или отладочные символы SO-файлов в AppMetrica: автоматически при сборке приложения или вручную через веб-интерфейс.

Чтобы отправлять файлы, подключите AppMetrica Gradle Plugin.

Примечание

Загружайте mapping-файлы, если вы используете ProGuard или R8. Если вы не сжимаете и не обфусцируете код, не подключайте плагин.

Работа плагина зависит от версий com.android.tools.build:gradle (AGP) и gradle. Поддерживается работа плагина со следующими версиями

com.android.tools.build:gradle с 7.2.+ до 8.7.+ (кроме 8.0.+)
gradle с 7.4 до 8.9 Работа плагина с другими версиями не гарантируется.

Работа плагина при использовании gradle 8.0 и AGP 7.4.+ вместе не гарантируется.

Подключение плагина

Чтобы подключить плагин:

Добавьте в корневой Gradle файл зависимость:

build.gradle.kts

build.gradle

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

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

Подключение с использованием buildscript

Добавьте в корневой Gradle файл зависимость:

build.gradle.kts

build.gradle

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

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

Добавьте в Gradle файл приложения подключение плагина и его настройку:

build.gradle.kts

build.gradle

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

appmetrica {
    postApiKey = { applicationVariant -> "Post Api key for variant" }
    // or setPostApiKey("Post Api key")
    enable = { applicationVariant -> true }    // Optional.
    offline = { applicationVariant -> 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 'io.appmetrica.analytics'
}

appmetrica {
    postApiKey = { applicationVariant -> "Post Api key for variant" }
    // or postApiKey = "Post Api key"
    enable = { applicationVariant -> true }    // Optional.
    offline = { applicationVariant -> 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.
    }
}

Параметр	Описание
`postApiKey*`	Post API key или лямбда-функция, которая возвращает Post API key для `ApplicationVariant`. Подробнее про `ApplicationVariant` в документации Android и Javadoc. Post API key можно получить в разделе Настройки в AppMetrica. Он используется для идентификации вашего приложения. Если `offline = true`, то параметр не является обязательным.
`enable`	Лямбда-функция, которая принимает `ApplicationVariant` и возвращает, надо ли использовать плагин для этого варианта сборки. Если плагин не используется, apk не меняется и mapping-файл не загружается. По умолчанию возвращает `true` только для `buildType = 'release'`. Примечание Для указания типов сборок используйте один из параметров: `enable` или `mappingBuildTypes`.
`mappingBuildTypes`	Список типов сборок `buildType`, для которых будет отправляться mapping-файл. Значение по умолчанию: `['release']`. Чтобы отключить загрузку mapping-файлов для определенного типа сборки, удалите из списка нужный `buildType`. Примечание Для указания типов сборок используйте один из параметров: `enable` или `mappingBuildTypes`.
`offline`	Включает режим `offline`. Boolean или лямбда-функция, которая принимает `ApplicationVariant`. Допустимые значения: `true` — не загружает файл в AppMetrica. Если включен, после сборки выводит путь до архива в лог. Его можно загрузить вручную через веб-интерфейс. `false` — автоматически загружает mapping-файл. Значение по умолчанию: `false`.
`mappingFile`	Лямбда-функция, которая принимает `ApplicationVariant` и возвращает mapping, который надо загрузить. Если лямбда возвращает `null`, используется значение по умолчанию. Значение по умолчанию: `ApplicationVariant.mappingFileProvider`.
`enableAnalytics`	Включает отправку статистики об использовании плагина в AppMetrica. `Boolean`. Допустимые значения: `true` — отправка статистики включена. `false` — отправка статистики выключена. Значение по умолчанию: `true`.
`allowTwoAppMetricas`	Лямбда-функция, которая принимает `ApplicationVariant` и проверяет использование двух библиотек AppMetrica одновременно. Допустимые значения: `false` — плагин проверяет, что в проекте используется только одна версия библиотеки `io.appmetrica.analytics:analytics` или `com.yandex.android:mobmetricalib`. Если это не так, выбрасывается исключение. `true` — плагин проверяет использование двух библиотек AppMetrica одновременно, результат проверки пишется в лог. Значение по умолчанию: `false`.
`ndk`	Параметр необходим для загрузки символов из SO-файла, чтобы отслеживать нативные крэши.
`ndk.enable`	Лямбда-функция, которая принимает `ApplicationVariant` и возвращает, надо ли загружать символы из SO-файлов для этого варианта сборки. Значение по умолчанию: `false`.
`ndk.soFiles`	Лямбда-функция, которая принимает `ApplicationVariant` и возвращает список SO-файлов. По умолчанию плагин ищет SO-файлы в папках проекта Android Studio. Необходимо переопределить, если ваши SO-файлы лежат в необычном месте или если плагин не может их найти.
`ndk.additionalSoFiles`	Лямбда-функция, которая принимает `ApplicationVariant` и возвращает список дополнительных SO-файлов, символы которых необходимо загрузить.
`ndk.addNdkCrashesDependency`	Лямбда-функция, которая принимает `ApplicationVariant` и возвращает, надо ли добавлять зависимость от `io.appmetrica.analytics:analytics-ndk-crashes`. Значение по умолчанию: `true`.

Если параметр ndk включен, то для отправки отладочных символов используется задача Gradle upload${variant.name.capitalize()}AppMetricaNdkSymbols. Чтобы вызывать задачу автоматически, можно добавить в файл app/build.gradle следующий код:

build.gradle.kts

build.gradle

android.applicationVariants.configureEach {
    val variant = this
    val uploadSymbolsTask = project.tasks.findByName("upload${variant.name.capitalize()}AppMetricaNdkSymbols")
    if (uploadSymbolsTask != null) {
        variant.assembleProvider.configure { it.finalizedBy(uploadSymbolsTask) } // Если используете apk
        project.tasks.named("bundle${variant.name.capitalize()}") { finalizedBy(uploadSymbolsTask) } // Если используете aab
    }
}

android.applicationVariants.configureEach { variant ->
    def uploadSymbolsTask = project.tasks.findByName("upload${variant.name.capitalize()}AppMetricaNdkSymbols")
    if (uploadSymbolsTask != null) {
        variant.assembleProvider.configure { it.finalizedBy(uploadSymbolsTask) } // Если используете apk
        project.tasks.named("bundle${variant.name.capitalize()}") { finalizedBy(uploadSymbolsTask) } // Если используете aab
    }
}

Ручная загрузка

Для ручной загрузки нужно подключить и использовать плагин с режимом offline. Это необходимо для связывания mapping-файла со сборкой приложения.

В файле app/build.gradle включите режим offline и запустите сборку.
build.gradle.kts

build.gradle
```
appmetrica {
    offline = { true }
}
```
```
appmetrica {
    offline = { true }
}
```
В интерфейсе AppMetrica перейдите в настройки приложения из меню слева.
Откройте вкладку Крэши → Android.
Нажмите кнопку Выберите файл и загрузите Zip-архив.

Описание генерируемых файлов

Плагин для работы генерирует файлы в папке app/build/appmetrica. Структура папок приведена ниже

app/build/appmetrica
└── release - название AndroidApplicationVariant
    ├── info.txt - файл с метаинформацией для поиска файла маппинга и символов
    ├── res - папка с ресурсами, которые будут использованы для сборки приложения
    │   ├── raw
    │   │   └── keep_appmetrica_resources.xml - правила для R8 по сохранению ресурсов
    │   └── values
    │       └── appmetrica_resources.xml - необходимые для работы ресурсы
    ├── result - папка с архивами, которые нужно самостоятельно загружать в режиме offline
    │   ├── mapping.zip - финальный архив с маппингами
    │   └── symbols.zip - финальный архив с символами
    └── symbols - папка с символами, которые получились из so файлов
        ├── libmyapplication_0E6CC10E8293F1B2DF0293FBE44887AD0.ysym
        ├── libmyapplication_3CDE92724603DA3A59BC6E311625A4000.ysym
        ├── libmyapplication_6F5C61C0E96CAEFD1E7ED491F806DA100.ysym
        └── libmyapplication_F3E083A014DD2840F0E730B6BB138E4A0.ysym

Ошибки при сборке

Возможные ошибки при сборке:

IllegalStateException — включите обфускацию кода с помощью ProGuard или R8 Compiler;
HttpResponseException — проверьте подключение к интернету.

При возникновении других ошибок обращайтесь в техническую поддержку.

Узнайте больше

Если вы не нашли ответ на свой вопрос, то вы можете задать его через форму обратной связи. Пожалуйста, опишите возникшую проблему как можно подробнее. Если возможно, приложите скриншот.

Написать в службу поддержки

Была ли статья полезна?

Анализ крэшей

Поддержка отложенных deeplinks