iOS SDK

Kixo iOS SDK podporuje Swift 5.9+ a iOS 16+ pro analytiku, atribuci, push notifikace, sledování životního cyklu i přehrávání relací. Pro replay přebírá přepínače záznamu nastavené na úrovni projektu a u náročnějších částí pipeline používá opatrné výchozí nastavení; kromě deployment targetu balíčku pro iOS 16 nemá žádné další minimální požadavky na OS ani model zařízení. SDK se distribuuje přes Swift Package Manager a jediným voláním Kixo.configure automaticky sleduje obrazovky, klepnutí, relace, pády, push notifikace i události životního cyklu. Sledování síťových požadavků je volitelné.

Instalace

Swift Package Manager

V Xcode přejděte do File → Add Package Dependencies a zadejte:

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

Pokud spravujete závislosti v Package.swift, použijte binární release balíček a 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"),
        ]
    )
]

Nastavení

Inicializujte Kixo ve své SwiftUI struktuře App nebo 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 konfigurace

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é události

• screen_view — okamžitá zobrazení view controllerů v UIKit a navigace ve SwiftUI
• screen_visit — strukturovaná návštěva ukončená při navigaci nebo přechodu na pozadí; obsahuje dobu strávenou na obrazovce, počty interakcí, identitu obrazovky a metadata toku
• session_start / session_end
• tap — klepnutí na tlačítka a rozpoznaná gesta
• crash — zachycená diagnostika pádů a výjimek
• network — volitelné očištěné agregace požadavků a diagnostika tras
• push_received / push_open / push_dismissed / push_silent / push_action — celý životní cyklus push notifikací
• push_permission / push_token_invalidated
• lifecycle — přechody do popředí, na pozadí a při spuštění aplikace

Vlastní události

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

Typované pomocné funkce pro události

Pohodlná nadstavba nad Kixo.track pro události, které Kixo rozpoznává podle názvu (purchase, signup, subscribe_start, trial_start, cancel, upgrade, activation, share, invite). Už při kompilaci ověří tvar vlastností a drží názvy klíčů na jednom místě — backendový detektor standardních událostí je porovnává 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)

Identifikace uživatelů

Vyhrazené klíče standardních vlastností mají předponu $ (konvence Mixpanel), takže jsou oddělené od vašich vlastních traits a promítají se do profilových sloupců v dashboardu. Použijte typovaný enum StandardProperty nebo přímo řetězec s předponou $ — úplný seznam všech 37 klíčů najdete níže v Katalog standardní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 uživatele pro segmentaci

Pomocí setUserProperty s hodnotou boolean přidáte uživateli jednoduchý příznak ano/ne. Zůstane zachovaný napříč relacemi a můžete ho použít v segmentech, e-mailových kampaních i dotazech v Kixo Chat — bez dalšího nastavování, stačí volání 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 se ukládají do UserDefaults i mezi spuštěními a automaticky se připojují ke každé odchozí události. V chatu můžete říct třeba "odeslat uvítací e-mail uživatelům, kde subscribe je true" — Kixo za vás sestaví segment i návrh šablony. Mažou se při Kixo.reset().

Katalog standardních vlastností

Vyhrazené klíče vlastností mají prefix $, aby byly oddělené od vašich vlastních atributů. Katalog Kixo pokrývá 37 klíčů ve 3 univerzálních sadách (identita, geo, životní cyklus) a 5 oborových sadách pro B2B (předplatné, e-commerce, média, marketplace, věrnost). Nastavte jen ty, které dávají smysl pro váš produkt — dashboard se přizpůsobí a zobrazí jen sady, které skutečně používáte.

Identita

Vždy relevantní. Určuje sloupce v záhlaví profilu.

Geo

Geografický kontext.

Životní cyklus

Kdy jsme ho zaznamenali.

Předplatné

Nastavte, pokud má váš produkt tarify.

E-commerce

Nastavte, pokud prodáváte produkty.

Média

Nastavte, pokud publikujete obsah.

Marketplace

Nastavte, pokud provozujete dvoustrannou platformu.

Věrnost

Nastavte pro programy zapojení a odměn.

Super-properties

Páry klíč/hodnota pro relaci, které se automaticky připojují ke každé odchozí události. Na rozdíl od vlastností identify, které popisují identitu, super-properties popisují kontext relace — aktivní variantu A/B testu, variantu buildu nebo zapnuté feature flagy. Ukládají se do UserDefaults i mezi spuštěními a mažou se při reset(). Při kolizi mají vlastnosti události z properties v track vždy přednost.

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

Sledování obrazovek ve SwiftUI

Zobrazení obrazovek ve SwiftUI se sledují automaticky, pokud SDK dokáže určit název view. Pokud potřebujete přesnější řízení nebo vlastní názvy, použijte view modifier .kixoScreen():

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

Přehrání relace

Replay rekonstruuje to, co uživatel skutečně viděl — SDK zachycuje obrazové snímky obrazovky kódované v HEIC spolu se strukturálním snímkem hierarchie view a přehrávač v dashboardu je skládá do přehrávání s možností posunu v čase vedle časové osy událostí. Replay pro projekt nastavíte v Přehled → Nastavení → Přehrání relace; SDK tuto politiku načítá automaticky a za běhu aplikace ji průběžně obnovuje.

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

V analytickém dashboardu nastavujete, jestli je replay zapnutý, jak se maskuje obsah, jaké režimy snímání se použijí a zda může nativní replay odesílat data přes mobilní síť. Když je odesílání přes mobilní data vypnuté, snímky se mohou dál ukládat do omezeného bufferu v zařízení; odeslání počká na povolený typ sítě.

SDK zachytává data povolená v projektu i události a vlastnosti, které odesílá vaše aplikace.

Maskování a soukromí

Protože replay zachycuje pixely, redakce probíhá na zařízení ještě předtím, než, než se zakóduje jediný snímek. Hesla a další citlivá pole se automaticky rozpoznají a redigují a text zachycený ve strukturálním snímku prochází filtrem PII. Pokud chcete redigovat něco vlastního — soukromé vlákno zpráv, zůstatek na účtu nebo rozepsanou obrazovku — nastavte na daném view kxRedact. Kixo před kódováním do HEIC vyrastruje přes hranice tohoto view plný obdélník, takže jeho pixely zařízení nikdy neopustí.

balanceLabel.kxRedact = true
cardNumberField.kxRedact = true

Push notifikace

SDK za běhu nasadí proxy AppDelegate na Kixo.configure — tiché push notifikace (content-available: 1) i viditelné notifikace doručené na pozadí se tak zachytí automaticky. Do AppDelegate nemusíte přidávat žádný kód. Stávající implementace UNUserNotificationCenterDelegate se dál volají beze změny; Kixo je jen obalí.

Zaregistrujte token zařízení přes standardní didRegisterForRemoteNotificationsWithDeviceToken:

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

Pokud aplikace používá Firebase Messaging, předejte jeho registrační token přes provider: .firebase. Kixo si tohoto poskytovatele uloží a doručuje přes FCM HTTP v1; než začnete odesílat kampaně, nastavte v Kixo servisní účet Firebase pro danou aplikaci.

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

Odesílání a chování offline

SDK ukládá události do lokální fronty, odesílá je dávkově a dočasná selhání opakuje s postupně delší prodlevou. Pokud je sběr pozastavený v nastavení projektu, nové události se neodesílají, dokud sběr znovu nepovolíte.

Diagnostika

Snapshot stavu jen pro čtení. Hodí se na ladicí obrazovky nebo do smoke testů — bez debuggeru odpoví na otázku „proč mi neodcházejí události?“

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

Vynutit odeslání fronty (pro testy)

Synchronní varianta, která při dokončení flush zablokuje běh až na timeout sekund. Je určená pro fixtures v XCTest — z hlavního vlákna ji nikdy nevolejte.

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

Resetovat

Vymaže identitu, super-properties i uloženou frontu. Volejte při odhlášení, aby se další události nepřiřazovaly předchozímu uživateli.

Kixo.reset()