Android SDK

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

Проверьте перед установкой
Убедитесь, что ваш проект соответствует требованиям: Android, Kotlin, minSDK = 21, targetSDK = 35, compiledSDK = 35. Получите ID потока (Flow ID) через письмо на analytics.support@mts.ru.

Шаг 1. Подключение SDK
Добавьте репозиторий mts_analytics_sdk в settings.gradle или build.gradle. Установите зависимость implementation "ru.mts.analytics:android-sdk-google-v2:$mts_analytics_version" для модуля. Дополнительно доступны версии с поддержкой Google, Huawei или без них.

Шаг 2. Инициализация SDK
В классе Application инициализируйте SDK с указанием Flow ID. Без указания Flow ID будет вызвана ошибка IllegalArgumentException.

Шаг 3. Конфигурация библиотеки
Настройте параметры: включение/отключение сети, сбор ошибок, мониторинг производительности, таймауты сессий, лимит событий в хранилище, режим экономии памяти. В таблице указаны возможные значения таймаутов и лимитов.

Шаг 4. Отправка событий
Создайте экземпляр события с обязательным полем eventName и отправьте его через метод track(). Доступны разные варианты передачи параметров.

Разрешения
Добавьте разрешения для доступа к интернету, проверки сети и получения AdvertisingId (для Android 33+).

Дополнительные методы
Используйте setLocations() для передачи геолокации и setUserId() для установки идентификатора пользователя. UserId, указанный в событии, имеет приоритет над глобальным.

Версия 2.5.0

Release notes

Чтобы данные передавались от приложения в МТС Аналитику, настройте и установите SDK (счётчик). В этой статье пошагово описан процесс установки для разработчиков.

Проверьте перед установкой

Android, Kotlin
minSDK = 21
targetSDK = 35
compiledSDK = 35
наличие ID потока (Flow ID)

Заметка

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

Шаг 1. Подключение SDK

Установите ссылку на артефакты библиотеки. Для настройки параметров сборки в корневой папке проекта — settings.gradle добавьте

pluginManagement {
    repositories {
    }
}
dependencyResolutionManagement {
    repositories {
        maven {
            name "mts_analytics_sdk"
            url "https://packages.a.mts.ru/repository/maven-releases/"
        }
    }
}

Если не получается добавить библиотеку, используйте альтернативный скрипт. Добавьте его в build.gradle проекта

aallprojects {
    repositories {
        maven {
            name "mts_analytics_sdk"
            url "https://packages.a.mts.ru/repository/maven-releases/"
        }
	}
}

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

implementation "ru.mts.analytics:android-sdk-google-v2:$mts_analytics_version"

Дополнительные версии библиотеки

Если вам необходима версия сборки, где в зависимостях есть обе библиотеки (и Google, и Huawei), используйте вариант Google и Huawei.

Google
Huawei
Google и Huawei
без Google и Huawei

googleImplementation "ru.mts.analytics:android-sdk-google-v2:$mts_analytics_version"

huaweiImplementation "ru.mts.analytics:android-sdk-huawei-v2:$mts_analytics_version"

allservImplementation "ru.mts.analytics:android-sdk-allserv-v2:$mts_analytics_version"

noservImplementation "ru.mts.analytics:android-sdk-noserv-v2:$mts_analytics_version"

Важно

Вы можете использовать версию без Google и Huawei, если хотите сократить количество зависимостей. Мы не рекомендуем делать это, так как SDK не будет собирать основные идентификаторы, что может снизить точность и полезность аналитики.

Шаг 2. Инициализация SDK

Для инициализации библиотеки и начальной конфигурации добавьте в Application класс приложения

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

flowId — полученный идентификатор потока.

Заметка

Flow ID не может быть пустой строкой, если он не будет указан, возникнет ошибка

IllegalArgumentException("FlowId is not initialized...")

Шаг 3. Конфигурация библиотеки

В Application классе приложения проинициализируйте SDK и начальную конфигурацию

val cfgBuilder = ru.mts.analytics.sdk2.publicapi.config.MtsAnalyticsConfig
    .Builder(flowId = "aabb1111-2c2d-3e3f-4444-555566667777")
    .setLogLevel(ru.mts.analytics.sdk2.logger.LogLevel.ERROR)
    .setNetworkTrafficEnabled(true)
    .setCrashReportingEnabled(true)
    .setNativeCrashReportingEnabled(true)
    .setAnrMonitoringEnabled(true)
    .setAnrMonitoringTimeout(4)
    .setCollectAppStartMetricsEnabled(true)
    .setCollectUIMetricsEnabled(true)
    .setActiveTimeout(3_600)
    .setBackgroundTimeout(3_600)
    .setEventStorageLimit(10_000)
    .setAllowFallbackMode(true)
    .subscribeForInstallReferrer { installReferrer: Map<String, String> ->
        // Handle installReferrer
    }
val config = cfgBuilder.build()

Обновление конфигурации

Конфигурацию можно обновить в рантайме. Это полезно, если нужно изменить параметры без перезапуска приложения. Для этого измените конфигурацию и вызовите getInstance(context, config) или updateConfig(config)

val mtsAnalytics: MtsAnalyticsApi = MTSAnalytics.getInstance(
    context = this,
    config = cfgBuilder.setEventStorageLimit(10000)
        .build()
)

Важно

Не рекомендуем менять Flow ID. Это нарушит процесс передачи данных и приведёт к потере данных.

Сеть

networkTrafficEnabled позволяет управлять отправкой событий в Аналитику. Настройка полезна, если вы управляете трафиком в зависимости от типа сети (roaming mode). По умолчанию включена (true).

Отлов ошибок

crashReportingEnabled позволяет отлавливать крэши (фатальные ошибки), сохранять их в виде событий и отправлять в Аналитику. По умолчанию выключен (false).
nativeCrashReportingEnabled позволяет отлавливать фатальные ошибки в нативном коде. По умолчанию выключен (false).
isAnrMonitoring позволяет предиктивно логировать ошибки ANR. По умолчанию выключен (false).
anrMonitoringTimeout интервал в секундах, по истечении которого SDK логирует ANR. По умолчанию 5 секунд.

Perfomance

collectAppStartMetricsEnabled позволяет замерить время отрисовки первого экрана на основе AppCompatActivity. По умолчанию отключена (false)
collectUIMetricsEnabled, позволяет замерять замедление отрисовки кадров (frozen frames) на основе AppCompatActivity. По умолчанию отключена (false)

Завершение сессии

Настройте время автоматического завершения фоновой и активной сессии

Тип сессии	Описание
`activeTimeout: Int`	Длительность сессии, если приложение будет открыто до тайм-аута
`backgroundTimeout: Int`	Длительность сессии, если активность в приложение остановилась, но оно работает фоном до тайм-аута

Возможные значения:

По умолчанию длительность сессии: 1 800 сек.
Минимальное значение: 900 сек.
Максимальное значение: 86 400 сек.

Важно

Cессия завершится только при окончательном закрытии приложения.

Аккумуляция событий в хранилище

Настройте количество событий в хранилище для отправки. Новые события будут вытеснять поступившие ранее.

`eventStorageLimit: Int` 

Возможные значения:

По умолчанию количество событий: 6 000
Максимальное количество событий: 20 000
Минимальное количество событий: 3 000

Заметка

Хранилище заполнится быстрее, если:

есть проблемы с сетью
передача трафика отключена
поток событий интенсивный (500 - 1000 и больше в минуту)

Поддержка слабых девайсов

allowFallbackMode разрешает работать в режиме экономии дискового места девайса. Переключает режим работы с событиями: вместо хранения в Базе Данных, события создаются исключительно in-memory. По умолчанию отключена (false)

Важно

В режиме in-memory теряются неотправленные события после закрытия приложения.

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

Логирование

LogLevel устанавливает уровень логирования. По умолчанию оно выключено
LoggerDelegat — в Аналитике по умолчанию есть собственная реализация логера, но вы можете передать ваш вариант

`loggerDelegate: LoggerDelegate?`

Установки

Функция subscribeForInstallReferrer(installReferrerListener: (Map<String, String>) -> Unit) необходима для получения install_referrer (данные по установкам приложения). Подробнее

Шаг 4. Отправка событий

Для настройки обмена данными между устройством Android и МТС Аналитикой создайте экземпляр события и передайте его в Аналитику. Чтобы события отправлялись корректно, согласуйте пары ключ-значение параметров, которые планируется отслеживать.

Создать экземпляр события

Подробнее про типы событий и заполнение полей

Важно

Поле eventName — обязательное. Если его не заполнить, параметры событий передаваться не будут.

Отправить экземпляр события

Метод отправки событий общий для всех типов событий

val mtsAnalytics: MtsAnalyticsApi = MTSAnalytics.getInstance(
    context = this,
    config = cfgBuilder.build()
)
val event = ru.mts.analytics.sdk2.publicapi.event.Event.AppEvent(
	eventName = "vntAuthStart",
	customDimensions = mapOf(mapOf("key1" to "val1"))
)
mtsAnalytics.track(event)

Помимо отправки события Event есть другие варианты передачи параметров

val mtsAnalytics: MtsAnalyticsApi = MTSAnalytics.getInstance(
    context = this,
    config = cfgBuilder.build()
)
mtsAnalytics.track(*)

где .track(*) может быть

fun track(event: Event)
fun track(eventName: String)
fun track(eventName: String, key: String, value: Any? = "")
fun track(eventName: String, vararg pair: Pair<String, Any?>)
fun track(eventName: String, map: Map<String, Any?>)

Разрешения

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

Данные о сети

Для опредедления наличия сети необходимо разрешение

<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />

Доступ к интернету

Для отправки событий приложению необходимо разрешение на доступ к интернету

<uses-permission android:name="android.permission.INTERNET" />

Получение AdvertisingId

Если вы работаете с версией Android SDK 33 или выше, для получения AdvertisingId добавьте

<uses-permission android:name="com.google.android.gms.permission.AD_ID"/>

Дополнительные методы библиотеки

Отслеживание геолокации

SDK Аналитики больше не собирает данные о геолокации. Для улучшения определения региона девайса можно передавать данные о локации в опциональные публичные методы

val mtsAnalytics: MtsAnalyticsApi = MTSAnalytics.getInstance(
    context = this,
    config = cfgBuilder.build()
)
mtsAnalytics.setLocations(*)

.setLocations(*) может быть

fun setLocation(latitude: Double, longitude: Double)
fun setLocation(location: android.location.Location)

Установка User ID

Для обогащения аналитических событий и крашей данными пользователя рекомендуется использовать глобальный идентфикатор UserId.

Для передачи идентификатора используйте метод setUserId. Он сохраняется между перезапусками приложения и автоматически добавляется в экосистемный объект (поле UserID) для всех типов событий.

val mtsAnalytics: MtsAnalyticsApi = MTSAnalytics.getInstance(
    context = this,
    config = cfgBuilder.build()
)

// Установить userId
mtsAnalytics.setUserId(userId = "user-123")

// Очистить userId — передать null или пустую строку
mtsAnalytics.setUserId(userId = null)
mtsAnalytics.setUserId(userId = "")

Приоритет

Если userId передан напрямую в AppEvent, он имеет приоритет над глобальным значением, установленным через setUserId.

Проверьте перед установкой​

Шаг 1. Подключение SDK​

Дополнительные версии библиотеки​

Шаг 2. Инициализация SDK​

Шаг 3. Конфигурация библиотеки​

Обновление конфигурации​

Сеть​

Отлов ошибок​

Perfomance​

Завершение сессии​

Аккумуляция событий в хранилище​

Поддержка слабых девайсов​

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

Установки​

Шаг 4. Отправка событий​

Создать экземпляр события​

Отправить экземпляр события​

Разрешения​

Данные о сети​

Доступ к интернету​

Получение AdvertisingId​

Дополнительные методы библиотеки​

Отслеживание геолокации​

Установка User ID​

Проверьте перед установкой

Шаг 1. Подключение SDK

Дополнительные версии библиотеки

Шаг 2. Инициализация SDK

Шаг 3. Конфигурация библиотеки

Обновление конфигурации

Сеть

Отлов ошибок

Perfomance

Завершение сессии

Аккумуляция событий в хранилище

Поддержка слабых девайсов

Логирование

Установки

Шаг 4. Отправка событий

Создать экземпляр события

Отправить экземпляр события

Разрешения

Данные о сети

Доступ к интернету

Получение AdvertisingId

Дополнительные методы библиотеки

Отслеживание геолокации

Установка User ID