Android SDK

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

Версия 2.8.0

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

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

Для корректной работы требуются Android, Kotlin, минимальный SDK 23, целевой и скомпилированный SDK 36, а также наличие ID потока (Flow ID). Если идентификатор отсутствует, его необходимо запросить по электронной почте.

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

В статье приведена пошаговая инструкция по подключению библиотеки, включающая настройку репозиториев в файлах settings.gradle и build.gradle, а также добавление зависимости. Доступны различные версии библиотеки для разных сервисов (Google, Huawei, комбинированные или без них). Рекомендуется использовать версию без сторонних сервисов только при необходимости сокращения зависимостей, так как это может снизить точность аналитики.

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

В тексте вы найдете руководство по инициализации библиотеки в классе Application. Обязательным параметром является flowId; его отсутствие приводит к возникновению ошибки.

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

SDK позволяет настраивать различные параметры работы приложения и сбора данных. Конфигурацию можно обновлять во время выполнения работы приложения без его перезапуска.

Основные настройки включают:

Управление отправкой событий в зависимости от типа сети.
Настройки отлова ошибок: крэши, фатальные ошибки нативного кода и мониторинг ANR.
Сбор метрик производительности: время отрисовки первого экрана и замедление кадров.
Параметры завершения сессий (активной и фоновой) с указанием допустимых значений времени.
Ограничение количества событий в хранилище, которое может заполняться быстрее при проблемах с сетью или высокой интенсивности событий.
Включение экономного режима для слабых устройств, где события хранятся в оперативной памяти.
Настройка уровня логирования и делегата логирования.
Подписка на данные об установке приложения.

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

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

Разрешения

Для передачи определенных данных требуются соответствующие разрешения Android:

ACCESS_NETWORK_STATE для определения наличия сети.
INTERNET для доступа в интернет.
AD_ID для получения AdvertisingId.

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

Библиотека предоставляет методы для расширения собираемых данных:

Отслеживание геолокации: данные о локации передаются вручную, так как SDK не собирает их автоматически.
Установка User ID: глобальный идентификатор пользователя связывает события с конкретным пользователем. Идентификатор сохраняется между перезапусками и может быть очищен.
Установка User-Agent: строка идентификации приложения в HTTP-запросах теперь устанавливается вручную и хранится только в оперативной памяти.

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

Статистика по переданным событиям доступна в отчетах МТС Аналитики и через 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. Просмотр данных