AppMetrica Gradle Plugin

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

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

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

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

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

Ограничения

Плагин подключается только в модули с com.android.application. В модулях com.android.library он не применяется.
Загружайте mapping-файлы, если вы используете ProGuard или R8. Если вы не сжимаете и не обфусцируете код, не подключайте плагин.
Работа плагина зависит от версий com.android.tools.build:gradle (AGP) и gradle. Поддерживается работа плагина со следующими версиями:
- com.android.tools.build:gradle с 7.2.0 до 8.13.+ (кроме 8.0.+);
- gradle с 7.4 до 9.2.1. Работа плагина с другими версиями не гарантируется.
Работа плагина при использовании gradle 8.0 и AGP 7.4.* вместе не гарантируется.
Для локальных сборок рекомендуем отключать плагин — это ускоряет сборку. Включайте его только на CI. Удобный паттерн — управлять флагом enable через переменную окружения:
```
appmetrica {
    enable.set(providers.environmentVariable("CI").map { it == "true" }.orElse(false))
}
```

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

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

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

build.gradle.kts

build.gradle

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

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

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

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

build.gradle.kts

build.gradle

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

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

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

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
    }
}

Параметр	Описание
`postApiKey*`	Post API key. `String`. Post API key можно получить в разделе Настройки в AppMetrica. Он используется для идентификации вашего приложения. Если `offline = true`, то параметр не является обязательным. Особенность для иерархической конфигурации: значение должно совпадать во всех источниках, где оно задано. Если в разных источниках указаны разные значения, плагин пишет ошибку в лог и считает ключ не заданным (см. Иерархическая конфигурация).
`enable`	Включает или выключает плагин для данного варианта сборки. `Boolean`. Если плагин выключен, apk не меняется, mapping и символы не собираются и не загружаются, генерация ресурсов не выполняется. По умолчанию `true` только для `buildType = 'release'`, иначе `false`. Поддерживает иерархическую конфигурацию (см. Иерархическая конфигурация).
`offline`	Включает режим `offline`. `Boolean`. Допустимые значения: `true` — не загружает файлы в AppMetrica. Архивы кладутся в `build/appmetrica/<variant>/result/`, пути выводятся в лог. Архивы можно загрузить вручную через веб-интерфейс. `false` — автоматически загружает mapping и символы. Значение по умолчанию: `false`. Поддерживает иерархическую конфигурацию (см. Иерархическая конфигурация).
`mappingFile`	Путь к mapping-файлу. `RegularFileProperty` (в Kotlin DSL задается через `file("...")`). Значение по умолчанию: mapping-файл из сборки (артефакт `OBFUSCATION_MAPPING_FILE` AGP). Переопределяйте, только если хотите загрузить mapping из необычного места. Поддерживает иерархическую конфигурацию (см. Иерархическая конфигурация).
`enableAnalytics`	Включает отправку статистики об использовании плагина в AppMetrica. `Boolean`. Допустимые значения: `true` — отправка статистики включена. `false` — отправка статистики выключена. Значение по умолчанию: `true`.
`allowTwoAppMetricas`	Поведение при наличии в проекте двух разных библиотек AppMetrica (`io.appmetrica.analytics:analytics` и `com.yandex.android:mobmetricalib`) одновременно. `Boolean`. Допустимые значения: `false` — если найдены обе библиотеки, сборка падает с ошибкой; `true` — наличие обеих библиотек допускается, в лог пишется предупреждение. Значение по умолчанию: `false`. Поддерживает иерархическую конфигурацию (см. Иерархическая конфигурация).
`ndk`	Параметр необходим для загрузки символов из SO-файла, чтобы отслеживать нативные крэши.
`ndk.enable`	Включает или выключает обработку и загрузку символов из SO-файлов. `Boolean`. Если включен, таски обработки символов и загрузки запускаются автоматически после сборки. Значение по умолчанию: `false`. Поддерживает иерархическую конфигурацию (см. Иерархическая конфигурация).
`ndk.soFiles`	SO-файлы для обработки. `ConfigurableFileCollection`. Используйте `.from(...)` для добавления файлов. По умолчанию плагин берет SO-файлы из артефакта `MERGED_NATIVE_LIBS` AGP — туда уже попадают `src/main/jniLibs/` и выходы CMake/ndk-build. Переопределяйте, если ваши SO-файлы лежат в нестандартном месте или если плагин их не находит. Поведение при иерархической конфигурации: коллекции из всех источников объединяются** (см. Иерархическая конфигурация).
`ndk.additionalSoFiles`	Дополнительные SO-файлы. `ConfigurableFileCollection`. Используйте `.from(...)` для добавления файлов. В отличие от `soFiles`, не заменяет дефолт, а дополняет его. Поведение при иерархической конфигурации: коллекции из всех источников объединяются.
`ndk.addNdkCrashesDependency`	Автоматически добавлять зависимость `io.appmetrica.analytics:analytics-ndk-crashes` в конфигурацию `<variant>Implementation`. `Boolean`. Значение по умолчанию: `true`. Поддерживает иерархическую конфигурацию (см. Иерархическая конфигурация).

Примечание

Если параметр ndk.enable включен, таски обработки и загрузки отладочных символов запускаются автоматически после сборки. Дополнительная ручная настройка не требуется.

Иерархическая конфигурация

Плагин поддерживает четыре уровня конфигурации:

appmetrica {
    // Глобальная конфигурация
    variants {
        create("<variantName>") {
            // Конфигурация для варианта
        }
    }
}

android {
    buildTypes {
        named("<buildTypeName>") {
            appmetrica {
                // Конфигурация для buildType
            }
        }
    }
    productFlavors {
        named("<flavorName>") {
            appmetrica {
                // Конфигурация для flavor
            }
        }
    }
}

Примечание

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

`enable`, `offline`, `ndk.enable`, `allowTwoAppMetricas`, `enableAnalytics`, `ndk.addNdkCrashesDependency`

Логика: «отключение всегда побеждает».

Если хотя бы в одном источнике значение равно false — итог false.
Иначе, если хотя бы в одном источнике значение равно true — итог true.
Иначе берется значение по умолчанию.

Пример:

appmetrica {
    enable.set(true)
}

android {
    buildTypes {
       debug {
           appmetrica {
               enable.set(false)
           }
       }
    }
}

В результате для debug будет false, а для остальных будет true.

`postApiKey`

Логика: «значение должно быть уникальным».

Если параметр задан только в одном источнике — используется это значение.
Если задан в нескольких источниках с одним и тем же значением — используется оно.
Если в разных источниках указаны разные значения — в лог пишется ошибка Conflicting values for postApiKey, и используется значение по умолчанию (пустая строка). Загрузка тогда не выполнится — плагин дополнительно выдаст предупреждение postApiKey is not set.

Поэтому задавайте postApiKey только в одном месте — обычно в глобальном блоке или в нужном flavor.

`mappingFile`

Логика: «приоритетный поиск».

Приоритет источников: глобальный блок > per-variant > per-buildType > первый сконфигурированный flavor > значение по умолчанию (mapping из сборки). Используется значение из первого источника, в котором параметр задан.

`ndk.soFiles`, `ndk.additionalSoFiles`

Логика: «объединение коллекций».

Все непустые .from(...) из всех уровней объединяются в одну коллекцию. Если ни на одном уровне коллекция не сконфигурирована — для soFiles используется дефолт из AGP, для additionalSoFiles — пустая коллекция. Чтобы заменить набор файлов из дефолта, задайте soFiles.from(...) в одном из источников — дефолт тогда не используется.

Пример

build.gradle.kts

build.gradle

// Глобальные настройки для всех вариантов
appmetrica {
    enableAnalytics.set(true)
}

android {
    buildTypes {
        release {
            // Загрузка NDK-символов нужна только для релизных сборок
            appmetrica {
                ndk {
                    enable.set(true)
                }
            }
        }
    }

    productFlavors {
        // У каждого flavor свой ключ — например, разные приложения для prod и dev
        create("prod") {
            appmetrica {
                postApiKey.set("prod-post-api-key")
            }
        }
        create("dev") {
            appmetrica {
                postApiKey.set("dev-post-api-key")
            }
        }
    }
}

// Per-variant: точечное переопределение для конкретного варианта
appmetrica {
    variants.create("prodRelease") {
        ndk {
            additionalSoFiles.from(file("extra-symbols"))
        }
    }
}

// Глобальные настройки для всех вариантов
appmetrica {
    enableAnalytics = true
}

android {
    buildTypes {
        release {
            // Загрузка NDK-символов нужна только для релизных сборок
            appmetrica {
                ndk {
                    enable = true
                }
            }
        }
    }

    productFlavors {
        // У каждого flavor свой ключ — например, разные приложения для prod и dev
        prod {
            appmetrica {
                postApiKey = "prod-post-api-key"
            }
        }
        dev {
            appmetrica {
                postApiKey = "dev-post-api-key"
            }
        }
    }
}

// Per-variant: точечное переопределение для конкретного варианта
appmetrica {
    variants.create("prodRelease") {
        ndk {
            additionalSoFiles.from(file("extra-symbols"))
        }
    }
}

Совет

Чтобы понять, какие значения плагин фактически применил к варианту, посмотрите лог сборки: для каждого параметра пишется строка вида Using value 'X' from <source> for <parameter> или Using default value '...' for ....

Таски плагина

Для каждого варианта сборки <variant> (Release, ProdRelease и т. п.) плагин регистрирует следующие таски:

Имя таска	Назначение
`check<variant>AppMetricaDependencies`	Проверяет, что в проекте используется ровно одна библиотека AppMetrica (см. `allowTwoAppMetricas`).
`create<variant>AppMetricaRes`	Генерирует ресурсы в `build/appmetrica/<variant>/res/`; результат подмешивается в ресурсы приложения.
`zip<variant>AppMetricaFiles`	Собирает `mapping.zip` (`info.txt` + mapping).
`upload<variant>AppMetricaMapping`	Загружает `mapping.zip` в AppMetrica (в режиме `offline` — пропускается, архив остается в `result/`).
`generate<variant>AppMetricaNdkSymbols`	Преобразует SO-файлы в `.ysym`.
`zip<variant>AppMetricaNdkFiles`	Собирает `symbols.zip` (`info.txt` + `.ysym`).
`upload<variant>AppMetricaNdkSymbols`	Загружает `symbols.zip` в AppMetrica.

Таски загрузки навешиваются как finalizedBy на assemble<variant> и bundle<variant>. Поэтому обычная сборка (./gradlew assembleRelease или ./gradlew bundleRelease) автоматически запускает загрузку. Запустить загрузку вручную можно так:

./gradlew uploadReleaseAppMetricaMapping
./gradlew uploadReleaseAppMetricaNdkSymbols

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

Для ручной загрузки нужно подключить плагин с режимом offline = true. Это нужно, чтобы плагин сгенерировал info.txt с метаинформацией, по которой сервер свяжет архив со сборкой.

В файле app/build.gradle включите режим offline:
build.gradle.kts

build.gradle
```
appmetrica {
    offline.set(true)
}
```
```
appmetrica {
    offline = true
}
```
В режиме offline параметр postApiKey указывать не обязательно.
Соберите нужный вариант приложения (например, ./gradlew assembleRelease). Архивы появятся в <appModule>/build/appmetrica/<variant>/result/:
- mapping.zip — для java-крэшей;
- symbols.zip — для нативных крэшей, если включен ndk.enable.
В интерфейсе AppMetrica перейдите в настройки приложения из меню слева.
Откройте вкладку Крэши → Android.
Нажмите кнопку Выберите файл и загрузите нужный архив.

Ошибки и предупреждения при сборке

Ошибки, прерывающие сборку

IllegalStateException — обфускация кода не включена. Включите ProGuard или R8.
HttpResponseException — не удалось загрузить архив. Проверьте подключение к интернету и корректность postApiKey.
Ошибка проверки зависимостей — в проекте найдены две библиотеки AppMetrica одновременно (io.appmetrica.analytics:analytics и com.yandex.android:mobmetricalib). Уберите одну из них или, временно, выставьте allowTwoAppMetricas = true.

Предупреждения (сборка не падает, но загрузка может не выполниться)

Эти сообщения важно отслеживать, особенно на CI — они означают, что что-то пошло не так, но Gradle об этом не сообщит.

AppMetrica plugin is enabled for variant '<variant>' but postApiKey is not set. Upload will fail. Set postApiKey or enable offline mode. — для варианта включен upload, но ключ пуст. Задайте postApiKey или включите offline.
Conflicting values for postApiKey: ... — postApiKey задан в разных источниках с разными значениями. Плагин использует пустой ключ — загрузка упадет. Оставьте задание ключа только в одном месте либо синхронизируйте значения.
Using default value '...' for <parameter> — параметр не задан ни в одном источнике, используется дефолт. Полезно для отладки, если кажется, что настройка «не применилась».

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

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

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

Написать в службу поддержки Предложить улучшение для документации

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

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

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

AppMetrica Gradle Plugin

Ограничения

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

Иерархическая конфигурация

enable, offline, ndk.enable, allowTwoAppMetricas, enableAnalytics, ndk.addNdkCrashesDependency

postApiKey

mappingFile

ndk.soFiles, ndk.additionalSoFiles

Пример

Таски плагина

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

Ошибки и предупреждения при сборке

Ошибки, прерывающие сборку

Предупреждения (сборка не падает, но загрузка может не выполниться)

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

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

`enable`, `offline`, `ndk.enable`, `allowTwoAppMetricas`, `enableAnalytics`, `ndk.addNdkCrashesDependency`

`postApiKey`

`mappingFile`

`ndk.soFiles`, `ndk.additionalSoFiles`