---
metadata:
  - name: generator
    content: Diplodoc Platform v5.50.6
alternate:
  - https://yandex.com/support/appmetrica-io/en/sdk/android/analytics/android-gradle-plugin.md
  - https://yandex.com/support/appmetrica-io/ru/sdk/android/analytics/android-gradle-plugin.md
---
> **Documentation Index:** Fetch the complete configuration index at https://yandex.com/support/appmetrica-io/ru/llms.txt

# AppMetrica Gradle Plugin

AppMetrica позволяет собирать информацию о нативных и java-крэшах. Их можно анализировать в отчете [Крэши](https://yandex.com/support/appmetrica-io/ru/mobile-reports/crashes-and-errors.md). См. также раздел [Крэши/ошибки](https://yandex.com/support/appmetrica-io/ru/data-collection/about-crashes-and-errors.md).

Чтобы уменьшить размер приложения, код [оптимизируют](https://developer.android.com/studio/build/shrink-code) во время релизной сборки.

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

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

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

## Ограничения {#restrictions}

- Плагин подключается только в модули с `com.android.application`. В модулях `com.android.library` он не применяется.

- Загружайте mapping-файлы, если вы используете [ProGuard](https://www.guardsquare.com/en/products/proguard/manual) или [R8](https://r8.googlesource.com/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` через переменную окружения:

   ```kotlin translate=no
   appmetrica {
       enable.set(providers.environmentVariable("CI").map { it == "true" }.orElse(false))
   }
   ```

## Подключение плагина {#connecting}

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

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

   ```kotlin translate=no
   plugins {
       id("io.appmetrica.analytics") version "2.1.0" apply false
   }
   ```

   {% cut "Подключение с использованием `buildscript`" %}

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

   ```kotlin translate=no
   buildscript {
      repositories {
          mavenCentral()
      }
      dependencies {
          classpath("io.appmetrica.analytics:gradle:2.1.0")
      }
   }
   ```

   {% endcut %}

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

   ```kotlin translate=no
   plugins {
       id("com.android.application")
       id("io.appmetrica.analytics")
   }

   appmetrica {
       postApiKey.set("Post Api key")
       ndk {
           enable.set(true) // Optional. Включите, если в проекте есть нативный код и нужны нативные крэши
       }
   }
   ```

   Остальные параметры и их значения по умолчанию описаны в разделе [Параметры плагина](#parameters).

## Типовые задачи {#recipes}

В типовом случае не меняйте настройки: `enable` по умолчанию `true` только для `buildType = 'release'`, а `ndk.enable` по умолчанию `false` (включайте, только если в проекте есть нативный код и вам нужны нативные крэши). Поэтому для проекта без обфускации вне `release` и без NDK-символов плагин уже работает оптимально из коробки.

{% cut "Собрать mapping и NDK-символы для отдельного нерелизного buildType, не тратя квоту на загрузку" %}

Это потребуется, например, если для отдельного нерелизного `buildType` (условно `snapshot`) тоже нужны mapping и NDK-символы, но при этом не хочется тратить на такую сборку дневную квоту загрузки на сервер. 

Так как `enable`, `offline` и `ndk.enable` определяются отдельно для каждого варианта сборки, точечно переопределяйте их для нужного `buildType` через иерархическую конфигурацию (см. [Иерархическая конфигурация](#hierarchical-config)):

```kotlin translate=no
android {
    buildTypes {
        // Кроме релиза, mapping и NDK-символы нужны еще и для сборки snapshot
        named("snapshot") {
            appmetrica {
                // По умолчанию enable=true только для release — для snapshot включаем явно,
                // иначе mapping не будет ни собираться, ни загружаться
                enable.set(true)

                ndk {
                    // По умолчанию ndk.enable=false — для snapshot включаем явно,
                    // иначе NDK-символы не будут собираться
                    enable.set(true)
                }

                // Чтобы не тратить на snapshot дневную квоту загрузки на сервер, не грузим
                // mapping и символы автоматически. Они все равно соберутся локально в
                // build/appmetrica/<variant>/result, и их можно будет загрузить вручную,
                // см. "Ручная загрузка"
                offline.set(true)
            }
        }
    }
}

appmetrica {
    // postApiKey задается один раз в глобальном блоке и действует для всех вариантов,
    // включая snapshot ниже — задавать его повторно в per-buildType блоке не требуется
    // (иначе при разных значениях получите "Conflicting values for postApiKey")
    postApiKey.set("Post Api key")
}
```

{% endcut %}

## Параметры плагина {#parameters}

Пример конфигурации со всеми доступными параметрами:

```kotlin translate=no
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
    }
}
```

#|
|| **Параметр** | **Описание** ||
|| `postApiKey*` | Post API key. `String`.
Post API key можно получить в разделе **Настройки** в AppMetrica. Он используется для идентификации вашего приложения.

Если `offline = true`, то параметр не является обязательным.

Особенность для иерархической конфигурации: значение должно совпадать во всех источниках, где оно задано. Если в разных источниках указаны разные значения, плагин пишет ошибку в лог и считает ключ не заданным (см. [Иерархическая конфигурация](#hierarchical-config)). ||
|| `enable` | Включает или выключает плагин для данного варианта сборки. `Boolean`.
Если плагин выключен, apk не меняется, mapping не собирается и не загружается, генерация ресурсов не выполняется.

Не влияет на сбор и загрузку NDK-символов — за это отвечает независимый параметр `ndk.enable` (см. ниже).

По умолчанию `true` только для `buildType = 'release'`, иначе `false`.

Поддерживает иерархическую конфигурацию (см. [Иерархическая конфигурация](#hierarchical-config)). ||
|| `offline` | Включает режим `offline`. `Boolean`.

Влияет на загрузку и mapping, и NDK-символов одновременно (независимо от того, включен ли `enable` или `ndk.enable` — офлайн-режим общий для обоих).

Допустимые значения:

* `true` — символы и mapping не загружаются в AppMetrica. Архивы кладутся в `build/appmetrica/<variant>/result/`, пути выводятся в лог. Архивы можно загрузить вручную через веб-интерфейс.
* `false` — символы и mapping автоматически загружаются.

Значение по умолчанию: `false`.

Поддерживает иерархическую конфигурацию (см. [Иерархическая конфигурация](#hierarchical-config)). ||
|| `mappingFile` | Путь к mapping-файлу. `RegularFileProperty` (в Kotlin DSL задается через `file("...")`).

Значение по умолчанию: mapping-файл из сборки (артефакт `OBFUSCATION_MAPPING_FILE` AGP). Переопределяйте, только если хотите загрузить mapping из необычного места.

Поддерживает иерархическую конфигурацию (см. [Иерархическая конфигурация](#hierarchical-config)). ||
|| `enableAnalytics` | Включает отправку статистики об использовании плагина в AppMetrica. `Boolean`.

Допустимые значения:

* `true` — отправка статистики включена.
* `false` — отправка статистики выключена.

Значение по умолчанию: `true`. ||
|| `allowTwoAppMetricas` | Поведение при наличии в проекте двух разных библиотек AppMetrica (`io.appmetrica.analytics:analytics` и `com.yandex.android:mobmetricalib`) одновременно. `Boolean`.

Допустимые значения:

* `false` — если найдены обе библиотеки, сборка **падает** с ошибкой;
* `true` — наличие обеих библиотек допускается, в лог пишется предупреждение.

Значение по умолчанию: `false`.

Поддерживает иерархическую конфигурацию (см. [Иерархическая конфигурация](#hierarchical-config)). ||
|| `ndk` | Параметр необходим для загрузки символов из SO-файла, чтобы отслеживать нативные крэши. ||
|| `ndk.enable` | Включает или выключает обработку и загрузку символов из SO-файлов. `Boolean`.

Если включен, таски обработки символов и загрузки запускаются автоматически после сборки.

Значение по умолчанию: `false`.

Поддерживает иерархическую конфигурацию (см. [Иерархическая конфигурация](#hierarchical-config)). ||
|| `ndk.soFiles` | SO-файлы для обработки. `ConfigurableFileCollection`. Используйте `.from(...)` для добавления файлов.

По умолчанию плагин берет SO-файлы из артефакта `MERGED_NATIVE_LIBS` AGP — туда уже попадают `src/main/jniLibs/**` и выходы CMake/ndk-build.

Переопределяйте, если ваши SO-файлы лежат в нестандартном месте или если плагин их не находит.

Поведение при иерархической конфигурации: коллекции из всех источников **объединяются** (см. [Иерархическая конфигурация](#hierarchical-config)). ||
|| `ndk.additionalSoFiles` | Дополнительные SO-файлы. `ConfigurableFileCollection`. Используйте `.from(...)` для добавления файлов.

В отличие от `soFiles`, не заменяет дефолт, а дополняет его.

Поведение при иерархической конфигурации: коллекции из всех источников **объединяются**. ||
|| `ndk.addNdkCrashesDependency` | Автоматически добавлять зависимость `io.appmetrica.analytics:analytics-ndk-crashes` в конфигурацию `<variant>Implementation`. `Boolean`.

Значение по умолчанию: `true`.

Поддерживает иерархическую конфигурацию (см. [Иерархическая конфигурация](#hierarchical-config)). ||
|#

{% note info %}

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

{% endnote %}

### Иерархическая конфигурация {#hierarchical-config}

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

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

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

{% note info %}

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

{% endnote %}

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

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

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

Пример:
```kotlin translate=no
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(...)` в одном из источников — дефолт тогда не используется.

#### Пример

```kotlin translate=no
// Глобальные настройки для всех вариантов
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"))
        }
    }
}
```

{% note tip %}

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

{% endnote %}

## Ручная загрузка {#manual-loading}

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

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

   ```kotlin translate=no
   appmetrica {
       offline.set(true)
   }
   ```

   В режиме `offline` параметр `postApiKey` указывать не обязательно.

2. Соберите нужный вариант приложения (например, `./gradlew assembleRelease`). Архивы появятся в `<appModule>/build/appmetrica/<variant>/result/`:

   - `mapping.zip` — для java-крэшей;
   - `symbols.zip` — для нативных крэшей, если включен `ndk.enable`.

3. В интерфейсе AppMetrica перейдите в настройки приложения из меню слева.
4. Откройте вкладку **Крэши** → **Android**.
5. Нажмите кнопку **Выберите файл** и загрузите нужный архив.

## Таски плагина {#tasks}

Для каждого варианта сборки `<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`) автоматически запускает загрузку. Запустить загрузку вручную можно так:

```bash
./gradlew uploadReleaseAppMetricaMapping
./gradlew uploadReleaseAppMetricaNdkSymbols
```

## Ошибки и предупреждения при сборке {#errors}

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

- `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>` — параметр не задан ни в одном источнике, используется дефолт. Полезно для отладки, если кажется, что настройка «не применилась».

При возникновении других ошибок обращайтесь в [техническую поддержку](https://yandex.com/support/appmetrica-io/ru/troubleshooting/feedback-new.md).

## Узнайте больше {#learn-more}

- [Отчет Крэши и ошибки](https://yandex.com/support/appmetrica-io/ru/mobile-reports/crashes-and-errors.md)
- [Документация Android](https://developer.android.com/topic/performance/vitals/crash)

<!-- source: ru/_includes/feedback-button-3.md -->
Если вы не нашли ответ на свой вопрос, то вы можете задать его через форму обратной связи. Пожалуйста, опишите возникшую проблему как можно подробнее. Если возможно, приложите скриншот.

<a href="../../../troubleshooting/feedback-new">
  <span class="button">Написать в службу поддержки</span>
</a>

<a href="../../../troubleshooting/feedback-docs">
  <span class="button">Предложить улучшение для документации</span>
</a>
<!-- endsource: ru/_includes/feedback-button-3.md -->