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

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

  • Плагин не поддерживает Configuration Cache в Gradle. Все задачи плагина помечены как несовместимые с этой функцией, и при их использовании вы увидите предупреждение от Gradle.

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

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

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

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

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

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

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

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

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

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

  3. Если параметр ndk включен, то для отправки отладочных символов используется задача Gradle upload${variant.name.capitalize()}AppMetricaNdkSymbols. Чтобы вызывать задачу автоматически, можно добавить в файл app/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-файла со сборкой приложения.

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

    appmetrica {
    offline = { 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