Android SDK

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

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

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

Шаг 1. Подключение 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 (не рекомендуется).

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

В Application классе инициализируйте SDK с flowId (обязательное поле).
Если flowId не указан, возникает ошибка IllegalArgumentException.

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

Настройте параметры: логирование, сеть, отлов ошибок, производительность, завершение сессии, аккумуляция событий, поддержка слабых устройств, логирование, установки.
Конфигурацию можно обновить в рантайме, но flowId менять не рекомендуется.
networkTrafficEnabled управляет отправкой событий по типу сети.
crashReportingEnabled и nativeCrashReportingEnabled отвечают за отлов ошибок.
collectAppStartMetricsEnabled и collectUIMetricsEnabled измеряют производительность.
activeTimeout и backgroundTimeout устанавливают длительность сессии.
eventStorageLimit ограничивает количество событий в хранилище.
allowFallbackMode экономит ресурсы на слабых устройствах.

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

Создайте экземпляр события с обязательным полем eventName.
Используйте метод track(event) для отправки событий.
Поддерживается несколько способов передачи параметров.

Разрешения
Требуются разрешения: ACCESS_NETWORK_STATE, INTERNET, AD_ID.

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

Отслеживание геолокации: setLocation(latitude, longitude) или setLocation(location).
Установка UserId: глобальный или с событием.
Установка User-Agent: вручную через setUserAgent(userAgent).

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

Версия 2.7.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

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. Просмотр данных