iOS SDK

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

Версия 6.6.0

Для передачи данных от приложения в МТС Аналитику необходимо настроить и установить SDK. Статья описывает пошаговый процесс установки для разработчиков.

Проверьте перед установкой В статье приведена пошаговая инструкция по установке SDK. Перед началом работы убедитесь, что устройство соответствует требованиям: iOS 15.0+, tvOS 15.0+ и наличие ID потока (Flow ID). Если идентификатор отсутствует, его можно запросить, отправив письмо на analytics.support@mts.ru.

Подключение SDK В тексте вы найдете руководство по добавлению библиотеки MTAnalytics в проект двумя способами: через CocoaPods или Swift Package Manager. Для CocoaPods необходимо добавить ссылки на репозитории в Podfile и выполнить установку через терминал. Для Swift Package Manager требуется добавить URL проекта в Xcode, выбрав между динамической или статической линковкой.

Инициализация SDK В статье приведена пошаговая инструкция по инициализации библиотеки. Основные шаги включают использование UIApplicationDelegate (который остается легальным способом, несмотря на ограничения в новых версиях Xcode), импорт библиотеки и вызов метода конфигурации в методе запуска приложения.

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

SwiftUI: Требуется создать класс AppDelegate, инициализировать SDK там и подключить его к главному классу приложения через адаптер @UIApplicationDelegateAdaptor. Также описано, как перехватывать deep links и universal links через колбэки .onOpenURL и .onContinueUserActivity.
UIKit: Инициализация происходит в AppDelegate, а обработка ссылок переносится в SceneDelegate с использованием методов scene(_:willConnectTo...), scene(_:continue...) и scene(_:openURLContexts...).

Конфигурация библиотеки В тексте вы найдете руководство по настройке параметров работы SDK. Инициализация конфигурации происходит через MTAnalyticsConfiguration с указанием Flow ID.

Описаны следующие параметры настройки:

Завершение сессии: Настраивается время автоматического завершения активной и фоновой сессий (activeTimeout и backgroundTimeout). Значения по умолчанию — 1800 секунд, минимальное — 900, максимальное — 86400. Сессия завершается только при полном закрытии приложения.
Аккумуляция событий: Настраивается лимит событий в хранилище (eventStorageLimit). По умолчанию и максимально допустимо 20 000 событий, минимально — 3 000. Новые события вытесняют старые.
Настройка роуминга: По умолчанию отправка событий в роуминге включена, но может быть отключена через параметр networkTraffic.

Отправка событий В статье приведена пошаговая инструкция по созданию и отправке событий. Для корректной передачи необходимо настроить пары ключ-значение. Обязательными полями являются eventType и eventName.

Описаны следующие аспекты отправки:

Создание экземпляра события MTAppEvent с указанием типа, имени, названия экрана и параметров.
Отправка события через общий метод MTAnalyticsApp.analytics?.track(event:).
Отправка в приоритетном режиме через метод trackExpedited. Это обеспечивает немедленную отправку отдельным запросом, минуя накопление батча. Если приоритетная отправка невозможна (из-за лимитов, недоступности сети или отключения трафика), событие передается в общий конвейер (fallback). Лимиты приоритетного режима: 50 событий на сессию и 300 в сутки на Flow ID.

Дополнительные методы библиотеки В тексте вы найдете руководство по использованию дополнительных методов для настройки контекста событий:

User ID: Установка глобального идентификатора пользователя через setUserId. Он автоматически прикрепляется к событиям. Для очистки используется передача nil. Если ID передан непосредственно в событии, он имеет приоритет над глобальным.
User-Agent: Ручная установка строки User-Agent для идентификации приложения в HTTP-запросах. Значение автоматически добавляется в заголовки. Для очистки используется передача nil.
Локация: Передача данных о геолокации через setLocation, так как SDK не собирает их автоматически.
Сведения об SDK: Получение текущей версии (sdkVersion) и номера сборки (sdkBuildNumber).

Просмотр данных Статистика по передаваемым событиям доступна в отчетах МТС Аналитики и через Data API.

Версия 6.6.0

Release notes

Чтобы данные передавались от приложения в МТС Аналитику, настройте и установите SDK (счётчик). В этой статье пошагово описан процесс установки для разработчиков.

Проверьте перед установкой

iOS 15.0+
tvOS 15.0+
наличие ID потока (Flow ID)

Заметка

Если вы не получили ID потока, отправьте письмо на analytics.support@mts.ru с темой «Получение Flow ID». Идентификатор нужен для отправки данных приложения в МТС Аналитику.

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

Варианты добавления библиотеки MTAnalytics в проект

CocoaPods
Swift Package Manager

Добавьте в Podfile

pod 'GRDB.swift', git: 'https://github.com/groue/GRDB.swift.git', tag: 'v6.29.3'
pod 'MTAnalytics'

Добавьте ссылку на библиотеку MTAnalytics в Podfile

source 'https://github.com/MTSWebServices/mts-analytics-ios-sdk'

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

Откройте Xcode project.
Выберите File — Add Packages. В поиск добавьте URL проекта и нажмите Add Package:

Dynamically Linked

https://github.com/MTSWebServices/mts-analytics-ios-sdk

Statically Linked

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

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

Основные варианты инициализации

Общая часть

Используйте UIApplicationDelegate.

Начиная с версии Xcode 27 часть колбэков жизненного цикла будет ограничена в работе, но в SDK они не используются. В остальном, делегат по-прежнему остаётся легальным способом инициализации.

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

import MTAnalytics

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

Уточнение для SwiftUI
Уточнение для UIKit

В .swift файле AppDelegate проинициализируйте SDK Аналитики:

import UIKit
import MTAnalytics

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

        return true
    }
}

Entry point

Не надо добавлять @UIApplicationMain, точка входа переносится в App класс.

В App подключите AppDelegate через адаптер:

import SwiftUI

@main
struct YourAppNameApp: App {

    // Подключаем AppDelegate через property wrapper
    @UIApplicationDelegateAdaptor(AppDelegate.self) var appDelegate

    var body: some Scene {
        WindowGroup {
            ContentView()
        }
    }
}

Для отлова и передачи deep links и universal links в SDK МТС Аналитики, в SwiftUI, точки перехвата ссылок перенесены в колбэки:

var body: some Scene {
    WindowGroup {
        ContentView()
            // 1. Обработка Диплинков (myapp://*)
            .onOpenURL { url in
                handleURL(url)
            }
            
            // 2. Обработка Универсальных ссылок (https://*)
            .onContinueUserActivity(NSUserActivityTypeBrowsingWeb) { userActivity in
                if let url = userActivity.webpageURL {
                    handleURL(url)
                }
            }
    }
}

Где в func handleURL(_ url: URL):

Task(priority: .userInitiated) {
    await MTAnalyticsApp.analytics?.tracker?.track(url: url, parameters: [:])
    let linkResult = try? await MTAnalyticsApp.linkResolver?.resolveLink(url: url)
}

Оставляем entry point и инициализацию SDK в AppDelegate:

import UIKit
import MTAnalytics

@UIApplicationMain
class AppDelegate: UIResponder, UIApplicationDelegate {
    func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]? = nil) -> Bool {
        let configuration = MTAnalyticsConfiguration(flowId: "your-flow-id")
        MTAnalyticsApp.configure(configuration)

        return true
    }
}

Отлов и передача deep links и universal links в SDK МТС Аналитики, для UIKit, переносится в SceneDelegate:

class SceneDelegate: UIResponder, UIWindowSceneDelegate {

    // Some inits

    private var tracker: MTTracker? { /* MTSA SDK tracker instance: MTAnalyticsApp.analytics?.tracker */ }
    private var linkResolver: MTLinkResolver? { /* MTSA SDK linkResolver instance: MTAnalyticsApp.linkResolver */ }

    func scene(_ scene: UIScene, willConnectTo session: UISceneSession, options connectionOptions: UIScene.ConnectionOptions) {
        let userActivity = connectionOptions.userActivities.first
        if userActivity?.activityType == NSUserActivityTypeBrowsingWeb {
            // Universal link
            guard let url = userActivity?.webpageURL else { return }
            Task(priority: .userInitiated) {
                await [tracker?.track(url: url, parameters: [:]), linkResolver?.resolveLink(url: url)]
            }
            
        } else {
            // Deeplink
            if let context = connectionOptions.urlContexts.first {
                Task(priority: .userInitiated) {
                    await [tracker?.track(url: context.url, parameters: [:]), linkResolver?.resolveLink(url: context.url)]
                }
            }
        }
    }

    // Universal link
    func scene(_ scene: UIScene, continue userActivity: NSUserActivity) {
        let url = userActivity.webpageURL
        if userActivity.activityType == NSUserActivityTypeBrowsingWeb, let url {
            Task(priority: .userInitiated) {
                await [tracker?.track(url: url, parameters: [:]), linkResolver?.resolveLink(url: url)]
            }
        }
    }

    // Deeplink
    func scene(_ scene: UIScene, openURLContexts URLContexts: Set<UIOpenURLContext>) {
        if let context = URLContexts.first {
            Task(priority: .userInitiated) {
                await [tracker?.track(url: context.url, parameters: [:]), linkResolver?.resolveLink(url: context.url)]
            }
        }
    }

    // ...
}

Подробнее про отслеживание Deeplink

Действия для начала работы с Link Manager

Шаг 3. Конфигурация библиотеки

Настройте работу SDK и параметры библиотеки. Инициализация конфигурации:

let configuration = MTAnalyticsConfiguration(flowId: "FLOW_ID")

Завершение сессии

Настройка времени автоматического завершения фоновой и активной сессии

configuration.activeTimeout = 1800

configuration.backgroundTimeout = 1800

Тип сессии	Описание
`ActiveTimeout`	Длительность сессии, если приложение будет открыто до таймаута
`BackgroundTimeout`	Длительность сессии, если активность в приложение остановилась, но оно будет открыто в фоновом режиме до таймаута

Возможные значения:

По умолчанию длительность сессии: 1800 сек.
Минимальное значение: 900 сек.
Максимальное значение: 86400 сек.

Важно

Сессия завершится только при окончательном закрытии приложения.

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

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

configuration.eventStorageLimit = 20000

Возможные значения:

По умолчанию количество событий: 20 000
Максимальное количество событий: 20 000
Минимальное количество событий: 3 000

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

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

configuration.networkTraffic = .on

Шаг 4. Отправка событий

Создайте экземпляр события и передайте его. Чтобы события отправлялись корректно, настройте пары ключ-значение параметров, которые планируете отслеживать.

Типы событий

Подробнее про типы событий и заполнение полей

Важно

Поля eventType и eventName — обязательные. Если их не заполнить, параметры событий передаваться не будут.

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

let event = MTAppEvent(
    eventType: .event,
    eventName: String,
    screenName: String?,
    parameters: [String: Any?]?
)

Заметка

В качестве ключей поля parameters в MTPerformanceEvent, MTScreen, MTError рекомендуем использовать MTAppEventDefaults.

Подробнее о ключах

2. Настроить отправку экземпляра события

Метод отправки общий для всех типов событий

MTAnalyticsApp.analytics?.track(event: event)

3. Событие может быть отправлено в "приоритетном режиме"

MTAnalyticsApp.analytics?.trackExpedited(eventName: String, parameters: [String: Any?]?)
// или
MTAnalyticsApp.analytics?.trackExpedited(event: MTAppEvent)

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

Событие отправляется немедленно отдельным запросом, без накопления батча. Игнорируется idle timeout, retry timeout. Одно событие - один сетевой запрос.
Если событие не может быть отправлено приоритетным способом, то оно сохраняется в общую таблицу событий и передаётся обычным конвейером отправки (fallback).

Лимиты и условия срабатывания fallback:

Превышение лимитов (50 на сессию, 300 в сутки на flowId)
При недоступности сети, bad response, трафике отключённом через конфиг аналитики MTAnalyticsConfiguration#networkTraffic=MTNetworkTraffic.off

Важно

Рациональное использование приоритетного режима разметки и отправки событий отдаётся на усмотрение продукта.

Дополнительные методы библиотеки

Установка User ID

Используйте глобальный идентификатор userId, чтобы связывать события с пользователем

MTAnalyticsApp.analytics?.setUserId("user_id")

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

Важно

Есть 2 способа передачи этого идентификатора пользователя. Если userId передаётся в событии MTAppEvent, то используется это значение. Если нет, применяется глобальный userId, установленный через setUserId.

Очистка userId

Для очистки userId вызовите:

MTAnalyticsApp.analytics?.setUserId(nil)

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

Установка User-Agent

Заметка

Раньше User-Agent собирался автоматически, теперь его нужно установить вручную.

User-Agent — это строка, которую приложение отправляет на сервер в HTTP-запросе для идентификации себя. Используйте, чтобы передавать информацию о типе, версии и других характеристиках приложения.

MTAnalyticsApp.analytics?.setUserAgent("your_user_agent")

После установки значение будет автоматически добавляться в заголовки всех последующих HTTP-запросов SDK.

Очистка User-Agent

Для очистки вызовите

MTAnalyticsApp.analytics?.setUserAgent(nil)

Новые HTTP-запросы будут отправляться без заголовка User-Agent.

Установка локации

Чтобы регион определялся точнее, передавайте данные о локации в опциональные публичные методы. SDK МТС Аналитики не собирает их автоматически

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

Сведения об SDK

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

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

MTAnalyticsApp.analytics?.sdkVersion

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

MTAnalyticsApp.analytics?.sdkBuildNumber

Шаг 5. Просмотр данных

Статистика по передаваемым событиям доступна в отчётах МТС Аналитики и через Data API.

Проверьте перед установкой​

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

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

Общая часть​

Шаг 3. Конфигурация библиотеки​

Завершение сессии​

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

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

Шаг 4. Отправка событий​

Типы событий​

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

2. Настроить отправку экземпляра события​

3. Событие может быть отправлено в "приоритетном режиме"​

Дополнительные методы библиотеки​

Установка User ID​

Установка User-Agent​

Установка локации​

Сведения об SDK​

Шаг 5. Просмотр данных​

Проверьте перед установкой

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

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

Общая часть

Шаг 3. Конфигурация библиотеки

Завершение сессии

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

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

Шаг 4. Отправка событий

Типы событий

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

2. Настроить отправку экземпляра события

3. Событие может быть отправлено в "приоритетном режиме"

Дополнительные методы библиотеки

Установка User ID

Установка User-Agent

Установка локации

Сведения об SDK

Шаг 5. Просмотр данных