iOS SDK

Kixo iOS SDK аналитика, attribution, push, lifecycle tracking және session replay үшін Swift 5.9+ пен iOS 16+ нұсқаларын қолдайды. Replay жоба деңгейіндегі capture тетіктеріне бағынады және ресурсты көбірек қажет ететін ағындар үшін сақ әдепкі баптауларды қолданады; пакеттегі iOS 16 deployment target-тен бөлек қосымша OS не құрылғы үлгісі бойынша шек қоймайды. SDK Swift Package Manager арқылы таратылады және Kixo.configure бір ғана шақыруымен экрандарды, түртулерді, сессияларды, crash оқиғаларын, push хабарландыруларын және lifecycle оқиғаларын автоматты түрде тіркейді. Желі сұрауларын бақылау әдепкіде өшірулі.

Орнату

Swift Package Manager

Xcode-та File → Add Package Dependencies бөліміне өтіп, мынаны енгізіңіз:

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

Тәуелділіктерді Package.swift арқылы басқарсаңыз, binary release package пен product-ты қолданыңыз:

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 struct-ында немесе 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 — dwell, engagement counts, screen identity және flow metadata қамтитын, навигация немесе background күйіне ауысқанда жабылатын құрылымды visit
• session_start / session_end
• tap — батырманы түрту және gesture recognizer оқиғалары
• crash — тіркелген crash және exception диагностикасы
• network — қалауыңызша қосылатын тазартылған request агрегаттары мен route диагностикасы
• push_received / push_open / push_dismissed / push_silent / push_action — push-тың толық өмірлік циклі
• push_permission / push_token_invalidated
• lifecycle — foreground / background / app-launch ауысулары

Custom оқиғалар

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

Типтелген оқиға көмекшілері

Kixo атауы бойынша танитын оқиғалар үшін Kixo.track үстіндегі ыңғайлы қабат (purchase, signup, subscribe_start, trial_start, cancel, upgrade, activation, share, invite). Properties құрылымы compile-time кезінде тексеріледі, ал кілт атаулары бір жерден басқарылады — backend-тегі standard-event detector атауларды дәл сол күйінде салыстырады.

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)

Пайдаланушыларды анықтау

Резервтелген стандартты property кілттері $ префиксімен келеді (Mixpanel дәстүрі), сондықтан олар өзіңіздің custom traits-пен шатаспайды және дашбордтағы профиль бағандарына шығарылады. Ол үшін типтелген StandardProperty enum-ын да, $ префиксі бар жай string-ті де қолдануға болады — 37 кілттің толық тізімі төмендегі Стандартты property каталогы бөлімінде.

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 науқандарында және chat сұрауларында бірден қолданылады — 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",
])

Properties іске қосулар арасында UserDefaults ішінде сақталады және сыртқа жіберілетін әр оқиғаға автоматты түрде қосылады. Chat-та "subscribe мәні true болатын пайдаланушыларға welcome email жібер" сияқты жазыңыз — Kixo сіз үшін сегментті құрып, шаблон нобайын дайындайды. Kixo.reset() кезінде тазартылады.

Стандартты property каталогы

Резервтелген property кілттері $ префиксімен беріледі, сондықтан олар custom traits-пен бір атау кеңістігінде қақтығыспайды. Kixo каталогында 3 әмбебап pack (identity, geo, lifecycle) және 5 B2B салалық pack (subscription, e-commerce, media, marketplace, loyalty) бойынша 37 кілт бар. Өніміңізге сәйкес келетіндерін ғана орнатыңыз — дашборд соған бейімделіп, тек толтырылған pack-терді көрсетеді.

Идентификация

Әрдайым қажет. Профиль тақырыбындағы бағандарды орнатады.

Гео

Географиялық контекст.

Өмірлік цикл

Оларды қашан көрдік.

Жазылым

Өніміңізде тарифтер болса, орнатыңыз.

E-commerce

Өнім сатсаңыз, орнатыңыз.

Медиа

Контент жарияласаңыз, орнатыңыз.

Маркетплейс

Екіжақты платформа болсаңыз, орнатыңыз.

Адалдық

Белсенділік пен сыйақы бағдарламалары болса, орнатыңыз.

Super-properties

Сыртқа жіберілетін әр оқиғаға автоматты түрде қосылатын, сессияға тән key/value жұптары. Олар identify traits-тен өзгеше: traits identity-ді сипаттайды, ал super-properties сессия контекстін береді — белсенді A/B нұсқасы, build flavor, қосылған feature flag-тер. Іске қосулар арасында UserDefaults ішінде сақталады, reset() кезінде тазартылады. Қақтығыс болса, track ішіндегі оқиғаға тән properties әрқашан басым болады.

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 экрандарын трекингтеу

SDK view атауын анықтай алса, SwiftUI экран қаралымдары автоматты түрде тіркеледі. Нақтырақ басқару немесе өз атауыңызды беру үшін .kixoScreen() view modifier-ін пайдаланыңыз:

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

Сессияны қайта ойнату

Replay пайдаланушының экранда нақты не көргенін қайта құрастырады: SDK экран кадрларын (HEIC-пен кодталған) және view hierarchy-дің құрылымдық снапшотын жинайды, ал дашбордтағы ойнатқыш оларды оқиғалар хронологиясының жанында таймлайн бойынша жылжытып көруге болатын ойнатуға біріктіреді. Жоба үшін replay баптауларын Басқару тақтасы → Баптаулар → Сессияны қайта ойнату ішінде орнатыңыз; SDK бұл саясатты автоматты түрде оқып, қолданба жұмыс істеп тұрған кезде жаңартып отырады.

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

Replay-дің қосулы болуы, бүркемелеу, түсіру режимдері және native replay-дің ұялы желі арқылы жүктей алуы — мұның бәрі дашбордтан басқарылады. Ұялы желі арқылы жүктеу өшірулі болса, кадрлар құрылғыдағы көлемі шектеулі буферге жазыла береді; жүктеу рұқсат етілген желіге шыққанша күтіп тұрады.

SDK жобаңызда қосылған деректерді және қолданбаңыз жіберетін оқиғалар мен қасиеттерді жинайды.

Бүркемелеу және құпиялылық

Replay пиксельдерді жазатындықтан, бүркемелеу кез келген кадр дейін кодталмай тұрып, құрылғының өзінде орындалады. Құпиясөздер мен басқа да сезімтал өрістер автоматты түрде анықталып, бүркемеленеді, ал құрылымдық snapshot-қа түсетін мәтін PII сүзгісінен өтеді. Кез келген custom деректі — жеке хабарламалар тізбегін, шот қалдығын, толтырылмаған экранды — бүркемелеу үшін view-ға kxRedact орнатыңыз. Kixo HEIC кодтауға дейін сол view шекарасының үстіне тұтас тікбұрыш салады, сондықтан оның пиксельдері құрылғыдан мүлде шықпайды.

balanceLabel.kxRedact = true
cardNumberField.kxRedact = true

Push хабарландырулар

SDK Kixo.configure үстіне runtime кезінде AppDelegate proxy орнатады — silent pushes (content-available: 1) және фондық режимде жеткізілетін көрінетін push хабарландырулар автоматты түрде тіркеледі. AppDelegate ішінде ешқандай код қажет емес. Бар UNUserNotificationCenterDelegate implementations әдеттегідей орындала береді; 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 арқылы орындайды; campaign жібермес бұрын қолданбаның Firebase service account-ын Kixo ішінде баптап қойыңыз.

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

Жеткізу және офлайн режимдегі жұмыс

SDK оқиғаларды құрылғыда кезекке жинайды, оларды топтап жібереді және уақытша қателер болса, backoff-пен қайта жібереді. Егер жинау project settings арқылы тоқтатылса, collection қайта қосылғанша жаңа оқиғалар жіберілмейді.

Диагностика

Тек оқуға арналған күй снапшоты. Debug экрандарында немесе smoke test кезінде ыңғайлы — дебаггерсіз-ақ «оқиғаларым неге жіберілмей жатыр?» деген сұраққа жауап береді.

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

Мәжбүрлі flush (тесттер үшін)

flush аяқталғанша timeout секундқа дейін бұғаттайтын синхронды overload. XCTest fixture-леріне арналған — main thread-тен ешқашан шақырмаңыз.

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

Қалпына келтіру

Identity, super-properties және сақталған кезекті тазалаңыз. Келесі оқиғалар алдыңғы пайдаланушыға байланып қалмауы үшін, мұны logout кезінде шақырыңыз.

Kixo.reset()