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

Tracehub SDK для iOS, tvOS и macOS отслеживает установки, сессии, события, доход и подписки, диплинки и согласия пользователя. Эта страница — путь от подключения фреймворка до первой отправленной сессии.

Требования

Компонент	Минимальная версия
iOS / tvOS	15.0
macOS	13.0
Swift	6.0
Xcode	16.0+

Установка

SDK поставляется архивом с готовым TracehubSdk.xcframework. XCFramework содержит срезы для iOS, iOS Simulator, tvOS, tvOS Simulator и macOS. Распакуйте архив и положите TracehubSdk.xcframework в папку проекта (например, Vendor/).

Swift Package Manager (binaryTarget)

В Package.swift подключите бинарную цель:

targets: [
    .target(
        name: "MyApp",
        dependencies: ["TracehubSdk"]
    ),
    .binaryTarget(
        name: "TracehubSdk",
        path: "Vendor/TracehubSdk.xcframework"
    ),
]

Xcode-проект

1. Перетащите TracehubSdk.xcframework в навигатор проекта Xcode (отметьте Copy items if needed).
2. В настройках таргета приложения, раздел Frameworks, Libraries, and Embedded Content, выберите для фреймворка Embed & Sign.

SDK полностью совместим с Objective-C — варианты импорта и сигнатуры всех методов см. в README репозитория SDK.

Разрешение в Info.plist

Если планируете запрашивать App Tracking Transparency (см. страницу iOS SDK: приватность и идентификаторы), добавьте описание в Info.plist:

<key>NSUserTrackingUsageDescription</key>
<string>Ваше объяснение причин отслеживания для пользователя</string>

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

Инициализируйте SDK как можно раньше — в init() у @main-структуры (SwiftUI) или в application(_:didFinishLaunchingWithOptions:) (UIKit). Токен приложения (appToken) — это SDK-токен платформы iOS: в кабинете Tracehub откройте Трекинг → Приложения → выберите приложение → вкладка SDK (там же — готовый фрагмент кода инициализации с подставленным токеном), см. страницу Быстрый старт.

import TracehubSdk

@main
struct MyApp: App {
    init() {
        let config = TracehubConfig(appToken: "ВАШ_APP_TOKEN", environment: .production)
        config.logLevel = .info
        Tracehub.initSdk(config: config)
    }

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

Для UIKit-приложений тот же код выполняется в AppDelegate.application(_:didFinishLaunchingWithOptions:).

Все настройки задаются через TracehubConfig до вызова Tracehub.initSdk(config:) — полный перечень полей см. на странице iOS SDK: справочник конфигурации.

Не храните appToken строкой в публичном коде

Токен приложения не является секретом уровня платёжного ключа, но в публичный репозиторий его класть не стоит. Загружайте его из Bundle, xcconfig или менеджера секретов.

Среды

Значение	Назначение
.production	Релизные сборки
.sandbox	Разработка и тестирование

Для разработки и отладки заведите в кабинете отдельное приложение — например «MyApp Test» — и укажите его SDK-токен в отладочных сборках. Так тестовые установки, события и доход не смешаются с боевыми цифрами.

Постбэки по тестовым событиям уходят партнёрам

Если к приложению, на котором вы тестируете, подключены рекламные кабинеты, установки и события из отладочных сборок будут отправлены им постбэками. Тестируйте на приложении без подключённых рекламных кабинетов.

Метка среды доступна в выгрузке: Экспорт → Pull API, отчёт «События».

Отслеживание сессий

Сессии отслеживаются автоматически: SDK подписывается на уведомления о переходе приложения на передний план и в фон и сам открывает и закрывает сессию. Новая сессия начинается, когда приложение выходит на передний план после более чем 30 минут отсутствия активности. Дополнительных вызовов из кода не требуется.

За результатом отправки можно следить через обратные вызовы:

config.sessionSuccessCallback = { session in
    print("Сессия отправлена — thid: \(session.thid ?? "-")")
}
config.sessionFailureCallback = { failure in
    print("Ошибка сессии — повтор: \(failure.willRetry)")
}

Размер приложения

Для iPhone линкуется срез ios-arm64 — 563 КБ до dead-code stripping. Приложение, использующее только базовый API (initSdk, trackEvent, getAttribution), получает прибавку к бинарнику примерно 300–450 КБ.

Опциональные поверхности добавляются, только если вы их вызываете:

Поверхность	Что включает	Вклад
WebBridge	обращение к TracehubWebBridge	~45 КБ
TLS-пиннинг	задан TracehubConfig.tlsConfig	~25 КБ
HMAC-подпись	задан TracehubConfig.hmacSigningConfig	~10 КБ
SKAdNetwork	ad network IDs в Info.plist	~5 КБ

Следующие шаги

• см. страницу iOS SDK: события и доход — отправка событий, покупки и подписки;
• см. страницу iOS SDK: диплинки и атрибуция — обработка ссылок и чтение атрибуции;
• см. страницу iOS SDK: приватность и идентификаторы — ATT, GDPR, состав собираемых данных;
• см. страницу iOS SDK: справочник конфигурации — все поля TracehubConfig.

---