iOS SDK

Kixo iOS SDK podržava Swift 5.9+ i iOS 16+ za analitiku, atribuciju, push obavijesti, praćenje životnog ciklusa i replay sesije. Replay koristi prekidače snimanja postavljene na razini projekta i konzervativne zadane postavke za zahtjevnije tokove obrade; ne uvodi zaseban minimalni OS ni ograničenje po modelu uređaja iznad iOS 16 deployment targeta paketa. SDK se distribuira kroz Swift Package Manager i jednim pozivom Kixo.configure automatski bilježi zaslone, dodire, sesije, rušenja, push obavijesti i događaje životnog ciklusa. Praćenje mrežnih zahtjeva uključuje se po potrebi.

Instalacija

Swift Package Manager

U Xcodeu otvorite File → Add Package Dependencies i unesite:

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

Ako ovisnostima upravljate u Package.swift, koristite paket s binarnim izdanjem i ovaj proizvod:

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

Konfiguriraj

Inicijalizirajte Kixo u svojoj SwiftUI strukturi App ili u AppDelegate:

import Kixo

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

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

Opcije konfiguracije

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

Automatski praćeni događaji

• screen_view — trenutačna pojavljivanja UIKit kontrolera prikaza i SwiftUI navigacija
• screen_visit — strukturirani posjet koji se zatvara pri navigaciji ili odlasku u pozadinu, s vremenom zadržavanja, brojačima angažmana, identitetom zaslona i metapodacima toka
• session_start / session_end
• tap — dodiri gumba i prepoznavanje gesti
• crash — zabilježena dijagnostika rušenja i iznimki
• network — opcionalni pročišćeni agregati zahtjeva i dijagnostika ruta
• push_received / push_open / push_dismissed / push_silent / push_action — cijeli životni ciklus push obavijesti
• push_permission / push_token_invalidated
• lifecycle — prijelazi pri pokretanju aplikacije te odlasku u foreground i background

Prilagođeni događaji

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

Tipizirani pomoćnici za događaje

Praktični sloj nad Kixo.track za događaje koje Kixo prepoznaje po nazivu (purchase, signup, subscribe_start, trial_start, cancel, upgrade, activation, share, invite). Oblik svojstava provjerava se pri kompilaciji, a nazivi ključeva imaju jedan izvor istine — backendov detektor standardnih događaja traži potpuno podudaranje.

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)

Identificirajte korisnike

Rezervirani standardni ključevi svojstava nose prefiks $ (Mixpanel konvencija), čime se odvajaju od vaših prilagođenih atributa i mapiraju u stupce profila na nadzornoj ploči. Koristite tipizirani enum StandardProperty ili tekstualni ključ s prefiksom $ — puni popis svih 37 ključeva nalazi se u Katalog standardnih svojstava niže.

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čite korisnika za segmentaciju

Upotrijebite setUserProperty s vrijednošću boolean da korisniku dodate jednostavnu da/ne oznaku. Oznaka ostaje sačuvana kroz sesije i koristi se za segmente, e-mail kampanje i upite u chatu — bez ikakve dodatne postave osim poziva 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",
])

Svojstva se spremaju u UserDefaults, ostaju nakon ponovnog pokretanja aplikacije i automatski se dodaju svakom odlaznom događaju. U chatu možete reći nešto poput "pošalji e-poruku dobrodošlice korisnicima kod kojih je subscribe true" — Kixo će za vas složiti segment i pripremiti predložak. Brišu se pri Kixo.reset().

Katalog standardnih svojstava

Rezervirani ključevi svojstava nose prefiks $ kako bi bili odvojeni od vaših prilagođenih atributa. Kixo katalog pokriva 37 ključeva u 3 univerzalna paketa (identitet, geo, životni ciklus) i 5 B2B vertikalnih paketa (pretplata, e-trgovina, mediji, marketplace, program vjernosti). Postavite samo ono što odgovara vašem proizvodu — nadzorna ploča prilagođava se i prikazuje samo pakete koje popunite.

Identitet

Uvijek relevantno. Postavlja stupce zaglavlja profila.

Geo

Geografski kontekst.

Životni ciklus

Kad smo ih vidjeli.

Pretplata

Postavite ako vaš proizvod ima pakete.

E-trgovina

Postavite ako prodajete proizvode.

Mediji

Postavite ako objavljujete sadržaj.

Marketplace

Postavite ako ste dvostrana platforma.

Program vjernosti

Postavite ako imate programe angažmana i nagrađivanja.

Super-svojstva

Parovi ključ/vrijednost na razini sesije koji se automatski dodaju svakom odlaznom događaju. Za razliku od atributa identify, koji opisuju identitet, super-svojstva opisuju kontekst sesije — aktivnu A/B varijantu, varijantu builda i uključene feature flagove. Spremaju se u UserDefaults i ostaju nakon ponovnog pokretanja aplikacije; brišu se pri reset(). Svojstva properties postavljena za pojedini događaj na track uvijek imaju prednost pri koliziji.

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

Praćenje zaslona u SwiftUI

Prikazi zaslona u SwiftUI automatski se prate kad SDK može razriješiti naziv prikaza. Za precizniju kontrolu ili prilagođene nazive upotrijebite modifikator prikaza .kixoScreen():

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

Snimka sesije

Replay rekonstruira ono što je korisnik stvarno vidio — SDK bilježi kadrove zaslona kodirane u HEIC-u zajedno sa strukturnom snimkom hijerarhije prikaza, a reproduktor na nadzornoj ploči to spaja u reprodukciju kroz koju se može pomicati uz vremensku crtu događaja. Replay za projekt konfigurirajte u Nadzorna ploča → Postavke → Reprodukcija sesije; SDK tu politiku čita automatski i osvježava je dok aplikacija radi.

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

Na nadzornoj ploči određujete je li replay uključen, kako radi maskiranje, koji se načini snimanja koriste i smije li izvorni replay slati podatke preko mobilne mreže. Kad je slanje preko mobilne mreže isključeno, kadrovi se i dalje mogu spremati u ograničeni međuspremnik na uređaju; prijenos čeka dopuštenu mrežu.

SDK bilježi podatke uključene u vašem projektu te događaje i svojstva koja šalje aplikacija.

Maskiranje i privatnost

Budući da replay bilježi piksele, redakcija se obavlja na uređaju prije nego što se ijedan kadar kodira. Lozinke i druga osjetljiva polja automatski se prepoznaju i redigiraju, a tekst zabilježen u strukturnoj snimci prolazi kroz PII filtar. Ako želite redigirati nešto prilagođeno — privatnu prepisku, stanje računa, zaslon sa skicom — postavite kxRedact na taj view. Kixo prije HEIC kodiranja preko granica tog viewa iscrta puni pravokutnik, pa njegovi pikseli nikad ne napuštaju uređaj.

balanceLabel.kxRedact = true
cardNumberField.kxRedact = true

Push obavijesti

SDK na Kixo.configure u vrijeme izvođenja postavlja AppDelegate proxy — tihi push (content-available: 1) i vidljive push obavijesti isporučene u pozadini bilježe se automatski. Ne trebate dodavati kod u AppDelegate. Postojeće implementacije UNUserNotificationCenterDelegate i dalje se normalno pozivaju; Kixo ih samo obavija.

Registrirajte token uređaja preko standardnog didRegisterForRemoteNotificationsWithDeviceToken:

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

Ako aplikacija koristi Firebase Messaging, proslijedite njegov registracijski token kroz provider: .firebase. Kixo sprema tog pružatelja i isporuku obavlja preko FCM HTTP v1; prije slanja kampanja u Kixo konfigurirajte Firebase servisni račun aplikacije.

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

Isporuka i ponašanje izvan mreže

SDK lokalno stavlja događaje u red, šalje ih u paketima i kod prolaznih grešaka pokušava ponovno uz backoff. Ako je prikupljanje pauzirano u postavkama projekta, novi se događaji neće slati dok se ponovno ne uključi.

Dijagnostika

Pregled stanja samo za čitanje. Koristan je na debug zaslonima ili u smoke testovima — odgovara na pitanje "zašto mi događaji ne prolaze?" bez debuggera.

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

Prisilno slanje reda (za testove)

Sinkrona varijanta koja blokira do timeout sekundi dok se slanje ne dovrši. Namijenjena je za XCTest fixturee — nikad je ne pozivajte s glavne niti.

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

Resetiraj

Briše identitet, super-svojstva i trajno spremljeni red. Pozovite pri odjavi kako se sljedeći događaji ne bi pripisali prethodnom korisniku.

Kixo.reset()