Подключение Крашлитики для Android

Краткое содержание

Версия 0.5.0 поддерживает AGP до 9., прекращена поддержка версий ниже 8.1. Плагин собран на Gradle 9., AGP 9.1.1 и Kotlin 2.2.21. Для приложений с AGP ниже 9. (например, 8.11.1) следует использовать версию плагина 0.4.0, функционал которой идентичен.

Как эта статья может мне помочь? Вы узнаете, как связать ошибки приложения с маппинг-файлами для их расшифровки в МТС Аналитике (сервис «Крашлитика»). Это позволяет корректно анализировать фатальные ошибки, сопоставляя их с конкретными сборками приложения.

Требования

Android, Kotlin
AGP версии 8.1.0 и выше
SDK МТС Аналитики

Для отправки событий необходимо подключить и проинициализировать SDK Аналитики, включив перехват крэшей методом setCrashReportingEnabled(true). Если отсутствует ID потока, его можно запросить по адресу analytics.support@mts.ru.

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

В статье приведена пошаговая инструкция по подключению плагина для проектов на Groovy и Kotlin DSL. Процесс включает добавление репозитория artifactory в settings.gradle, подключение зависимости в build.gradle, применение плагина и настройку параметров через mtsaPluginMapping. После конфигурации проект необходимо синхронизировать.

Конфигурация плагина

В тексте вы найдете руководство по решению задачи настройки параметров плагина. Доступные параметры включают идентификацию потока (flowId), учетные данные (clientId, clientSecret), настройки прокси и управление версиями сборок.

allowUploadMappingFiles: управляет автоматической загрузкой файлов.
releaseBuildVariants: обязательное поле для указания релизных вариантов сборок.
ignoredBuildTypes и ignoredFlavors: позволяют исключить определенные типы сборок из обработки.
onlyReleaseEnabled: по умолчанию включено, ограничивает создание ID только для релизных сборок.

Для включения логирования отладочной информации добавьте свойство ma_debug_logging_is_enabled=true в файл gradle.properties.

Генерация файла

После сборки приложения с включенной минификацией (minifyEnabled true) в папке build/tmp/mtsa/mapping/variantName/ создается файл mapping.zip. Плагин автоматически добавляет в конец файла уникальный ID сборки (mfid). SDK Аналитики отправляет события ошибок вместе с этим ID, что позволяет сервису Крашлитика сопоставить маппинг с конкретными ошибками.

Загрузка файла в Крашлитику

В тексте вы найдете руководство по решению задачи загрузки маппинг-файлов двумя способами:

Автоматически: требуется включить allowUploadMappingFiles=true и настроить учетные данные (flowId, clientId, clientSecret) и параметры прокси. Файл будет загружаться во время сборки.
Вручную: автоматическая отправка отключена (allowUploadMappingFiles=false). Необходимо самостоятельно взять сгенерированный mapping.zip и загрузить его в сервис Крашлитика.

Смотреть данные

Статистика ошибок отображается в отчете «Крашлитика» в МТС Аналитике.

Версия 0.5.0

Важно

Начиная с версии 0.5.0

Добавлена поддержка AGP версий до 9.*
Прекращена поддержка AGP версий до 8.1
Плагин собран под gradle 9., AGP 9.1.1, kotlin 2.2.21

Если ваше приложение собирается под AGP ниже 9.* (например 8.11.1), используйте версию плагина 0.4.0. Функционал плагина v0.4.0 и v0.5.0 идентичен.

Информацию об ошибках в приложении можно передавать в МТС Аналитику, в сервис «Крашлитика».

Для расшифровки Stack Trace ошибок, переданных в Аналитику, важно связать их с маппинг-файлом. Для этого необходимо установить плагин.

Как это работает

SDK Аналитики подключен к проекту, проинициализирован, включен перехват крэшей (фатальных ошибок).
Плагин Крашлитики подключен к проекту.
На этапе сборки приложения создаётся маппинг-файл.
Плагин присваивает сборке уникальный идентификатор, добавляя его в маппинг и в константы приложения.
Разработчик выкладывает сборку с таким ID в маркет.
SDK Аналитики начинает отправлять события ошибок с тем же ID сборки.
Разработчик загружает в Крашлитику маппинг, который содержит ID сборки.
МТС Аналитика сопоставляет маппинг с ошибками по номеру сборки для дальнейшего анализа в отчёте.

Требования

Android, Kotlin
AGP version to 8.1.0 +
SDK МТС Аналитики

Чтобы события отправлялись в Аналитику, подключите и проинициализируйте SDK Аналитики. Включите отлов крэшей setCrashReportingEnabled(true)

val mtsAnalytics: ru.mts.analytics.sdk.publicapi.api.MtsAnalyticsApi =
    ru.mts.analytics.sdk.publicapi.MTSAnalytics.getInstance(
        context = this,
        config = MtsAnalyticsConfig.Builder(flowId = "aabb1111-2c2d-3e3f-4444-555566667777")
            .setCrashReportingEnabled(true)
            .build()
    )

Заметка

Если вы не получили ID потока, отправьте письмо на analytics.support@mts.ru с темой «Получение Flow ID». Идентификатор нужен для отправки данных с вашего ресурса в МТС Аналитику.

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

Groovy
Kotlin DSL

В settings.gradle добавьте зависимость на artifactory

pluginManagement {
    repositories {
        maven {
            name "mts_analytics_plugins_dev"
            url "https://artifacts.services.mts.ru/repository/maven-public-mtsm-maven-local/"
            content {
                includeGroupAndSubgroups("ru.mts.analytics")
            }
        }
    }
}

В build.gradle добавьте

buildscript {
    dependencies {
        classpath("ru.mts.analytics:android-plugin-mapping:0.4.0")
    }
}

В build.gradle модуля, к которому подключается зависимость, в заголовок файла, блок apply plugins, добавьте

plugins {
    id 'ru.mts.analytics.android-plugin-mapping'
}

Ниже в том же файле вызовите plugin extension mtsaPluginMapping и укажите значения параметров

mtsaPluginMapping {
    flowId = "aabb1111-2c2d-3e3f-4444-555566667777"
    clientId = "ccdd3333-d4e4-5566-d7e7-88889999ffff"
    clientSecret = "0AaBb1CcDEeXYzXyzXYz12BbCc"
    proxyHost = "ci.proxy.company.ru"
    proxyPort = 1234
    proxyUser = techUserProxyLogin
    proxyPassword = techUserProxyPassword
    allowUploadMappingFiles = true
    showUploadingProgress = false
    uploadTryCount = 1
    onlyReleaseEnabled = true
    releaseBuildVariants = [
        "advancedRelease",
        "proRelease",
        "freeRelease",
        "promoRelease",
    ]
    ignoredBuildTypes = [
        "debug",
    ]
    ignoredFlavors = [
        "free",
        "promo",
    ]
    failOnError = true
}

Примечание

Где buildTypes, flavor dimensions и buildVariants соответствуют настройкам вашего проекта.

В примере выше flowId, clientId, clientSecret и параметры прокси - демонстрационные. Используйте реальные значения.

Набор releaseBuildVariants обязательный к заполнению и не может примать пустое значение.

Синхронизируйте проект.

В settings.gradle.kts добавьте зависимость на artifactory

pluginManagement {
    repositories {
        maven {
            name = "mts_analytics_plugins_dev"
            url = uri("https://artifactory.mts.ru/artifactory/maven-public-mtsm-maven-local/")
            content {
                includeGroupAndSubgroups("ru.mts.analytics")
            }
        }
    }
}

В build.gradle.kts, в заголовок файла, блок buildscript добавьте

buildscript {
    dependencies {
        classpath("ru.mts.analytics:android-plugin-mapping:0.4.0")
    }
}

В build.gradle.kts модуля, к которому подключается зависимость, добавьте в заголовок файла, верхними строчками выше блока apply plugins

import ru.mts.analytics.gradle.MappingPluginExtension

В заголовок файла, под импортами, блок apply plugins

plugins {
    id("ru.mts.analytics.android-plugin-mapping")
}

Ниже, в том же файле, вызовите plugin extension mtsaPluginMapping и укажите значения параметров

configure<MappingPluginExtension> {
    flowId = "aabb1111-2c2d-3e3f-4444-555566667777"
    clientId = "ccdd3333-d4e4-5566-d7e7-88889999ffff"
    clientSecret = "0AaBb1CcDEeXYzXyzXYz12BbCc"
    proxyHost = "ci.proxy.company.ru"
    proxyPort = 1234
    proxyUser = techUserProxyLogin
    proxyPassword = techUserProxyPassword
    allowUploadMappingFiles = true
    showUploadingProgress = false
    uploadTryCount = 1
    onlyReleaseEnabled = true
    releaseBuildVariants.set(
        setOf(
            "advancedRelease",
            "proRelease",
            "freeRelease",
            "promoRelease",
        )
    )
    ignoredBuildTypes.set(
        setOf("debug")
    )
    ignoredFlavors.set(
        setOf(
            "free",
            "promo",
        )
    )
    failOnError = true
}

Примечание

Где buildTypes, flavor dimensions и buildVariants соответствуют настройкам вашего проекта.

В примере выше flowId, clientId, clientSecret и параметры прокси - демонстрационные. Используйте реальные значения.

Набор releaseBuildVariants обязательный к заполнению и не может быть пустым.

Синхронизируйте проект.

Конфигурация плагина

Доступные параметры

Параметр	Описание	Значение по умолчанию
`flowId: String?`	Идентификатор потока в МТС Аналитике, тот же, что и для СДК Аналитики. Необходимо указать, если включена автоматическая отправка маппинг файла	-
`clientId: String?`	Логин вашей учётной записи для аутентификации в сервисе. Необходимо указать, если включена автоматическая отправка маппинг файла	-
`clientSecret: String?`	Пароль вашей учётной записи для аутентификации в сервисе. Необходимо указать, если включена автоматическая отправка маппинг файла	-
`proxyHost: String?`, `proxyPort: Int?`	Параметры прокси-сервера, если доступ во внешний интернет закрыт настройками прокси	-
`proxyUser: String?`, `proxyPassword: String?`	Параметры учётной записи для отправки маппинг файла через прокси	-
`allowUploadMappingFiles: Boolean`	Запускает `gradle tasks` автоматической загрузки `mapping.zip` на сервис аналитики	`false`
`showUploadingProgress: Boolean`	Разрешает вывод прогресса загрузки файла в logcat Android Studio	`false`
`uploadTryCount: Int`	Количество попыток отправить mapping-file в случае возникновения ошибок сети. Минимум 1, максимум 3 попытки	`1`
`onlyReleaseEnabled: Boolean`	Запускает `gradle tasks` и записывает ID сборки только для вариантов, перечисленных в `releaseBuildVariants`	`true`
`allowDependenciesReport: Boolean`	Создаёт файл со списком сторонних зависимостей проекта во временной папке `app/build/*`. В настоящий момент фича отключена	`false`
`releaseBuildVariants: Set<String>`	Обязательное поле. Укажите варианты сборок, которые должны считаться релизными. Для них, маппинг файлы будут храниться максимально предусмотренное время	-
`ignoredBuildTypes: Set<String>`	Используйте, чтобы передавать типы сборки, для которых не будет создаваться ID сборки	`emptySet()`
`ignoredFlavors: Set<String>`	Используйте, чтобы передавать `build-flavor dimensions`, для которых не будет создаваться ID сборки	`emptySet()`
`ignoredVariants: Set<String>`	Используйте, чтобы передавать имена вариантов или готовых сочетаний `Flavors*BuildType`, для которых не будет создаваться ID сборки	`emptySet()`

Логирование

Чтобы включить логирование отладочной информации о работе плагина, добавьте в gradle.properties файл модуля :app свойство: ma_debug_logging_is_enabled=true.

Генерация файла

После подключения плагина и выполнения gradle tasks build* или assemble* для build-вариантов с включённой минификацией minifyEnabled true / isMinifyEnabled = true появится файл mapping.zip.

Где будет файл: в Application-модуле, к которому подключён плагин.

Пример

build/tmp/mtsa/mapping/variantName/mapping.zip

Плагин допишет в конец этого файла строку с ID сборки, например, ma_mfid=b556d760-2031-49be-a14e-945f6d25a36d.

События фатальных ошибок, отловленные SDK МТС Аналитики, будут отправляться в Аналитику и включать в себя stacktrace ошибки и такой же mfid. Так, сервис крашлитики будет понимать, ошибкам какой версии приложения соответствует загруженный mapping.zip.

Загрузка файла в Крашлитику

Автоматически

В конфигурации плагина включите автоматическую отправку маппинг-файлов allowUploadMappingFiles=true.
Настройте параметры учётной записи: flowId, clientId, clientSecret.
Параметры прокси и технической учётки для CI-CD (если необходимо): proxyHost, proxyPort, proxyUser, proxyPassword

После этого маппинг-файл будет отправляться автоматически во время сборки проекта.

Вручную

В конфигурации плагина выключите автоматическую отправку маппинг-файлов allowUploadMappingFiles=false (по умолчанию). Настраивать параметры учётной записи flowId, clientId, clientSecret не обязательно.
После завершения сборки .apk для релизных или других сборок возьмите полученный mapping.zip файл и вручную загрузите его в Крашлитику.

Смотреть данные

Статистика будет отображаться в отчёте «Крашлитика».

Требования​

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

Конфигурация плагина​

Доступные параметры​

Логирование​

Генерация файла​

Загрузка файла в Крашлитику​

Автоматически​

Вручную​

Смотреть данные​