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

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

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

Подходит для библиотек, встраиваемых в приложения, и приложений, содержащих библиотеки.
Избежание конфликтов версий: SDK встроен только в приложение, а не в библиотеку.

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

Шаг 1. Добавить API
- Создать интерфейс AnalyticsHostDelegate с методами для передачи событий.
- Заменить префикс MyProduct на название продукта, указать Flow ID в shared.
Шаг 2. Передавать события
- Отправить бизнес-требование на analytics.support@mts.ru для получения технического задания.
- Использовать методы делегата для отправки событий после инициализации делегата приложением.

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

Шаг 1. Создать класс
- Реализовать интерфейс AnalyticsHostDelegate, например, класс AnalyticsManager.
- Инициализировать hostAPI из библиотеки в конструкторе.
Шаг 2. Реализовать API библиотеки
- Установить объект, реализующий интерфейс, в hostAPI для каждой библиотеки.
- Добавить реализацию интерфейса для нескольких SDK в extension.
Шаг 3. Отправлять события
- Использовать AnalyticsManager для передачи событий в МТС Аналитику.
- Хранить объект AnalyticsManager на протяжении всего жизненного цикла приложения.

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

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

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

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

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

Библиотека предоставляет интерфейс 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. Отправлять события​