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

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

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

• Подходит для библиотек, интегрирующихся в приложения с МТС Аналитикой, и приложений, передающих данные в МТС Аналитику.
• Ранее SDK встраивался в библиотеку и приложение, что вызывало конфликты версий. Новый способ позволяет избежать этого.

Интерфейс AnalyticsHostDelegate

• Библиотека предоставляет интерфейс для передачи событий в приложение.
• Приложение реализует интерфейс, передаёт instance делегата и обрабатывает данные.

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

• Добавить API: Создать интерфейс с методами для отправки событий и ошибок.
• Добавить метод: Реализовать метод setAnalyticsHostDelegate для инициализации делегата.
• Передавать события: Отправить бизнес-требование для получения технического задания.

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

• Реализовать API библиотеки: Создать интерфейс EcoSdk1AnalyticsHostDelegate.
• Инициализировать делегат: Использовать метод setAnalyticsHostDelegate.
• Подготовить конфигурацию SDK: Настроить MtsAnalyticsConfig с flowId библиотеки.
• Отправлять события: Реализовать методы для передачи данных в МТС Аналитику.

Семантика AnalyticsHostDelegate
Одинакова для всех SDK. При интеграции нескольких библиотек можно унаследоваться от нескольких интерфейсов.

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

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, поэтому при интеграции нескольких библиотек можно унаследоваться от нескольких интерфейсов, а методы не изменяются.