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

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

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

Интеграция с MTS Аналитикой для библиотек и iOS-приложений

Способ интеграции

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

Проблема и решение

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

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

  • Добавить API

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

  • Передавать события

    • Отправить бизнес-требование на analytics.support@mts.ru для получения технического задания.
    • Использовать методы делегата для отправки событий: 
      [MyProduct]MTSAnalytics.shared.track(eventName, parameters)
      [MyProduct]MTSAnalytics.shared.track(error, errorMessage, data)
      [MyProduct]MTSAnalytics.shared.webSessionQueryItem(url)

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

  • Создать класс

    • Реализовать интерфейс AnalyticsHostDelegate в классе, например AnalyticsManager.
    • Пример кода: 
      final class AnalyticsManager {
          init() { 
              EcoSDK1MTSAnalytics.shared.hostAPI = self
          }
      }

  • Реализовать API библиотеки

    • Установить объект, реализующий интерфейс, в hostAPI библиотеки.
    • Для нескольких SDK добавить их названия в extension.
    • Пример: 
      extension AnalyticsManager: EcoSdk1AnalyticsHostDelegate, EcoSdk2AnalyticsHostDelegate { 
      }

  • Отправлять события

    • Использовать static-переменную класса для хранения объекта на весь жизненный цикл приложения.
    • Пример: 
      AnalyticsManager.shared.mtsAnalytics.track(eventName, data)

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

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

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

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

Ранее 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)
    }

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

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

  1. Укажите ваш 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. Отправлять события​

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