iOS SDK

A Kixo iOS SDK Swift 5.9+ és iOS 16+ mellett támogatja az analitikát, az attribúciót, a push értesítéseket, az életciklus követését és a session replayt. A replay a projekt szintjén beállított rögzítési kapcsolókat használja, és az erőforrás-igényesebb feldolgozási útvonalaknál visszafogott alapértékekkel működik; a csomag iOS 16-os telepítési célján felül nincs külön OS- vagy eszközmodell-követelménye. A terjesztés Swift Package Manageren keresztül történik, és az SDK egyetlen Kixo.configure hívással automatikusan követi a képernyőket, koppintásokat, munkameneteket, összeomlásokat, push értesítéseket és életciklus-eseményeket. A hálózati kérések követése külön bekapcsolható.

Telepítés

Swift Package Manager

Az Xcode-ban nyisd meg ezt: File → Add Package Dependencies, majd írd be:

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

Ha a függőségeket Package.swift alatt kezeled, ezt a bináris kiadási csomagot és productot használd:

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

Beállítás

Inicializáld a Kixo-t a SwiftUI App structban vagy itt: AppDelegate:

import Kixo

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

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

Konfigurációs lehetőségek

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

Automatikusan követett események

• screen_view — azonnali UIKit view controller-megjelenések és SwiftUI navigáció
• screen_visit — strukturált látogatás, amely navigációkor vagy háttérbe kerüléskor zárul le, és tartalmazza az oldalon töltött időt, az aktivitási számlálókat, a képernyő azonosítóját és a folyamat metaadatait
• session_start / session_end
• tap — gombérintések és gesztusfelismerők
• crash — rögzített összeomlás- és kivételdiagnosztika
• network — opcionális, szűrt kérésösszesítések és útvonal-diagnosztika
• push_received / push_open / push_dismissed / push_silent / push_action — a push teljes életciklusa
• push_permission / push_token_invalidated
• lifecycle — előtér / háttér / alkalmazásindítás közötti átmenetek

Egyedi események

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

Tipizált eseménysegédek

Kényelmi réteg a(z) Kixo.track fölött azokhoz az eseményekhez, amelyeket a Kixo név alapján felismer (purchase, signup, subscribe_start, trial_start, cancel, upgrade, activation, share, invite). Fordítási időben ellenőrzi a propertyk szerkezetét, és egyetlen forrást ad a kulcsnevekhez — a backend standardesemény-felismerője szó szerinti egyezést keres.

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)

Felhasználók azonosítása

A fenntartott standard propertykulcsok $ előtagot kapnak (Mixpanel-konvenció), így elkülönülnek a saját egyedi traitjeidtől, és megjelennek a dashboard profiloszlopaiban. Használd a tipizált StandardProperty enumot vagy a nyers, $ előtagú karakterláncot — a teljes, 37 elemes listát lásd lejjebb: Standard propertykatalógus.

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

Felhasználó megjelölése szegmentáláshoz

A(z) setUserProperty hívást logikai érték értékkel használd, ha egy egyszerű igen/nem jelölést szeretnél a felhasználóhoz adni. A jelölés munkameneteken át megmarad, és használható szegmensekhez, e-mail-kampányokhoz és chatlekérdezésekhez — az SDK-híváson kívül nincs szükség további beállításra.

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

A propertyk a(z) UserDefaults tárolóban indítások között is megmaradnak, és automatikusan rákerülnek minden kimenő eseményre. A chatben mondhatsz például ilyet: "küldj üdvözlő e-mailt azoknak a felhasználóknak, akiknél a subscribe értéke true" — a Kixo elkészíti hozzá a szegmenst és a sablonvázlatot. A(z) Kixo.reset() törli őket.

Standard propertykatalógus

A fenntartott propertykulcsok $ előtagot kapnak, így elkülönülnek az egyedi traitjeidtől. A Kixo katalógusa 37 kulcsot tartalmaz: 3 univerzális csomagban (identity, geo, lifecycle) és 5 B2B vertikális csomagban (subscription, e-commerce, media, marketplace, loyalty). Azokat állítsd be, amelyek a termékedre vonatkoznak — a dashboard ehhez igazodik, és csak a kitöltött csomagokat jeleníti meg.

Azonosítás

Mindig releváns. A profilfejléc oszlopait állítja be.

Földrajzi adatok

Földrajzi kontextus.

Életciklus

Mikor láttuk.

Előfizetés

Állítsd be, ha a terméked csomagokat használ.

E-kereskedelem

Állítsd be, ha termékeket értékesítetek.

Média

Állítsd be, ha tartalmat publikáltok.

Piactér

Állítsd be, ha a terméked kétoldalú platform.

Hűségprogram

Állítsd be, ha elköteleződési vagy jutalmazási programot használtok.

Super-properties

Munkamenetszintű kulcs-érték párok, amelyek automatikusan rákerülnek minden kimenő eseményre. Ezek nem azonosak a(z) identify traitjeivel, amelyek az identitást írják le; a super-properties a munkamenet kontextusát hordozzák — például az aktív A/B variánst, a buildváltozatot vagy az engedélyezett feature flageket. A(z) UserDefaults indítások között is megőrzi őket; a(z) reset() törli őket. Ütközés esetén mindig a(z) track hívásban megadott eseményszintű properties az erősebb.

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

Képernyőkövetés SwiftUI-ban

A SwiftUI képernyőmegtekintéseket az SDK automatikusan követi, ha fel tudja oldani a nézet nevét. Ha finomabb vezérlésre vagy egyedi névre van szükséged, használd a(z) .kixoScreen() view modifiert:

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

Munkamenet-visszajátszás

A replay azt építi újra, amit a felhasználó ténylegesen látott: az SDK HEIC-kódolású képkockákat rögzít a képernyőről a nézethierarchia szerkezeti pillanatképével együtt, a dashboard lejátszója pedig ezeket az eseményidővonal mellett visszatekerhető lejátszássá fűzi össze. A projekt replay-beállításait itt adhatod meg: Vezérlőpult → Beállítások → Munkamenet-visszajátszás; az SDK ezt a szabályzatot automatikusan beolvassa, és az alkalmazás futása közben frissíti.

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

A dashboard vezérli, hogy engedélyezett-e a replay, milyen maszkolási és rögzítési módok érvényesek, illetve hogy a natív replay feltölthet-e mobilhálózaton. Ha a mobilhálózatos feltöltés tiltva van, a képkockák ettől még bekerülhetnek egy korlátozott méretű, eszközön tárolt pufferbe; a feltöltés megvárja az engedélyezett hálózatot.

Az SDK a projektben engedélyezett adatokat, valamint az alkalmazás által küldött eseményeket és tulajdonságokat rögzíti.

Maszkolás és adatvédelem

Mivel a replay pixeleket rögzít, a kitakarás még az eszközön megtörténik mielőtt bármelyik képkocka kódolásra kerülne. A jelszómezőket és más érzékeny mezőket a rendszer automatikusan felismeri és kitakarja, a strukturális pillanatképbe bekerülő szöveg pedig átmegy egy PII-szűrőn. Ha egyedi tartalmat is ki akarsz takarni — például privát üzenetszálat, számlaegyenleget vagy piszkozatképernyőt — állítsd be a(z) kxRedact értéket az adott view-n. A Kixo a HEIC-kódolás előtt egyszínű téglalapot rajzol a view határaira, így annak pixelei soha nem hagyják el az eszközt.

balanceLabel.kxRedact = true
cardNumberField.kxRedact = true

Pushértesítések

Az SDK futásidőben AppDelegate-proxyt telepít a(z) Kixo.configure fölé — a csendes pushok (content-available: 1) és a háttérben kézbesített, látható pushok automatikusan rögzülnek. Ehhez nem kell kódot írnod az AppDelegate-be. A meglévő UNUserNotificationCenterDelegate implementációk továbbra is rendesen lefutnak; a Kixo becsomagolja őket.

Regisztráld az eszköztokent a szokásos didRegisterForRemoteNotificationsWithDeviceToken hívással:

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

Ha az alkalmazás Firebase Messaginget használ, add át a regisztrációs tokent a(z) provider: .firebase hívással. A Kixo eltárolja a szolgáltatót, és FCM HTTP v1-en keresztül kézbesít; kampányküldés előtt állítsd be az alkalmazás Firebase-szolgáltatásfiókját a Kixo felületén.

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

Kézbesítés és offline működés

Az SDK helyben sorba állítja az eseményeket, kötegekben küldi el őket, és átmeneti hibák esetén backoffos újrapróbálkozást végez. Ha a gyűjtést a projektbeállításokban szünetelteted, az új események addig nem mennek ki, amíg újra be nem kapcsolod a gyűjtést.

Diagnosztika

Csak olvasható állapotkép. Hasznos hibakereső képernyőn vagy smoke tesztben: debugger nélkül is megmutatja, miért nem érkeznek az események.

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

Azonnali küldés kényszerítése (tesztekhez)

Szinkron változat, amely legfeljebb timeout másodpercig blokkol, amíg a flush be nem fejeződik. XCTest-fixture-ökhöz készült — a főszálról soha ne hívd meg.

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

Alaphelyzetbe állítás

Törli az identitást, a super-properties értékeit és a tartósan tárolt várólistát. Kijelentkezéskor hívd meg, hogy a későbbi események ne az előző felhasználóhoz legyenek társítva.

Kixo.reset()