MTS Analytics iOS

Документация MTS Analytics SDK

Подключение SDK
Инициализация
Отправка события
Конфигурация
Сведения об SDK
ECommerce события
Отслеживание deeplink
Link Manager
Лимит символов события
RemoteConfig
Perfomance

Актуальная версия MTAnalytics - 5.1.4

Требования для установки SDK

iOS 13.0+
tvOS 13.0+
Необходим ID потока, который на данном этапе выдается по запросу.

Шаг 1. Подключение SDK

Swift Package Manager

Открыть Xcode project, выбрать вкладку File → Add Packages
В поле поиска добавить URL проекта и нажать Add Package

https://github.com/MobileTeleSystems/mts-analytics-swiftpm-ios-sdk/

Cocoapods

Чтобы добавить библиотеку MTAnalytics в проект, через CocoaPods добавьте в Podfile:

pod 'MTAnalytics',  '~> 5.1.4'

Устанавливаем ссылку на библиотеку MTAnalytics в Podfile:

source 'https://github.com/MobileTeleSystems/mts-analytics-podspecs'

Сохраните Podfile и введите pod install в Терминале для установки библиотеки.

Шаг 2. Инициализация SDK

Сделайте импорт библиотеки:

import MTAnalytics

Инициализируйте библиотеку в методе application(_:didFinishLaunchingWithOptions:) вашего UIApplicationDelegate:

func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey : Any]? = nil) -> Bool {
    // Создание конфига с уникальным flowid
    let configuration = MTAnalyticsConfiguration(flowId: "your-flow-id")

    // Активация конфига
    MTAnalyticsApp.configure(configuration)
}

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

Для настройки обмена данными между устройством iOS и МТС Аналитикой создайте экземпляр события и запустите его отправку.

Создать экземпляр события:

Можно использовать custom event, где можно задать .event, .screenView или свое собственное название типа ивента через .custom("any_name")

let event = MTCustomEvent(eventType: .event, eventName: "button_tap", screenName: "Login", parameters: ["test": "123"])

Либо использовать свой собственный шаблон используя MTEventRepresentable протокол.

Настроить отправку экземпляра события в МТС Аналитику:

MTAnalyticsApp.analytics?.track(event: event)

Так же можно отправлять event и его дополнительные атрибуты без использования шаблонов

MTAnalyticsApp.analytics?.track(eventName: "button_tap", parameters: ["test": "123"])

Создать экземпляр ошибок:

let error = MTError(errorName: "failed request", parameters: ["test": "123"])

Так же можно передать stacktrace symbols в stacktrace экземпляра ошибки в виде массива строк (На данный момент сборка ошибок не функционирует)

Кросс-платформенное отслеживание

Для авторизации сессии через webView используйте WebSSO state, который можно получить из WebSSO SDK.

MTAnalyticsApp.analytics?.sendAuthenticationEvent(ssoState: "...", redirectUrl: "https://mts.ru")

Для передачи значения вызовите метод и передайте ранее полученный ssoState в формате String. Для определения сессии юзера в случае перехода в webView или внешний браузер через приложение в котором активирован MTAnalytics, при формировании запроса для webView или браузер требуется добавить webSessionQueryItem в url запроса в виде URLQueryItem.

let queryItem = MTAnalyticsApp.analytics?.webSessionQueryItem(url: "https://mts.ru")

Передача данных о геолокации

MTAnalyticsApp.analytics?.setLocation(CLLocation(latitude: latitude, longitude: longitude))

Обновление конфигурации без повторной инициализации

MTAnalyticsApp.analytics?.update(with: configuration)

Конфигурация SDK

func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey : Any]? = nil) -> Bool {
    let configuration = MTAnalyticsConfiguration(flowId: "your-flow-id")

    // Кастомизация конфигурации аналитики, например расширение хранилища событий
    configuration.eventStorageLimit = 10000

    // Инициализация Аналитики
    MTAnalyticsApp.configure(configuration)
}

Сбор краш метрик

configuration.crashReportingEnabled = false

По умолчанию, сборка краш метрик включена.

Настройки сессии

Чтобы настроить время автоматического завершения фоновой (backgroundTimeout) и активной сессии (activeTimeout), добавьте:

configuration.activeTimeout = 1800
configuration.backgroundTimeout = 1800

По умолчанию для обоих режимов значение составляет 1800 секунд (30 минут). Минимальное допустимое значение - 900 (15 минут), максимальное - 86400 (24 часа).

Аккумуляция событий в хранилищ

configuration.eventStorageLimit = 20000

Определяет максимальное количество событий, которые будут храниться на девайсе до тех пора пока не будут отправлены. Поступающие новые события будут вытеснять наиболее старые, тем самым соблюдать ограничение в рамках установленного лимита. По умолчанию максимальное количество составляет 20000 событий и является максимальным допустимым значением. Минимальное количество событий составляет 3000.

Настройка роуминга

configuration.networkTraffic = .on

Дает возможность остановить отправку событий. По умолчанию отправка событий включена.

Сведения об SDK

Для получения информации о текущей версии MTAnalytics:

MTAnalyticsApp.analytics?.sdkVersion

Свойство sdkVersion предоставляет текущую версию SDK. Пример: "1.2.3"

MTAnalyticsApp.analytics?.sdkBuildNumber

Свойство sdkBuildNumber предоставляет текущий номер сборки версии SDK. Пример: "5"

Отправка ECommerce событий

МТС Аналитика предоставляет два вида шаблонов ECommerce событий: MTECommerceGA4 и MTECommerceUA. Для отправки ECommerce событий используется метод

MTAnalyticsApp.analytics?.track(event: event)

MTECommerceGA4Event

let event = MTECommerceGA4Event(
        eventName: MTECommerceGA4EventName,
        parameters: [String: Any?]?,
        transactionId: String?,
        affiliation: String?,
        value: String?,
        currency: String?,
        tax: String?,
        shipping: String?,
        shippingTier: String?,
        paymentType: String?,
        coupon: String?,
        itemListName: String?,
        itemListId: String?,
        items: [MTECommerceGA4EventItem]?,
        creativeName: String?,
        creativeSlot: String?,
        promotionId: String?,
        promotionName: String?
)

При выборе определенного кейса в MTECommerceGA4EventName в eventName, есть обязательные поля для корректной разметки.

add_payment_info

Пользователь выбрал способ оплаты. Обязательные поля: массив MTECommerceGA4EventItem.

add_shipping_info

Пользователь выбрал способ доставки. Обязательные поля: массив MTECommerceGA4EventItem.

add_to_cart

Пользователь добавляет товар в корзину из карточки товара или любых других товарных блоков. Обязательные поля: массив MTECommerceGA4EventItem.

add_to_wishlist

Пользователь добавляет товар в избранное. Обязательные поля: массив MTECommerceGA4EventItem.

begin_checkout

Пользователь переходит на страницу оформления заказа. Обязательные поля: массив MTECommerceGA4EventItem.

purchase

Пользователь совершил покупку. Данное событие должно срабатывать только один раз для оформленного заказа. Обязательные поля:

transactionId.
массив MTECommerceGA4EventItem.

refund

Пользователь возвращает покупку. Обязательные поля:

при полном возврате transactionId.
при частичном возврате массив MTECommerceGA4EventItem.

remove_from_cart

Пользователь удаляет товар из корзины, карточки товара. Обязательные поля: массив MTECommerceGA4EventItem.

select_item

Пользователь кликает по товарам в каталоге, результате поиска, товарных блоках и других списках. Обязательные поля: массив MTECommerceGA4EventItem.

select_promotion

При клике на рекламные акции. Обязательные поля: массив MTECommerceGA4EventItem.

view_cart

Пользователь посетил страницу корзины. Обязательные поля: массив MTECommerceGA4EventItem.

view_item

Пользователь просматривает карточку товара. Обязательные поля: массив MTECommerceGA4EventItem.

view_item_list

Пользователь просматривает список товаров. Обязательные поля: массив MTECommerceGA4EventItem.

view_promotion

При просмотре рекламных акций на странице. Обязательные поля: массив MTECommerceGA4EventItem.

MTECommerceGA4EventItem

Массив items представляет собой структуру MTECommerceGA4EventItem

let item = MTEcommerceGA4EventItem(
        itemId: String,
        itemName: String,
        itemListName: String?,
        itemListId: String?,
        index: String?,
        itemBrand: String?,
        itemCategory: String?,
        itemCategory2: String?,
        itemCategory3: String?,
        itemCategory4: String?,
        itemCategory5: String?,
        itemVariant: String?,
        affiliation: String?,
        discount: String?,
        coupon: String?,
        price: String?,
        currency: String?,
        quantity: String?,
        locationId: String?,
        creativeName: String?,
        creativeSlot: String?,
        promotionId: String?,
        promotionName: String?,
        parameters: [String: Any?]?
)

MTECommerceUAEvent

let event = MTEcommerceUAEvent(eventName: MTEcommerceUAEventName, ecommerce: MTECommerceUA))

let ecommerceUA = MTECommerceUA(
        purchase: MTECommerceUA.Purchase?,
        checkoutOption: MTECommerceUA.CheckoutOption?,
        add: MTECommerceUA.Add?,
        checkout: MTECommerceUA.Checkout?,
        refund: MTECommerceUA.Refund?,
        remove: MTECommerceUA.Remove?,
        click: MTECommerceUA.Click?,
        promoClick: MTECommerceUA.PromoClick?,
        detail: MTECommerceUA.Detail?,
        impressions: MTECommerceUA.Impressions?,
        promoView: MTECommerceUA.PromoView?
)

Внутри purchase, checkoutOption, add и т.д могут находится структуры ActionField и массив Product.

При выборе определенного кейса в MTECommerceUAEventName в eventName, есть обязательные поля для корректной разметки.

checkout_option

Пользователь выбрал способ оплаты или выбрал способ доставки. Обязательные поля:

ActionField внутри CheckoutOption непустой.

add

Пользователь добавляет товар в корзину из карточки товара или любых других товарных блоков. Обязательные поля:

Массив Product внутри Add непустой. В каждом Product поля name и id должны быть заполнены.

checkout

Пользователь переходит на страницу оформления заказа. Обязательные поля:

Массив Product внутри Checkout непустой. В каждом Product поля name и id должны быть заполнены.

purchase

Пользователь совершил покупку. Данное событие должно срабатывать только один раз для оформленного заказа. Обязательные поля:

ActionField внутри Purchase непустой. Поля id, revenue должны быть заполнены.
Массив Product внутри Purchase непустой. В каждом Product поля name и id должны быть заполнены.

refund

Пользователь возвращает покупку. Обязательные поля:

ActionField внутри Refund непустой. При полном возврате поле id должно быть заполнено, при частичном в Product поля id, quantity также обязательны к заполнению.

remove

Пользователь удаляет товар из корзины, карточки товара. Обязательные поля:

Массив Product внутри Remove непустой. В каждом Product поля name и id должны быть заполнены.

click

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

Массив Product внутри Click непустой. В каждом Product поля name и id должны быть заполнены.

promoClick

При клике на рекламные акции. Обязательные поля:

Массив Promotions внутри PromoClick непустой. В каждом Promotion поля name и id должны быть заполнены.

detail

Пользователь просматривает карточку товара. Обязательные поля:

Массив Product внутри Product непустой. В каждом Product поля name и id должны быть заполнены.

impressions

Пользователь просматривает список товаров. Обязательные поля:

Массив Product внутри Impressions непустой. В каждом Product поля name и id должны быть заполнены.

promoView

При просмотре рекламных акций на странице. Обязательные поля:

Массив Promotions внутри PromoView непустой. В каждом Promotion поля name и id должны быть заполнены.

Отслеживание Deep/Universal Links

UISceneDelegate

Чтобы отслеживать открытия приложения с помощью Universal link, в UISceneDelegate в метод scene:willConnectToSession:options: добавьте код:

func scene(_ scene: UIScene, willConnectTo session: UISceneSession, options connectionOptions: UIScene.ConnectionOptions) {
    let userActivity = connectionOptions.userActivities.first
    if userActivity?.activityType == NSUserActivityTypeBrowsingWeb {
        // Universal Link
        if let url = userActivity?.webpageURL {
            MTAnalyticsApp.analytics?.track(url: url, parameters: [:])
        }
    } else {
        // Deeplink
        if let context = connectionOptions.urlContexts.first {
            MTAnalyticsApp.analytics?.track(url: context.url, parameters: [:])
        }
    }
}

Чтобы отслеживать открытия приложения в запущенном приложении, используйте код:

func scene(_ scene: UIScene, continue userActivity: NSUserActivity) {
    let url = userActivity.webpageURL
    if userActivity.activityType == NSUserActivityTypeBrowsingWeb, let url {
        MTAnalyticsApp.analytics?.track(url: url, parameters: [:])
    }
}

func scene(_ scene: UIScene, openURLContexts URLContexts: Set<UIOpenURLContext>) {
    if let context = URLContexts.first {
        MTAnalyticsApp.analytics?.track(url: context.url, parameters: [:])
    }
}

UIApplicationDelegate

Чтобы отслеживать открытия приложения с помощью deeplink или обработку deeplink в запущенном приложении, используйте UIApplicationDelegate и добавьте следующие изменения:

func application(_ application: UIApplication, trackOpeningURL url: URL) -> Bool {
    MTAnalyticsApp.analytics?.track(url: context.url, parameters: [:])
    return true
}

func application(_ application: UIApplication, openURL url: URL, sourceApplication: String?, annotation: AnyObject) -> Bool {
    MTAnalyticsApp.analytics?.track(url: context.url, parameters: [:])
    return true
}

func application(_ application: UIApplication, continue userActivity: NSUserActivity, restorationHandler: @escaping ([UIUserActivityRestoring]?) -> Void) -> Bool {
    if userActivity.activityType == NSUserActivityTypeBrowsingWeb, let url = userActivity.webpageURL {
        MTAnalyticsApp.analytics?.track(url: context.url, parameters: [:])
    }
    return true
}

Использование Link Manager

Настройка приложения

В Xcode необходимо выполнить следующие действия:

Выбрать Target приложения и вкладку General.
В разделе Capabilities включить опцию Associated Domains.
В поле Domains добавьте новую строку, сгенерированную административной панелью Link Manager. Формат должен быть следующим:

applinks:*product*.url.mts.ru

В случае если вам необходимо протестировать под VPN, то вы можете использовать параметр mode:

applinks:*product*.url.mts.ru?mode=developer

Использование прямой Universal Link

Прямая Universal Link имеет следующий формат:

https://*product*.url.mts.ru/example

В зависимости от того, установлено и настроено ли приложение на устройстве будет:

Запуск приложения
Открытие AppStore на странице приложения

Получение параметров Universal Link

Описание API

В публичном интерфейсе SDK есть два метода для получения параметров:

Для вызова через Swift Concurrency:

public func resolveLink(url: URL) async throws -> MTLink

Для вызова через completion:

public func resolveLink(url: URL, completion: @escaping (Result<MTLink, Error>) -> Void)

Вернется структура MTLink:

public struct MTLink {

    /**
    Link (deeplink) with params for app.
     */
    public let location: String

    /**
     Params from Link Manager for link.
     */
    public let params: [String: Any?]
}

UISceneDelegate

Чтобы обработать universal link в SceneDelegate, в случае если приложение запускается по ссылке, используйте код:

func scene(_ scene: UIScene, willConnectTo session: UISceneSession, options connectionOptions: UIScene.ConnectionOptions) {
    let userActivity = connectionOptions.userActivities.first
    if userActivity?.activityType == NSUserActivityTypeBrowsingWeb {
        Task {
            let link = try? await MTAnalyticsApp.linkResolver?.resolveLink(url: url)
        }
    }
}

Для случая, если приложение уже было открыто на момент перехода по ссылке:

func scene(_ scene: UIScene, continue userActivity: NSUserActivity) {
    let url = userActivity.webpageURL
    if userActivity.activityType == NSUserActivityTypeBrowsingWeb, let url {
        Task {
            let link = try? await MTAnalyticsApp.linkResolver?.resolveLink(url: url)
        }
    }
}

UIApplicationDelegate

Чтобы обработать universal link в SceneDelegate, используйте следующий код:

func application(_ application: UIApplication, continue userActivity: NSUserActivity, restorationHandler: @escaping ([UIUserActivityRestoring]?) -> Void) -> Bool {
    MTAnalyticsApp.linkResolver?.resolveLink(url: url) { result in
        switch result {
            case .success(let link):
                ...
            case .failure(let error):
                ...
        }
    }
    return true
}

Лимит символов события

Для разных полей существует определенный лимит на количество символов. При привышении лимита поле будет обрезаться. Для всех событий:

eventName - 500.
screenName - 100.
parameters - первые 20 полей до 500, остальные до 100.

MTEcosystemEvent:

первые 20 полей до 500, остальные до 200.

Максимальное количество символов для MTECommerceGa4 и MTECommerceUA - 100.

RemoteConfig

MTRemoteConfig — это класс для управления удаленными настройками конфигурации в вашем приложении. Он позволяет задавать значения по умолчанию, получать обновления с сервера и активировать их для использования в приложении без необходимости выпуска новых версий. Кроме того, MTRemoteConfig поддерживает проведение AB-тестов, что позволяет тестировать различные сценарии и функции на разных группах пользователей.

Инициализация

Создайте экземпляр Remote Config

let remoteConfig = MTAnalyticsApp.remoteConfig

Установка значений по умолчанию

Задайте значения по умолчанию для параметров конфигурации. Это обеспечит работу приложения до получения remote config с сервера.

Из plist-файла:

remoteConfig.setDefaults(plistName: "DefaultConfig")

Из словаря:

remoteConfig.setDefaults(dict: [
    "welcome_message": "Добро пожаловать!",
    "new_feature_flag": false,
    "max_items": 10
])

Настройка параметров запросов

minFetchInterval

Минимальный интервал (в секундах) между последовательными запросами к серверу. Используйте для предотвращения частых запросов. Значение по умолчанию: 300

remoteConfig.minFetchInterval = 600

fetchTimeout

Максимальное время ожидания ответа от сервера (в секундах). Значение по умолчанию: 30

remoteConfig.fetchTimeout = 15

Получение и активация значений с сервера

Чтобы получить обновленные значения с сервера, вызовите метод fetchRemoteConfigValues. После успешного получения активируйте их с помощью метода activate().

Асинхронное получение:

Task {
    let status = await remoteConfig.fetchRemoteConfigValues()
    if status == .success {
        remoteConfig.activate()
    }
}

С использованием completion handler:

remoteConfig.fetchRemoteConfigValues { status in
    if status == .success {
        remoteConfig.activate()
    }
}

Асинхронное получение и активация:

Task {
    do {
        let status = try await remoteConfig.fetchRemoteConfigValuesAndActivate()
        if status == .success {
            print("Конфигурация успешно обновлена и активирована")
        }
    } catch {
        print("Ошибка при получении и активации: \(error)")
    }
}

Получение значений после активации

После успешной активации полученные значения будут доступны через метод configValue(_:). Этот метод возвращает объект, реализующий протокол MTRemoteConfigValue, который позволяет получить значение в различных форматах.

if let welcomeMessage = remoteConfig.configValue("welcome_message")?.stringValue {
    print("Сообщение приветствия: \(welcomeMessage)")
}

Получение значений по умолчанию

Если вам нужно получить значение по умолчанию, используйте метод defaultValue(_:):

if let defaultValue = remoteConfig.defaultValue("welcome_message")?.stringValue {
    print("Значение по умолчанию для welcome_message: \(defaultValue)")
}

Perfomance

MTPerformance — это инструмент для:

Замера скорости работы участков кода с помощью MTTracer с последующей отправкой события в центр аналитики.
Трекинг URL запросов из приложения с возможностью фильтрации трафика и последующей отправкой события с параметрами запроса в центр аналитики.
Замера скорости открытия приложения от нажатия на иконку до первого вызвова viewDidAppear.

Инициализация

Создайте экземпляр

let performance = MTAnalyticsApp.performance

Для начала трекинга запросов и скорости открытия приложения необходимо до инициализации сетевого слоя в приложении проинициализировать MTAnalytics:

func application(
    _ application: UIApplication,
    willFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]? = nil
) -> Bool {
    let configuration = MTAnalyticsConfiguration(flowId: "your-flow-id")
    configuration.appStartMetricsCollectingEnabled = true
    configuration.networkTrackingEnabled = true
    MTAnalyticsApp.configure(configuration)
}

Трекинг URL-запросов

Для фильтрации трафика необходимо вызвать setExcludedUrls:

let filteredRequests: [String] = ["https://example.com"]
performance?.setExcludedUrls(filteredRequests)

Tracer

MTTracer - инструмент, позволяющий произвести замеры выполения кода в вашем приложении.

При инициализации необходимо указать название замера:

let tracer = performance.newTrace("customTrace")

Для запуска и остановки замера используйте функции start() и stop():

tracer.start()
// some code running
tracer.stop()

После остановки замера событие с параметрами замера и названием автоматически отправится в систему аналитики, но если вам необходимо получить данные замера, то можете воспользоваться параметрами name и lastMeasure:

public protocol MTTracer {
    /*
     Name of the tracer that was passed through the init
     */
    var name: String { get }

    /*
     Last measure between calls start and stop functions
     */
    var lastMeasure: Double? { get }
    ...
}

Name		Name	Last commit message	Last commit date
MTAnalytics		MTAnalytics
MTMetrics		MTMetrics
MTSAnalytics		MTSAnalytics
CHANGELOG.md		CHANGELOG.md
LICENSE		LICENSE
README.md		README.md

Latest commit

History

Folders and files

Repository files navigation

MTS Analytics iOS

Актуальная версия MTAnalytics - 5.1.4

Требования для установки SDK

Swift Package Manager

Cocoapods

Создать экземпляр события:

Настроить отправку экземпляра события в МТС Аналитику:

Так же можно отправлять event и его дополнительные атрибуты без использования шаблонов

Создать экземпляр ошибок:

Кросс-платформенное отслеживание

Передача данных о геолокации

Обновление конфигурации без повторной инициализации

Сбор краш метрик

Настройки сессии

Аккумуляция событий в хранилищ

Настройка роуминга

MTECommerceGA4Event

add_payment_info

add_shipping_info

add_to_cart

add_to_wishlist

begin_checkout

purchase

refund

remove_from_cart

select_item

select_promotion

view_cart

view_item

view_item_list

view_promotion

MTECommerceGA4EventItem

MTECommerceUAEvent

checkout_option

add

checkout

purchase

refund

remove

click

promoClick

detail

impressions

promoView

UISceneDelegate

UIApplicationDelegate

Настройка приложения

В Xcode необходимо выполнить следующие действия:

Использование прямой Universal Link

Получение параметров Universal Link

Описание API

UISceneDelegate

UIApplicationDelegate

Инициализация

Установка значений по умолчанию

Из plist-файла:

Из словаря:

Настройка параметров запросов

minFetchInterval

fetchTimeout

Получение и активация значений с сервера

Асинхронное получение:

С использованием completion handler:

Асинхронное получение и активация:

Получение значений после активации

Получение значений по умолчанию

Инициализация

Трекинг URL-запросов

Tracer

About

Resources

Stars

Watchers

Forks

Releases

Packages