Перейти к основному содержимому

Библиотека и Android-приложение

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

Интеграция библиотек и приложений с МТС Аналитикой
Для кого подходит способ интеграции

  • Библиотек, которые интегрируются в приложения с МТС Аналитикой.
  • Приложений, библиотекам которых необходимо передать данные в МТС Аналитику.

Проблема и решение
Ранее SDK Аналитики встраивался и в библиотеку, и в приложение, что могло вызывать конфликты версий. Новый способ позволяет избежать этого, встраивая SDK только в приложение.

Интерфейс AnalyticsHostDelegate
Библиотека предоставляет интерфейс AnalyticsHostDelegate, через который приложение передаёт данные событий.

Порядок действий для библиотек
Шаг 1. Добавить API
Создать интерфейс с методами для отправки событий и ошибок. Пример:

interface MyProductAnalyticsHostDelegate

Шаг 2. Добавить метод
Добавить метод для инициализации делегата:

fun setAnalyticsHostDelegate(delegate: EcoSdk1AnalyticsHostDelegate)

Шаг 3. Передавать события
Отправить бизнес-требование на analytics.support@mts.ru для получения технического задания. Использовать экосистемную разметку для корректной передачи событий.

Порядок действий для приложений
Шаг 1. Реализовать API библиотеки
Реализовать интерфейс EcoSdk1AnalyticsHostDelegate.
Шаг 2. Инициализировать делегат
Использовать метод setAnalyticsHostDelegate(this).
Шаг 3. Подготовить конфигурацию SDK
Создать конфигурацию MtsAnalyticsConfig с flowId библиотеки.
Шаг 4. Отправлять события
Передавать данные в МТС Аналитику через методы делегата.

Пример реализации
В статье приведена пошаговая инструкция по реализации EcoSystemSdkAnalyticsWrapper, которая обрабатывает события от нескольких библиотек.

Такой способ интеграции подходит для:

  1. Библиотек, которые интегрируются в приложения с МТС Аналитикой.
  2. Приложений, библиотекам которых необходимо передать свои данные в МТС Аналитику.

Если библиотека встраивается в приложение вне экосистемы МТС, интеграция с МТС Аналитикой проходит стандартным образом.

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

Ранее SDK Аналитики встраивался и в библиотеку, и в приложение. Из-за этого могли возникнуть конфликты версий библиотек и зависимостей. Описанный ниже способ позволяет этого избежать.

Библиотека предоставляет интерфейс AnalyticsHostDelegate, возможность установить его instance и передаёт данные событий разметки в delegate. Приложение реализует предложенный интерфейс, передаёт instance делагата в библиотеку и обрабатывает данные от делегата. Так, SDK МТС Аналитики будет встроен только в приложение.

Порядок действий для библиотек​

Шаг 1. Добавить API​

Добавьте в пакет публичного API интерфейс

interface MyProductAnalyticsHostDelegate {
    fun sendEvent(flowId: String, eventName: String, data: Map<String, Any?>?) // Стандартные события
    fun sendError(flowId: String, error: Throwable, errorMessage: String?, data: Map<String, Any?>?) // События ошибок
    suspend fun getHostSessionQueryAsync(url: String): String // События кросс-платформенных сессий
    fun getHostSessionQuery(url: String): String
}

Замените префикс MyProduct на название своего продукта. Например

interface EcoSdk1AnalyticsHostDelegate

Это позволит избежать конфликта имён классов в приложении при добавлении нескольких библиотек. Приложение сможет легко найти название библиотеки для дальнейшей интеграции.

Шаг 2. Добавить метод​

Добавьте в публичное API метод для инициализации делегата

fun setAnalyticsHostDelegate(delegate: EcoSdk1AnalyticsHostDelegate)

Приложение проинициализирует делегат на своей стороне.

Шаг 3. Передавать события​

Важно

Если вы планируете отслеживать определённые события, например, клики на конкретные кнопки, направьте на analytics.support@mts.ru бизнес-требование для получения технического задания на разметку.

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

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

Порядок действий для приложений​

Требования
  • Завершена интеграция с МТС Аналитикой
  • Библиотека предоставила интерфейс AnalyticsHostDelegate. Если библиотека добавила данный публичный интерфейс, он будет отображаться в её пакете

Шаг 1. Реализовать API библиотеки​

Реализуйте публичный интерфейс

interface EcoSdk1AnalyticsHostDelegate

Шаг 2. Инициализировать делегат​

Проинициализируйте делегат через публичный метод SDK. Например,

ecoSdk1Api.setAnalyticsHostDelegate(this)

Шаг 3. Подготовить конфигурацию SDK Аналитики​

Для каждой библиотеки подготовьте стандартную конфигурацию МТС Аналитики, используя flowId библиотеки. Например,

private fun defaultMTSAConfigFor(flowId: String): MtsAnalyticsConfig {
	return MtsAnalyticsConfig.Builder(flowId = flowId)
	    // LogLevel.ERROR, or LogLevel.VERBOSE for debug
	    .setLogLevel(LogLevel.OFF)
	    .build()
}

Шаг 4. Отправлять события​

Начните передавать в МТС Аналитику данные, полученные от делегата. Например,

class EcoSystemSdkAnalyticsWrapper(
    private val context: Context,
    private val ecoSdk1Api: EcoSdk1Api,
    private val ecoSdk2Api: EcoSdk2Api,
) : EcoSdk1AnalyticsHostDelegate,
    EcoSdk2AnalyticsHostDelegate {

    init {
        ecoSdk1Api.setAnalyticsHostDelegate(this)
        ecoSdk2Api.setAnalyticsHostDelegate(this)
    }

    override fun sendEvent(flowId: String, eventName: String, data: Map<String, Any?>?) {
        runCatching {
            MTSAnalytics.getInstance(context.applicationContext, defaultMTSAConfigFor(flowId))
                .track(eventName, data ?: emptyMap())
        }
    }

    override fun sendError(
        flowId: String,
        error: Throwable,
        errorMessage: String?,
        data: Map<String, Any?>?
    ) {
    }

    override suspend fun getHostSessionQueryAsync(url: String) = withContext(Dispatchers.IO) {
    }

    override fun getHostSessionQuery(url: String): String {
        return 
    }
	
    private fun defaultMTSAConfigFor(flowId: String): MtsAnalyticsConfig {
	return MtsAnalyticsConfig.Builder(flowId = flowId)
	    // LogLevel.ERROR, or LogLevel.VERBOSE for debug
	    .setLogLevel(LogLevel.OFF)
	    .build()
    }
}

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