Android SDK

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

Версия 2.8.0

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

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

Чтобы интеграция прошла успешно, убедитесь, что проект соответствует требованиям: Android, Kotlin, minSDK 23, targetSDK и compiledSDK равны 36. Также необходим ID потока (Flow ID). Если идентификатор отсутствует, направьте запрос на analytics.support@mts.ru с темой «Получение Flow ID», так как он критически важен для отправки данных.

Подключение SDK

Для подключения библиотеки добавьте репозиторий mts_analytics_sdk в settings.gradle или build.gradle проекта. В файл build.gradle модуля добавьте зависимость implementation "ru.mts.analytics:android-sdk-google-v2:$mts_analytics_version".

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

Google
Huawei
Google и Huawei
без Google и Huawei

Использование версии без сервисов Google и Huawei позволяет сократить зависимости, но SDK перестанет собирать основные идентификаторы, что может снизить точность аналитики.

Инициализация SDK

В классе Application выполните инициализацию библиотеки через MTSAnalytics.getInstance, передав контекст и конфигурацию. Обязательным параметром является flowId. Если этот параметр не указан, возникнет ошибка IllegalArgumentException.

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

В классе Application настройте параметры SDK через MtsAnalyticsConfig.Builder. Доступны следующие опции:

Обновление конфигурации: Параметры можно менять в рантайме без перезапуска приложения. Изменения применяются через getInstance или updateConfig. Менять Flow ID не рекомендуется, чтобы не нарушить передачу данных.
Сеть: Параметр networkTrafficEnabled управляет отправкой событий в зависимости от типа сети. По умолчанию включен.
Отлов ошибок: Можно настроить сбор крэшей (crashReportingEnabled, nativeCrashReportingEnabled) и мониторинг ANR (isAnrMonitoring, anrMonitoringTimeout). По умолчанию эти функции отключены.
Performance: Включите collectAppStartMetricsEnabled для замера времени отрисовки первого экрана и collectUIMetricsEnabled для отслеживания замедления кадров. По умолчанию отключено.
Завершение сессии: Настройте таймауты активной (activeTimeout) и фоновой (backgroundTimeout) сессий. Диапазон значений: от 900 до 86 400 секунд. Сессия завершается при полном закрытии приложения.
Аккумуляция событий: Параметр eventStorageLimit определяет максимальное количество событий в хранилище (от 3 000 до 20 000). При проблемах с сетью или высокой интенсивности событий хранилище заполняется быстрее.
Поддержка слабых девайсов: Режим allowFallbackMode хранит события только в оперативной памяти. В этом режиме неотправленные события удаляются при закрытии приложения, а при нехватке места (менее 100 МБ) включается оптимизация.
Логирование: Уровень логирования настраивается через LogLevel. Можно использовать собственную реализацию логера через LoggerDelegate.
Установки: Метод subscribeForInstallReferrer позволяет получать данные об установке приложения.

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

Отправка событий

Создайте экземпляр события и передайте его через метод track. Поле eventName является обязательным.

Метод track поддерживает различные варианты передачи параметров:

Объект события
Имя события
Имя события и пара ключ-значение
Имя события и массив пар
Имя события и карта параметров

Разрешения

Для корректной работы SDK требуются следующие разрешения:

ACCESS_NETWORK_STATE — для определения наличия сети.
INTERNET — для доступа к интернету.
com.google.android.gms.permission.AD_ID — для получения AdvertisingId.

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

Отслеживание геолокации: SDK не собирает геоданные автоматически. Используйте метод setLocation для передачи координат вручную.
Установка User ID: Метод setUserId позволяет связать события с пользователем. Идентификатор сохраняется между перезапусками. Если userId передан в конкретном событии, используется он; иначе применяется глобальный ID. Для очистки передайте null или пустую строку.
Установка User-Agent: Теперь требуется устанавливать User-Agent вручную через метод setUserAgent. Значение хранится в оперативной памяти и не сохраняется после перезапуска.

Просмотр данных

Статистика по событиям доступна в отчетах МТС Аналитики и через Data API.

Версия 2.8.0

Release notes

Инструкция для ИИ-агента

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

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

Android, Kotlin
minSDK = 23
targetSDK = 36
compiledSDK = 36
наличие 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

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).

Важно

в этом режиме все неотправленные события удаляются после закрытия приложения
при активации режима приложение контролирует свободное место. Если остаётся меньше 100 МБ, включается оптимизация для предотвращения сбоев при запуске

Логирование

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

`loggerDelegate: LoggerDelegate?`

Установки

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

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

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

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

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

Важно

Поле 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)

Другие варианты передачи параметров:

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

Чтобы получить 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, чтобы связывать события с пользователем.

Заметка

Есть 2 способа передачи этого идентификатора пользователя:

С событием: Если userId передаётся в AppEvent, то используется это значение
Глобально: Если userId НЕ передаётся в AppEvent, применяется глобальный 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 = "")

Установка User-Agent

Заметка

Раньше User-Agent (WebSettings.getDefaultUserAgent(context)) собирался автоматически, теперь его нужно установить вручную.

User-Agent — это строка, которую приложение отправляет на сервер в HTTP-запросе для идентификации себя. Используйте, чтобы передавать информацию о типе, версии и других характеристиках приложения. UserAgent хранится в оперативной памяти и не сохраняется между перезапусками приложения.

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

// Установить userAgent:

val userAgent = ru.mts.analytics.sdk2.publicapi.Helpers.getUserAgentOrNull(appContext)
mtsAnalytics.setUserAgent(userAgent = userAgent)

// Очистить userAgent:
mtsAnalytics.setUserAgent(userAgent = null)

Шаг 5. Просмотр данных

Статистика по передаваемым событиям доступна в отчётах МТС Аналитики и через Data API.

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

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

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

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

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

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

Сеть​

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

Perfomance​

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

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

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

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

Установки​

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

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

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

Разрешения​

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

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

Получение AdvertisingId​

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

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

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

Установка User-Agent​

Шаг 5. Просмотр данных​

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

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

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

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

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

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

Сеть

Отлов ошибок

Perfomance

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

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

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

Логирование

Установки

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

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

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

Разрешения

Данные о сети

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

Получение AdvertisingId

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

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

Установка User ID

Установка User-Agent

Шаг 5. Просмотр данных