iOS SDK

Kixo iOS SDK поддържа Swift 5.9+ и iOS 16+ за аналитика, атрибуция, push известия, проследяване на жизнения цикъл и session replay. Replay използва настройки за заснемане на ниво проект и предпазливи стойности по подразбиране за по-тежките си потоци; не изисква отделен минимум за OS или модел устройство извън deployment target-а iOS 16 на пакета. SDK се разпространява чрез Swift Package Manager и с едно извикване на Kixo.configure автоматично проследява екрани, докосвания, сесии, сривове, push известия и събития от жизнения цикъл. Проследяването на мрежови заявки е по избор.

Инсталиране

Swift Package Manager

В Xcode отидете на File → Add Package Dependencies и въведете:

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

Ако управлявате зависимостите в Package.swift, използвайте бинарния release пакет и продукта:

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 — незабавни появявания на UIViewController в UIKit + навигация в 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 и стартиране на приложението

Персонализирани събития

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), за да бъдат отделени от вашите персонализирани атрибути и да се показват в колоните на профила в таблото. Използвайте типизираното изброяване 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 със стойност булева стойност, за да добавите към потребителя прост маркер да/не. Маркерът се запазва между сесиите и се използва за сегменти, имейл кампании и заявки в чата — без нищо допълнително освен извикването към 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 между стартиранията и автоматично се добавят към всяко изходящо събитие. В чата можете да казвате неща като "изпрати приветствен имейл до потребителите, при които subscribe е true" — Kixo ще изгради сегмента и ще подготви шаблона вместо вас. Изчистват се при Kixo.reset().

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

Запазените ключове за свойства са с префикс $, за да не се смесват с вашите персонализирани атрибути. Каталогът на Kixo включва 37 ключа в 3 универсални пакета (идентичност, геоданни, жизнен цикъл) и 5 B2B вертикални пакета (абонамент, електронна търговия, медии, маркетплейс, лоялност). Задайте само тези, които са приложими за продукта ви — таблото се адаптира и показва само пакетите, които попълвате.

Идентичност

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

Геоданни

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

Жизнен цикъл

Кога сме го видели.

Абонамент

Задайте, ако продуктът ви предлага планове.

Електронна търговия

Задайте, ако продавате продукти.

Медии

Задайте, ако публикувате съдържание.

Маркетплейс

Задайте, ако продуктът ви е двустранна платформа.

Лоялност

Задайте, ако имате програми за ангажираност и награди.

Суперсвойства

Ключ/стойност двойки за сесията, които автоматично се добавят към всяко изходящо събитие. За разлика от traits в identify, които описват идентичността, суперсвойствата описват контекста на сесията — активен A/B вариант, вариант на build, включени 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 успее да определи име на изгледа. За по-прецизен контрол или собствени имена използвайте модификатора за изглед .kixoScreen():

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

Възпроизвеждане на сесии

Replay възстановява какво реално е видял потребителят — SDK заснема екранни кадри на ниво пиксел, кодирани с HEIC, заедно със структурна снимка на йерархията на изгледите, а плеърът в таблото ги сглобява в възпроизвеждане с превъртане по времето до хронологията на събитията. Настройте replay за проекта в Табло → Настройки → Запис на сесии; SDK прочита тази политика автоматично и я опреснява, докато приложението работи.

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

От таблото се управляват дали replay е включен, маскирането, режимите на заснемане и дали native replay може да качва данни през мобилна мрежа. Ако качването през мобилна мрежа е изключено, кадрите пак могат да се записват в ограничен буфер на устройството; качването изчаква разрешена мрежа.

SDK събира данните, които са включени в проекта ви, както и събитията и свойствата, които приложението ви изпраща.

Маскиране и поверителност

Тъй като replay записва пиксели, редактирането се извършва на устройството преди да бъде кодиран който и да е кадър. Паролите и другите чувствителни полета се откриват и скриват автоматично, а текстът, уловен в структурната снимка, минава през филтър за PII. За да скриете нещо свое — личен разговор, баланс по сметка, екран с чернова — задайте kxRedact на съответния изглед. Kixo растеризира плътен правоъгълник върху границите на този изглед преди HEIC кодирането, така че тези пиксели никога не напускат устройството.

balanceLabel.kxRedact = true
cardNumberField.kxRedact = true

Push известия

SDK инсталира runtime proxy за AppDelegate върху Kixo.configure — silent pushes (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; преди да изпращате кампании, настройте Firebase service account на приложението в Kixo.

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

Изпращане и поведение офлайн

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

Диагностика

Снимка на състоянието само за четене. Полезна е в екрани за диагностика или smoke тестове — отговаря на въпроса „защо събитията ми не пристигат?“ без debugger.

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

Принудително изпращане (за тестове)

Синхронен overload, който блокира до timeout секунди, докато flush приключи. Предназначен е за XCTest fixtures — никога не го извиквайте от главната нишка.

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

Нулиране

Изчиства идентичността, суперсвойствата и запазената опашка. Извикайте при изход, за да не се приписват следващите събития на предишния потребител.

Kixo.reset()