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.0 до 8.13.+ (кроме 8.0.+);
    • gradle с 7.4 до 9.2.1. Работа плагина с другими версиями не гарантируется.

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

  • Для локальных сборок рекомендуется отключать плагин. Это позволит ускорить сборку проекта. Плагин необходимо включать только для сборок на CI.

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

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

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

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

    plugins {
    id "io.appmetrica.analytics" version "2.0.1" apply false
}
    Подключение с использованием buildscript

    Добавьте в корневой 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'
   }
}

  2. Добавьте в 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
    }
}

    Совет

    Плагин поддерживает иерархическую конфигурацию per-buildType, per-flavor и per-variant. Приоритет настроек: глобальные > вариант > buildType > flavor > значение по умолчанию.

    Пример иерархической конфигурации
    // Глобальные настройки (наивысший приоритет)
appmetrica {
    postApiKey.set("default-key")
    enable.set(true)
}

// Настройки per-buildType
android.buildTypes {
    named("release") {
        appmetrica {
            postApiKey.set("release-key")
        }
    }
    named("debug") {
        appmetrica {
            enable.set(false)
            offline.set(true)
        }
    }
}

// Настройки per-flavor
android.productFlavors {
    named("prod") {
        appmetrica {
            postApiKey.set("prod-key")
        }
    }
}

    // Глобальные настройки (наивысший приоритет)
appmetrica {
    postApiKey = "default-key"
    enable = true
}

// Настройки per-buildType
android.buildTypes {
    release {
        appmetrica {
            postApiKey = "release-key"
        }
    }
    debug {
        appmetrica {
            enable = false
            offline = true
        }
    }
}

// Настройки per-flavor
android.productFlavors {
    prod {
        appmetrica {
            postApiKey = "prod-key"
        }
    }
}

    Параметр

    Описание

    postApiKey*

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

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

    Поддерживает иерархическую конфигурацию per-buildType, per-flavor и per-variant.

    enable

    Включает или выключает плагин для данного варианта сборки. Boolean.
    Если плагин выключен, apk не меняется и mapping-файл не загружается.

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

    Поддерживает иерархическую конфигурацию per-buildType, per-flavor и per-variant.

    offline

    Включает режим offline. Boolean.

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

    • true — не загружает файл в AppMetrica. Если включен, после сборки выводит путь до архива в лог. Его можно загрузить вручную через веб-интерфейс.
    • false — автоматически загружает mapping-файл.

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

    Поддерживает иерархическую конфигурацию per-buildType, per-flavor и per-variant.

    mappingFile

    Путь к mapping-файлу, который надо загрузить. File.

    Значение по умолчанию: mapping-файл из сборки.

    enableAnalytics

    Включает отправку статистики об использовании плагина в AppMetrica. Boolean.

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

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

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

    allowTwoAppMetricas

    Проверяет использование двух библиотек AppMetrica одновременно. Boolean.

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

    • false — плагин проверяет, что в проекте используется только одна версия библиотеки io.appmetrica.analytics:analytics или com.yandex.android:mobmetricalib. Если это не так, выбрасывается исключение.
    • true — плагин проверяет использование двух библиотек AppMetrica одновременно, результат проверки пишется в лог.

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

    Поддерживает иерархическую конфигурацию per-buildType, per-flavor и per-variant.

    ndk

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

    ndk.enable

    Включает или выключает загрузку символов из SO-файлов. Boolean.

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

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

    Поддерживает иерархическую конфигурацию per-buildType, per-flavor и per-variant.

    ndk.soFiles

    SO-файлы для обработки. ConfigurableFileCollection. Используйте .from(...) для добавления файлов.

    По умолчанию плагин ищет SO-файлы в папках проекта Android Studio.

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

    ndk.additionalSoFiles

    Дополнительные SO-файлы, символы которых необходимо загрузить. ConfigurableFileCollection. Используйте .from(...) для добавления файлов.

    ndk.addNdkCrashesDependency

    Включает автоматическое добавление зависимости от io.appmetrica.analytics:analytics-ndk-crashes. Boolean.

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

    Поддерживает иерархическую конфигурацию per-buildType, per-flavor и per-variant.

    Примечание

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

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

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

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

    appmetrica {
    offline.set(true)
}

    appmetrica {
    offline = true
}

  2. В интерфейсе AppMetrica перейдите в настройки приложения из меню слева.

  3. Откройте вкладку Крэши → Android.

  4. Нажмите кнопку Выберите файл и загрузите 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