iOS SDK

Kixo iOS SDK підтримує Swift 5.9+ та iOS 16+ і надає аналітику, атрибуцію, push-сповіщення, відстеження життєвого циклу та відтворення сесій. Відтворення сесій керується перемикачами запису на рівні проєкту й за замовчуванням обережно налаштоване для ресурсомістких етапів обробки; окремих мінімальних вимог до OS чи моделі пристрою понад iOS 16 як deployment target пакета немає. SDK поширюється через Swift Package Manager і після одного виклику Kixo.configure автоматично відстежує екрани, натискання, сесії, збої, push-сповіщення та події життєвого циклу. Відстеження мережевих запитів вмикається окремо.

Встановлення

Swift Package Manager

У Xcode відкрийте File → Add Package Dependencies і введіть:

https://github.com/kixoio/kixo-ios-sdk

Якщо керуєте залежностями через Package.swift, використовуйте бінарний релізний пакет і продукт:

dependencies: [
    .package(
        url: "https://github.com/kixoio/kixo-ios-sdk",
        from: "1.0.21"
    ),
],
targets: [
    .target(
        name: "YourApp",
        dependencies: [
            .product(name: "Kixo", package: "kixo-ios-sdk"),
        ]
    )
]

Налаштувати

Ініціалізуйте Kixo у своїй структурі SwiftUI App або в AppDelegate:

import Kixo

@main
struct MyApp: App {
    init() {
        Kixo.configure(
            projectId: "YOUR_PROJECT_ID",
            apiKey: "YOUR_API_KEY"
        )
    }

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

Параметри конфігурації

Kixo.configure(
    projectId: "YOUR_PROJECT_ID",
    apiKey: "YOUR_API_KEY",
    options: ConfigurationOptions(
        autoTrackScreens:   true,
        autoTrackTaps:      true,
        autoTrackNetwork:   false,
        autoTrackCrashes:   true,
        autoTrackSessions:  true,
        autoTrackPush:      true,
        sessionTimeout:     30,
        flushInterval:      30,
        flushAt:            20,
        maxBufferSize:      200,
        // apiHost:    nil  → managed Kixo ingest host
        // debug:      nil  → true in DEBUG, false otherwise
        // environment: nil → production
    )
)

Автовідстежувані події

• screen_view — миттєві появи UIKit view-controller і навігація SwiftUI
• screen_visit — структурований візит, що завершується під час переходу або згортання застосунку, з тривалістю, лічильниками взаємодій, ідентифікатором екрана та метаданими потоку
• session_start / session_end
• tap — натискання кнопок і розпізнавачі жестів
• crash — зібрана діагностика збоїв і винятків
• network — необов’язкові очищені агрегати запитів і діагностика маршрутів
• push_received / push_open / push_dismissed / push_silent / push_action — повний життєвий цикл push-сповіщень
• push_permission / push_token_invalidated
• lifecycle — переходи foreground / background / app-launch

Користувацькі події

Kixo.track("purchase_completed", properties: [
    "product_id": "SKU-123",
    "amount": 49.99,
    "currency": "USD",
])

Типізовані помічники для подій

Зручна обгортка над Kixo.track для подій, які Kixo розпізнає за назвою (purchase, signup, subscribe_start, trial_start, cancel, upgrade, activation, share, invite). Дає перевірку структури властивостей під час компіляції та єдине джерело істини для назв ключів — стандартний детектор подій на бекенді звіряє їх дослівно.

Kixo.trackPurchase(
    amount: 49.99,
    currency: "USD",
    productId: "pro_yearly"
)

Kixo.trackSubscriptionStart(
    plan: "pro",
    amount: 9.99,
    currency: "USD",
    interval: .month
)

Kixo.trackSignup(method: "google")
Kixo.trackTrialStart(plan: "pro", days: 14)
Kixo.trackCancel(plan: "pro", reason: "too_expensive")
Kixo.trackUpgrade(fromPlan: "free", toPlan: "pro")
Kixo.trackActivation(event: "first_post_published")
Kixo.trackShare(channel: "twitter", contentId: "post_123")
Kixo.trackInvite(channel: "email", recipientCount: 5)

Ідентифікувати користувачів

Зарезервовані ключі стандартних властивостей мають префікс $ (за конвенцією Mixpanel), щоб не перетинатися з вашими власними атрибутами й потрапляти в стовпці профілю в дашборді. Використовуйте типізований enum StandardProperty або рядок із префіксом $ — повний список із 37 ключів див. в Каталог стандартних властивостей нижче.

Kixo.identify("user_123", traits: [
    "$email": "jane@example.com",       // identity
    "$name":  "Jane Doe",                // identity
    "$plan":  "pro",                     // subscription pack
    "$lifetime_orders": 12,              // e-commerce pack
    "signup_source": "twitter_ad"       // custom trait
])

Позначити користувача для сегментації

Використовуйте setUserProperty зі значенням булеве значення, щоб додати користувачеві просту ознаку «так/ні». Вона зберігається між сесіями й використовується в сегментах, email-кампаніях і запитах у чаті — достатньо лише виклику SDK.

// Tag a user as subscribed — segments + campaigns can target this
Kixo.setUserProperty("subscribe", value: true)

// VIP membership
Kixo.setUserProperty("vip", value: true)

// String + numeric values work too
Kixo.setUserProperty("plan_tier", value: "enterprise")
Kixo.setUserProperty("lifetime_orders", value: 42)

// Bulk-set
Kixo.setUserProperties([
    "subscribe": true,
    "plan_tier": "enterprise",
])

Властивості зберігаються в UserDefaults між запусками й автоматично додаються до кожної вихідної події. У чаті можна писати щось на кшталт "надішли вітальний email користувачам, у яких subscribe має значення true" — Kixo сам збере сегмент і підготує шаблон. Очищаються через Kixo.reset().

Каталог стандартних властивостей

Зарезервовані ключі властивостей мають префікс $, щоб не перетинатися з вашими власними атрибутами. У каталозі Kixo є 37 ключів у 3 універсальних наборах (ідентичність, геодані, життєвий цикл) і 5 галузевих наборах для B2B (підписка, e-commerce, медіа, маркетплейс, лояльність). Заповнюйте лише ті, що підходять вашому продукту, — дашборд сам підлаштується й покаже тільки використані набори.

Ідентифікація

Завжди актуально. Визначає стовпці в заголовку профілю.

Геодані

Географічний контекст.

Життєвий цикл

Коли ми бачили їх востаннє.

Підписка

Використовуйте, якщо у вашому продукті є тарифні плани.

Електронна комерція

Використовуйте, якщо ви продаєте товари.

Медіа

Використовуйте, якщо ви публікуєте контент.

Маркетплейс

Використовуйте, якщо у вас двостороння платформа.

Лояльність

Використовуйте для програм залучення та винагород.

Супервластивості

Пари ключ/значення на рівні сесії, які автоматично додаються до кожної вихідної події. На відміну від traits у identify, що описують identity, супервластивості описують контекст сесії — активний варіант A/B, тип збірки, увімкнені feature flags. Зберігаються в UserDefaults між запусками; очищаються через reset(). У разі конфлікту properties у track завжди мають пріоритет.

Kixo.setSuperProperty("build_flavor", value: "beta")
Kixo.setSuperProperties([
    "ab_variant": "B",
    "referrer_campaign": "autumn-launch",
])

// Sugar for A/B tracking — keys as 'experiment_<id>'.
Kixo.setExperimentVariant("checkout_v2", variant: "variant_a")

Kixo.unsetSuperProperty("build_flavor")
Kixo.clearSuperProperties()

Відстеження екранів у SwiftUI

Перегляди екранів у SwiftUI відстежуються автоматично, коли SDK може визначити назву view. Якщо потрібен точніший контроль або власні назви, використовуйте модифікатор view .kixoScreen():

struct HomeView: View {
    var body: some View {
        VStack { Text("Welcome") }
            .kixoScreen("HomeView")
    }
}

Відтворення сесій

Replay відтворює саме те, що бачив користувач: SDK зберігає піксельні кадри екрана в HEIC разом зі структурним знімком ієрархії view, а плеєр у дашборді збирає їх у відтворення з перемотуванням поруч із часовою шкалою подій. Налаштуйте replay для проєкту в Панель керування → Налаштування → Повтор сеансу; SDK автоматично підхоплює цю політику й оновлює її під час роботи застосунку.

Kixo.configure(
    projectId: "YOUR_PROJECT_ID",
    apiKey: "YOUR_API_KEY"
)

У дашборді задається, чи ввімкнено replay, маскування, режими захоплення та чи може native replay вивантажувати дані через мобільну мережу. Якщо вивантаження через мобільну мережу вимкнено, кадри все одно можуть потрапляти в обмежений локальний буфер на пристрої; вивантаження почнеться, щойно з’явиться дозволена мережа.

SDK збирає дані, увімкнені у вашому проєкті, а також події й властивості, які надсилає застосунок.

Маскування та приватність

Оскільки replay захоплює пікселі, приховування даних відбувається на пристрої до того, як буде закодовано бодай один кадр. Паролі та інші чутливі поля визначаються й маскуються автоматично, а текст, що потрапляє до структурного знімка, проходить через фільтр PII. Щоб приховати будь-що своє — приватну гілку повідомлень, баланс облікового запису чи екран чернетки, — задайте kxRedact для view. Kixo растеризує суцільний прямокутник поверх меж цього view перед кодуванням у HEIC, тож його пікселі ніколи не залишають пристрій.

balanceLabel.kxRedact = true
cardNumberField.kxRedact = true

Push-сповіщення

SDK встановлює проксі AppDelegate під час виконання на Kixo.configure: silent push (content-available: 1) і видимі push-сповіщення, доставлені у фоновому режимі, фіксуються автоматично. Додавати код у AppDelegate не потрібно. Наявні реалізації UNUserNotificationCenterDelegate і далі працюють як звично — Kixo лише обгортає їх.

Зареєструйте токен пристрою стандартним способом через didRegisterForRemoteNotificationsWithDeviceToken:

func application(
    _ application: UIApplication,
    didRegisterForRemoteNotificationsWithDeviceToken deviceToken: Data
) {
    let token = deviceToken.map { String(format: "%02x", $0) }.joined()
    Kixo.setPushToken(token)
}

Якщо застосунок використовує Firebase Messaging, передайте його реєстраційний токен через provider: .firebase. Kixo збереже цього провайдера й доставлятиме повідомлення через FCM HTTP v1; перед надсиланням кампаній налаштуйте в Kixo сервісний обліковий запис Firebase для цього застосунку.

func messaging(_ messaging: Messaging, didReceiveRegistrationToken token: String?) {
    guard let token else { return }
    Kixo.setPushToken(token, provider: .firebase)
}

Доставка подій і робота офлайн

SDK ставить події в локальну чергу, надсилає їх пакетами й повторює тимчасові збої з backoff. Якщо збір призупинено в налаштуваннях проєкту, нові події не надсилатимуться, доки його знову не ввімкнуть.

Діагностика

Знімок стану лише для читання. Корисний на екранах налагодження або в smoke-тестах — відповідає на запитання «чому події не надходять?» без дебагера.

let diag = Kixo.diagnostics()
print(diag.queue.bufferedEventCount)  // events waiting to flush
print(diag.paused)                     // collection paused state
print(diag.environment)                // configured environment
print(diag.apiHost)                    // configured ingest host

Примусово відправити все з черги (для тестів)

Синхронне перевантаження, яке блокує потік до timeout секунд, доки не завершиться flush. Призначене для фікстур XCTest — ніколи не викликайте його з головного потоку.

func testEventLanded() {
    Kixo.track("test_event")
    let landed = Kixo.flush(timeout: 5.0)
    XCTAssertTrue(landed)
}

Скинути

Очищає identity, супервластивості та збережену чергу. Викликайте під час виходу з облікового запису, щоб наступні події не зараховувалися попередньому користувачу.

Kixo.reset()