iOS SDK

De Kixo iOS SDK ondersteunt Swift 5.9+ en iOS 16+ voor analytics, attributie, push, lifecycle-tracking en session replay. Replay volgt de vastleginstellingen op projectniveau en gebruikt voor de zwaardere verwerkingspijplijnen terughoudende standaardwaarden; behalve het iOS 16-deploymenttarget van het package geldt er geen extra ondergrens voor OS of toestelmodel. De SDK wordt geleverd via Swift Package Manager en registreert met één aanroep van Kixo.configure automatisch schermen, taps, sessies, crashes, pushmeldingen en lifecycle-events. Het registreren van netwerkverzoeken is opt-in.

Installatie

Swift Package Manager

Ga in Xcode naar File → Add Package Dependencies en voer het volgende in:

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

Als je afhankelijkheden beheert in Package.swift, gebruik dan het binaire releasepakket en dit 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"),
        ]
    )
]

Configureren

Initialiseer Kixo in je SwiftUI-struct App of in AppDelegate:

import Kixo

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

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

Configuratieopties

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

Automatisch getrackte events

• screen_view — directe weergave van UIKit-viewcontrollers + SwiftUI-navigatie
• screen_visit — een gestructureerd bezoek dat bij navigatie of naar de achtergrond gaan wordt afgesloten, met verblijfsduur, engagementtellingen, schermidentiteit en flowmetadata
• session_start / session_end
• tap — tikken op knoppen en gesture recognizers
• crash — vastgelegde diagnostiek voor crashes en exceptions
• network — optionele opgeschoonde verzoeksaggregaten en routediagnostiek
• push_received / push_open / push_dismissed / push_silent / push_action — volledige pushlevenscyclus
• push_permission / push_token_invalidated
• lifecycle — overgangen tussen voorgrond, achtergrond en app-start

Aangepaste events

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

Getypeerde eventhelpers

Syntactische suiker boven op Kixo.track voor events die Kixo op naam herkent (purchase, signup, subscribe_start, trial_start, cancel, upgrade, activation, share, invite). Compile-time validatie van de property-structuur, één centrale bron voor sleutelnamen — de detector voor standaardevents in de backend vergelijkt letterlijk.

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)

Gebruikers identificeren

Gereserveerde sleutels voor standaardeigenschappen krijgen het voorvoegsel $ (Mixpanel-conventie). Zo blijven ze gescheiden van je eigen aangepaste traits en verschijnen ze in de profielkolommen van het dashboard. Gebruik de getypeerde StandardProperty-enum of de ruwe, met $ geprefixte string — zie Catalogus met standaardeigenschappen hieronder voor de volledige lijst met 37 sleutels.

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

Geef een gebruiker een tag voor segmentatie

Gebruik setUserProperty met een boolean-waarde om een eenvoudige ja/nee-tag aan de gebruiker te hangen. Die tag blijft over sessies heen bestaan en wordt gebruikt voor segmenten, e-mailcampagnes en chatquery's — zonder extra setup naast de SDK-aanroep.

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

Eigenschappen blijven in UserDefaults bewaard tussen appstarts en worden automatisch meegestuurd met elk uitgaand event. Zeg in chat bijvoorbeeld "stuur een welkomstmail naar gebruikers waarvoor subscribe true is" — Kixo maakt dan het segment en zet een eerste versie van de template klaar. Gewist bij Kixo.reset().

Catalogus met standaardeigenschappen

Gereserveerde property-sleutels krijgen het voorvoegsel $, zodat ze gescheiden blijven van je eigen traits. De catalogus van Kixo bevat 37 sleutels in 3 universele packs (identity, geo, lifecycle) en 5 B2B-specifieke packs (subscription, e-commerce, media, marketplace, loyalty). Stel alleen in wat voor jouw product relevant is — het dashboard past zich aan en toont alleen de packs die je gebruikt.

Identiteit

Altijd relevant. Bepaalt de kolommen in de profielkop.

Geo

Geografische context.

Levenscyclus

Wanneer hebben we deze gebruiker gezien?

Abonnement

Stel dit in als je product abonnementen heeft.

E-commerce

Stel dit in als je producten verkoopt.

Media

Stel dit in als je content publiceert.

Marktplaats

Stel dit in als je een tweezijdig platform hebt.

Loyaliteit

Stel dit in voor engagement- en beloningsprogramma’s.

Super-properties

Sleutel-waardeparen per sessie die automatisch aan elk uitgaand event worden toegevoegd. Anders dan identify traits, die de identiteit beschrijven, leggen super-properties de sessiecontext vast — actieve A/B-variant, buildvariant, ingeschakelde feature flags. Ze blijven in UserDefaults bewaard tussen appstarts en worden gewist bij reset(). Bij een botsing krijgen waarden per event in properties op track altijd voorrang.

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

Schermtracking in SwiftUI

Schermweergaven in SwiftUI worden automatisch gevolgd zodra de SDK een viewnaam kan bepalen. Wil je meer controle of eigen namen gebruiken, gebruik dan de viewmodifier .kixoScreen():

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

Sessie-replay

Replay reconstrueert wat de gebruiker echt zag — de SDK legt pixelframes van het scherm vast (HEIC-gecodeerd), samen met een structurele snapshot van de viewhiërarchie. De speler in het dashboard voegt die samen tot een doorspoelbare opname naast de gebeurtenistijdlijn. Configureer replay voor het project in Dashboard → Instellingen → Sessiereplay; de SDK leest dat beleid automatisch in en ververst het terwijl de app draait.

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

In het dashboard bepaal je of replay is ingeschakeld, hoe afscherming werkt, welke vastlegmodi worden gebruikt en of native replay via mobiele data mag uploaden. Als uploaden via mobiele data uitstaat, kunnen frames nog steeds worden vastgelegd in een afgebakende buffer op het apparaat; uploaden wacht dan op een toegestaan netwerk.

De SDK legt de gegevens vast die in je project zijn ingeschakeld, plus de events en properties die je app verstuurt.

Afscherming en privacy

Omdat replay pixels vastlegt, gebeurt redactie op het apparaat voordat ook maar één frame wordt gecodeerd. Wachtwoorden en andere gevoelige velden worden automatisch herkend en afgeschermd, en tekst die in de structurele snapshot terechtkomt gaat door een PII-filter. Wil je zelf iets afschermen — een privégesprek, een saldo of een conceptscherm — zet dan kxRedact op de view. Kixo rasteriseert dan vóór HEIC-codering een egaal vlak over de grenzen van die view, zodat die pixels het apparaat nooit verlaten.

balanceLabel.kxRedact = true
cardNumberField.kxRedact = true

Pushmeldingen

De SDK installeert tijdens runtime een AppDelegate-proxy op Kixo.configure. Silent pushes (content-available: 1) en zichtbare pushmeldingen die op de achtergrond worden afgeleverd, worden automatisch vastgelegd. Je hoeft daarvoor geen code aan je AppDelegate toe te voegen. Bestaande UNUserNotificationCenterDelegate-implementaties blijven normaal werken; Kixo wikkelt ze in.

Registreer het apparaattoken via de standaard didRegisterForRemoteNotificationsWithDeviceToken:

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

Als de app Firebase Messaging gebruikt, geef het registratietoken dan door met provider: .firebase. Kixo slaat die provider op en levert af via FCM HTTP v1; configureer het Firebase-serviceaccount van de app in Kixo voordat je campagnes verstuurt.

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

Verzending en gedrag bij offline gebruik

De SDK zet events lokaal in de wachtrij, verstuurt ze in batches en probeert tijdelijke fouten opnieuw met backoff. Als dataverzameling vanuit de projectinstellingen is gepauzeerd, worden nieuwe events pas weer verstuurd zodra die opnieuw is ingeschakeld.

Diagnostiek

Alleen-lezen statussnapshot. Handig in debugschermen of smoke tests — beantwoordt "waarom stromen mijn events niet door?" zonder debugger.

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

Direct flushen (voor tests)

Synchrone overload die maximaal timeout seconden blokkeert totdat een flush is afgerond. Bedoeld voor XCTest-fixtures — roep dit nooit aan vanaf de main thread.

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

Resetten

Wis de identiteit, super-properties en de bewaarde wachtrij. Roep dit aan bij uitloggen, zodat volgende events niet aan de vorige gebruiker worden toegeschreven.

Kixo.reset()