iOS SDK

Kixo iOS SDK podporuje Swift 5.9+ a iOS 16+ pre analytiku, atribúciu, push notifikácie, sledovanie životného cyklu aj replay relácií. Replay sa riadi prepínačmi zachytávania na úrovni projektu a pri náročnejších častiach používa konzervatívne predvolené nastavenia; okrem cieľa nasadenia iOS 16 pre balík nemá žiadne ďalšie minimálne požiadavky na verziu OS ani model zariadenia. SDK sa distribuuje cez Swift Package Manager a jediným volaním Kixo.configure automaticky sleduje obrazovky, ťuknutia, relácie, pády, push notifikácie a udalosti životného cyklu. Sledovanie sieťových požiadaviek je voliteľné.

Inštalácia

Swift Package Manager

V Xcode prejdite na File → Add Package Dependencies a zadajte:

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

Ak spravujete závislosti v Package.swift, použite binárny release balík a produkt:

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"),
        ]
    )
]

Nastaviť

Inicializujte Kixo vo svojej SwiftUI štruktúre App alebo v AppDelegate:

import Kixo

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

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

Možnosti konfigurácie

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
    )
)

Automaticky sledované udalosti

• screen_view — okamžité zobrazenia radičov z UIKit + navigácia v SwiftUI
• screen_visit — štruktúrovaná návšteva uzavretá pri navigácii alebo prechode na pozadie s časom zotrvania, počtami interakcií, identitou obrazovky a metadátami toku
• session_start / session_end
• tap — ťuknutia na tlačidlá a rozpoznávače gest
• crash — zachytená diagnostika pádov a výnimiek
• network — voliteľné anonymizované agregácie požiadaviek a diagnostika trás
• push_received / push_open / push_dismissed / push_silent / push_action — celý životný cyklus push notifikácií
• push_permission / push_token_invalidated
• lifecycle — prechody do popredia, na pozadie a pri spustení aplikácie

Vlastné udalosti

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

Typované pomocné funkcie pre udalosti

Nadstavba nad Kixo.track pre udalosti, ktoré Kixo rozpoznáva podľa názvu (purchase, signup, subscribe_start, trial_start, cancel, upgrade, activation, share, invite). Validácia tvaru vlastností pri kompilácii a jeden zdroj pravdy pre názvy kľúčov — backendový detektor štandardných udalostí porovnáva názvy doslova.

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)

Identifikácia používateľov

Vyhradené štandardné kľúče vlastností majú prefix $ (konvencia Mixpanel), takže sa nebijú s vašimi vlastnými traits a zároveň sa premietnu do profilových stĺpcov v dashboarde. Použite typovaný enum StandardProperty alebo surový reťazec s prefixom $ — úplný zoznam 37 kľúčov nájdete nižšie v Katalóg štandardných vlastností.

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
])

Označte používateľa na segmentáciu

Pomocou setUserProperty s hodnotou boolean priradíte používateľovi jednoduchý príznak áno/nie. Príznak pretrváva medzi reláciami a môžete ho hneď použiť v segmentoch, e-mailových kampaniach aj dopytoch v chate — bez ďalšieho nastavovania mimo volania 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",
])

Vlastnosti sa ukladajú v UserDefaults aj medzi spusteniami a automaticky sa pripájajú ku každej odchádzajúcej udalosti. V chate môžete povedať napríklad "pošli uvítací e-mail používateľom, pre ktorých subscribe je true" — Kixo za vás vytvorí segment aj návrh šablóny. Mažú sa pri Kixo.reset().

Katalóg štandardných vlastností

Vyhradené kľúče vlastností majú prefix $, takže sú oddelené od vašich vlastných traits. Katalóg Kixo obsahuje 37 kľúčov v 3 univerzálnych balíkoch (identita, geo, životný cyklus) a 5 B2B vertikálnych balíkoch (predplatné, e-commerce, médiá, trhovisko, vernosť). Nastavte tie, ktoré sa hodia pre váš produkt — dashboard sa prispôsobí a zobrazí len balíky, ktoré vyplníte.

Identita

Vždy relevantné. Nastavuje stĺpce v hlavičke profilu.

Geo

Geografický kontext.

Životný cyklus

Kedy sme ho videli.

Predplatné

Nastavte, ak má váš produkt plány.

E-commerce

Nastavte, ak predávate produkty.

Médiá

Nastavte, ak publikujete obsah.

Trhovisko

Nastavte, ak je váš produkt obojstranná platforma.

Vernosť

Nastavte, ak používate vernostné alebo odmeňovacie programy.

Super-properties

Dvojice kľúč/hodnota na úrovni relácie, ktoré sa automaticky pripájajú ku každej odchádzajúcej udalosti. Na rozdiel od vlastností identify, ktoré opisujú identitu, super-properties opisujú kontext relácie — aktívny A/B variant, variant buildu či zapnuté feature flagy. Ukladajú sa v UserDefaults aj medzi spusteniami a mažú sa pri reset(). Pri kolízii majú vždy prednosť hodnoty properties v 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()

Sledovanie obrazoviek v SwiftUI

Zobrazenia obrazoviek v SwiftUI sa sledujú automaticky, keď SDK dokáže určiť názov view. Ak chcete jemnejšie riadenie alebo vlastné názvy, použite view modifier .kixoScreen():

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

Replay relácií

Replay rekonštruuje to, čo používateľ skutočne videl — SDK zachytáva obrazové snímky obrazovky zakódované v HEIC spolu so štruktúrnou snímkou hierarchie view a prehrávač v dashboarde ich spojí do záznamu, v ktorom sa dá posúvať, vedľa časovej osi udalostí. Replay pre projekt nastavíte v Prehľad → Nastavenia → Prehrávanie relácií; SDK si túto politiku načíta automaticky a počas behu aplikácie ju obnovuje.

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

V dashboarde nastavíte, či je replay zapnutý, aké maskovanie a režimy záznamu sa použijú a či natívny replay smie nahrávať dáta cez mobilnú sieť. Ak je nahrávanie cez mobilnú sieť vypnuté, snímky sa môžu ďalej ukladať do obmedzeného buffera v zariadení; odoslanie počká na povolený typ siete.

SDK zachytáva údaje, ktoré máte v projekte povolené, aj udalosti a vlastnosti, ktoré odosiela vaša aplikácia.

Maskovanie a súkromie

Keďže replay zachytáva pixely, redakcia prebieha priamo v zariadení pred, než sa zakóduje akýkoľvek snímok. Heslá a ďalšie citlivé polia sa automaticky rozpoznajú a začiernia a text zachytený do štruktúrnej snímky prechádza filtrom PII. Ak chcete začierniť čokoľvek vlastné — súkromné vlákno správ, zostatok na účte či rozpracovanú obrazovku — nastavte na view kxRedact. Kixo pred kódovaním do HEIC vyrastruje cez hranice daného view nepriehľadny obdĺžnik, takže jeho pixely nikdy neopustia zariadenie.

balanceLabel.kxRedact = true
cardNumberField.kxRedact = true

Push notifikácie

SDK na Kixo.configure za behu nainštaluje proxy pre AppDelegate — tiché push notifikácie (content-available: 1) aj viditeľné push notifikácie doručené na pozadí sa zachytávajú automaticky. Do AppDelegate nemusíte pridávať žiadny kód. Vaše existujúce implementácie UNUserNotificationCenterDelegate sa budú naďalej volať štandardne; Kixo ich len obalí.

Zaregistrujte token zariadenia cez štandardné didRegisterForRemoteNotificationsWithDeviceToken:

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

Ak aplikácia používa Firebase Messaging, odovzdajte jeho registračný token cez provider: .firebase. Kixo si uloží poskytovateľa a doručuje cez FCM HTTP v1; pred odosielaním kampaní najprv v Kixo nastavte servisný účet Firebase pre danú aplikáciu.

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

Doručovanie a správanie offline

SDK ukladá udalosti lokálne do frontu, odosiela ich v dávkach a pri dočasných zlyhaniach opakuje odoslanie s rastúcim odstupom. Ak je zber pozastavený v nastaveniach projektu, nové udalosti sa neodosielajú, kým zber znovu nepovolíte.

Diagnostika

Prehľad stavu iba na čítanie. Hodí sa na debug obrazovky alebo smoke testy — bez debuggera odpovie na otázku „prečo mi netečú udalosti?“.

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

Vynútiť odoslanie (pre testy)

Synchrónne preťaženie, ktoré pri dokončení flush zablokuje volanie až na timeout sekúnd. Je určené pre fixtures v XCTest — nikdy ho nevolajte z hlavného vlákna.

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

Resetovať

Vymaže identitu, super-properties aj perzistentný front. Volajte pri odhlásení, aby sa ďalšie udalosti nepripisovali predchádzajúcemu používateľovi.

Kixo.reset()