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

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

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

Библиотек, которые интегрируются в приложения.
Приложений, которые содержат библиотеки.

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

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

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

Порядок действий для библиотек
Шаг 1. Добавить API

Добавьте в пакет публичного API интерфейс AnalyticsHostDelegate и класс MTSAnalytics.
Замените префикс MyProduct на название своего продукта для избежания конфликта имён.
Укажите ваш Flow ID в переменной shared.

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

Направьте на analytics.support@mts.ru бизнес-требование для получения технического задания на разметку.
Используйте методы делегата для отправки событий в Аналитику после инициализации делегата приложением.

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

Завершена интеграция с МТС Аналитикой.
Библиотека предоставила интерфейс AnalyticsHostDelegate.

Шаг 1. Создать класс

Создайте класс, реализующий интерфейс AnalyticsHostDelegate.
Используйте MTAnalytics для обработки событий, полученных от библиотеки.

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

Установите в hostAPI объект, реализующий интерфейс.
Добавьте названия нескольких SDK в extension для обработки событий от всех библиотек.

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

Храните объект AnalyticsManager на всем жизненном цикле приложения.
Используйте static-переменную для отправки событий в Аналитику с момента запуска приложения.

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

Библиотек, которые интегрируются в приложения.
Приложений, которые содержат библиотеки.

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

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

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

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

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

public protocol [MyProduct]AnalyticsHostDelegate: AnyObject {
    func track(flowId: String, eventName: String, data: [String: Any?]?) // Стандартные события
    func track(flowId: String, error: Error, errorMessage: String?, data: [String: Any?]?) // События об ошибках
    func webSessionQueryItem(flowId: String, url: String) -> URLQueryItem? // События кросс-платформенных сессий
}

public final class [MyProduct]MTSAnalytics {

    public weak var hostAPI: [MyProduct]AnalyticsHostDelegate?
    private let flowId: String

    private init(flowId: String) {
        self.flowId = flowId
    }

    public static let shared = [MyProduct]MTSAnalytics(flowId: "flowId")

    func track(eventName: String, parameters: [String : Any?]?) {
        hostAPI?.track(flowId: flowId, eventName: eventName, data: parameters)
    }

    func track(error: Error, errorMessage: String?, data: [String: Any?]?) {
        hostAPI?.track(flowId: flowId, error: error, errorMessage: errorMessage, data: data)
    }

    func webSessionQueryItem(url: String) -> URLQueryItem? {
        hostAPI?.webSessionQueryItem(flowId: flowId, url: url)
    }

}

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

protocol EcoSdk1AnalyticsHostDelegate

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

Укажите ваш Flow ID в переменной shared.

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

Важно

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

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

Начните отправлять данные событий разметки через методы делагата

[MyProduct]MTSAnalytics.shared.track(eventName, parameters)

[MyProduct]MTSAnalytics.shared.track(error, errorMessage, data)

[MyProduct]MTSAnalytics.shared.webSessionQueryItem(url)

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

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

Требования

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

Шаг 1. Создать класс

Создайте класс, который будет реализовывать интерфейс EcoSdk1AnalyticsHostDelegate. Например,

final class AnalyticsManager {
    init() { 
        EcoSDK1MTSAnalytics.shared.hostAPI = self
    }
}

extension AnalyticsManager: EcoSdk1AnalyticsHostDelegate {

    func track(flowId: String, eventName: String, data: [String : Any?]?) {
        MTAnalytics.getInstance(configuration: .init(flowId: flowId))
            .track(eventName: eventName, parameters: data)
    }

    func track(flowId: String, error: any Error, errorMessage: String?, data: [String : Any?]?) {
        MTAnalytics.getInstance(configuration: .init(flowId: flowId))
            .track(error: MTError(errorName: errorMessage ?? error.localizedDescription, parameters: data))
    }

    func webSessionQueryItem(flowId: String, url: String) -> URLQueryItem? {
        MTAnalytics.getInstance(configuration: .init(flowId: flowId))
            .webSessionQueryItem(url: url)
    }

}

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

Установите в hostAPI из библиотеки объект, который реализует интерфейс. Например, через init(). Это необходимо сделать для каждого SDK, если их несколько

init() { 
    EcoSDK1MTSAnalytics.shared.hostAPI = self
    EcoSDK2MTSAnalytics.shared.hostAPI = self
}

Семантика AnalyticsHostDelegate одинакова для всех SDK, поэтому при интеграции нескольких библиотек достаточно добавить их названия в extension. Например,

extension AnalyticsManager: EcoSdk1AnalyticsHostDelegate, EcoSdk2AnalyticsHostDelegate, EcoSdk3AnalyticsHostDelegate { 
}

Требования

Объект класса AnalyticsManager необходимо хранить на всем жизненном цикле приложения, чтобы SDK могли отправлять события в Аналитику с начала работы приложения.

Пример реализации:

final class AnalyticsManager {
    var mtsAnalytics: MTAnalyticsProvider?

    static let shared = AnalyticsManager()
    
    private init() { 
        EcoSDK1MTSAnalytics.shared.hostAPI = self
    }
    
    func setupTracker(flowId: String) {
        let configuration = MTAnalyticsConfiguration(flowId: flowId)
        mtsAnalytics = MTAnalytics.getInstance(configuration: configuration)
        mtsAnalytics?.logLevel = .verbose
    }

}

Если вы создаёте static-переменную этого класса, объект будет создаваться при запуске приложения. Это необходимо, чтобы приложение корректно передавало события из библиотеки c момента запуска. Также эту переменную можно использовать для аналитики внутри приложения, например

AnalyticsManager.shared.mtsAnalytics.track(eventName, data)

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

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

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

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

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

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

Шаг 1. Создать класс​

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

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