iOS SDK

Das Kixo iOS SDK unterstützt Swift 5.9+ und iOS 16+ für Analytics, Attribution, Push, Lifecycle-Tracking und Session Replay. Für Replay gelten die projektweiten Erfassungsschalter und vorsichtige Standardwerte für die aufwendigeren Verarbeitungspfade; über das iOS-16-Deployment-Target des Pakets hinaus gibt es keine zusätzliche Mindestanforderung an OS oder Gerätemodell. Das SDK wird über den Swift Package Manager bereitgestellt und erfasst mit einem einzigen Aufruf von Kixo.configure automatisch Screens, Taps, Sitzungen, Abstürze, Push-Benachrichtigungen und Lifecycle-Events. Das Tracking von Netzwerkanfragen ist optional.

Installation

Swift Package Manager

Gehe in Xcode zu File → Add Package Dependencies und gib Folgendes ein:

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

Wenn du Abhängigkeiten in Package.swift verwaltest, verwende das Binary-Release-Paket und dieses 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"),
        ]
    )
]

Konfigurieren

Initialisiere Kixo in deiner SwiftUI-App-Struktur oder 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() }
    }
}

Konfigurationsoptionen

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 erfasste Events

• screen_view — unmittelbare View-Controller-Wechsel in UIKit plus SwiftUI-Navigation
• screen_visit — ein strukturierter Besuch, der bei Navigation oder beim Wechsel in den Hintergrund abgeschlossen wird, mit Verweildauer, Engagement-Zählern, Screen-Identität und Flow-Metadaten
• session_start / session_end
• tap — Button-Taps und Gestenerkenner
• crash — erfasste Diagnoseinformationen zu Abstürzen und Exceptions
• network — optionale bereinigte Request-Aggregate und Routen-Diagnosen
• push_received / push_open / push_dismissed / push_silent / push_action — kompletter Push-Lebenszyklus
• push_permission / push_token_invalidated
• lifecycle — Übergänge zwischen Vordergrund, Hintergrund und App-Start

Benutzerdefinierte Events

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

Typisierte Event-Helfer

Komfort-Wrapper um Kixo.track für Events, die Kixo am Namen erkennt (purchase, signup, subscribe_start, trial_start, cancel, upgrade, activation, share, invite). Property-Validierung zur Compile-Zeit und eine zentrale Quelle für Schlüsselnamen — der Standard-Event-Detektor im Backend gleicht sie exakt ab.

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)

Nutzer identifizieren

Reservierte Standard-Property-Keys tragen ein Präfix $ (Mixpanel-Konvention). So sind sie klar von deinen eigenen Traits getrennt und werden in die Profilspalten des Dashboards übernommen. Verwende entweder das typisierte Enum StandardProperty oder den mit $ präfixierten String — die vollständige Liste aller 37 Keys findest du unten in Standardkatalog für Properties.

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

Nutzer für die Segmentierung markieren

Verwende setUserProperty mit einem boolesch-Wert, um den Nutzer mit einem einfachen Ja/Nein-Merkmal zu versehen. Das Merkmal bleibt sitzungsübergreifend erhalten und kann für Segmente, E-Mail-Kampagnen und Chat-Abfragen genutzt werden — mehr als den SDK-Aufruf brauchst du nicht.

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

Properties bleiben in UserDefaults über App-Starts hinweg erhalten und werden automatisch an jedes ausgehende Event angehängt. Sag in Kixo Chat zum Beispiel "Sende eine Willkommens-E-Mail an Nutzer, bei denen subscribe true ist" — Kixo erstellt dir daraus das Segment und einen Vorlagenentwurf. Gelöscht bei Kixo.reset().

Standardkatalog für Properties

Reservierte Property-Schlüssel tragen das Präfix $, damit sie klar von deinen eigenen Traits getrennt sind. Der Katalog von Kixo umfasst 37 Schlüssel in 3 universellen Paketen (Identität, Geo, Lebenszyklus) und 5 B2B-Fachpaketen (Subscription, E-Commerce, Medien, Marktplatz, Loyalität). Setze einfach die Schlüssel, die zu deinem Produkt passen — das Dashboard passt sich an und zeigt nur die Pakete an, die du tatsächlich befüllst.

Identität

Immer relevant. Legt die Spalten im Profilkopf fest.

Geo

Geografischer Kontext.

Lebenszyklus

Wann wir sie zuletzt gesehen haben.

Abonnement

Setzen, wenn dein Produkt Tarife hat.

E-Commerce

Setzen, wenn du Produkte verkaufst.

Medien

Setzen, wenn du Inhalte veröffentlichst.

Marktplatz

Setzen, wenn dein Produkt eine zweiseitige Plattform ist.

Loyalität

Für Engagement- und Bonusprogramme setzen.

Super-Properties

Schlüssel/Wert-Paare pro Sitzung, die automatisch an jedes ausgehende Event angehängt werden. Anders als identify Traits, die die Identität beschreiben, erfassen Super-Properties den Sitzungskontext — etwa die aktive A/B-Variante, den Build-Typ oder aktivierte Feature-Flags. Sie bleiben in UserDefaults über App-Starts hinweg erhalten und werden bei reset() gelöscht. Ereignisspezifische properties in track haben bei Kollisionen immer Vorrang.

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

Screen-Tracking mit SwiftUI

Screen-Aufrufe in SwiftUI werden automatisch erfasst, wenn das SDK einen View-Namen auflösen kann. Für feinere Steuerung oder eigene Namen verwende den View-Modifier .kixoScreen():

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

Sitzungswiedergabe

Replay rekonstruiert, was der Nutzer tatsächlich gesehen hat: Das SDK erfasst Bildschirm-Frames im HEIC-Format zusammen mit einem strukturellen Snapshot der View-Hierarchie, und der Player im Dashboard setzt beides neben dem Event-Verlauf zu einer durchsuchbaren Wiedergabe zusammen. Konfiguriere Replay für das Projekt in Dashboard → Einstellungen → Sitzungswiedergabe; das SDK übernimmt diese Richtlinie automatisch und aktualisiert sie auch während die App läuft.

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

Im Dashboard steuerst du, ob Replay aktiv ist, welche Maskierung gilt, welche Aufnahmemodi verwendet werden und ob natives Replay über Mobilfunk hochladen darf. Ist der Upload über Mobilfunk deaktiviert, können Frames weiterhin in einen begrenzten Puffer auf dem Gerät aufgenommen werden; der Upload wartet dann auf ein erlaubtes Netzwerk.

Das SDK erfasst die in deinem Projekt aktivierten Daten sowie die Events und Properties, die deine App sendet.

Maskierung und Datenschutz

Da Replay Pixel erfasst, erfolgt die Schwärzung auf dem Gerät bevor, bevor überhaupt ein Frame kodiert wird. Passwörter und andere sensible Felder werden automatisch erkannt und geschwärzt, und Text aus dem strukturellen Snapshot läuft durch einen PII-Filter. Wenn du eigene Inhalte schwärzen willst — etwa einen privaten Nachrichtenverlauf, einen Kontostand oder einen Entwurfsbildschirm — setze kxRedact auf der View. Kixo rastert vor der HEIC-Kodierung ein deckendes Rechteck über die Begrenzungen dieser View, sodass ihre Pixel das Gerät nie verlassen.

balanceLabel.kxRedact = true
cardNumberField.kxRedact = true

Push-Benachrichtigungen

Das SDK installiert zur Laufzeit auf Kixo.configure einen AppDelegate-Proxy. Stille Pushes (content-available: 1) und sichtbare Pushes, die im Hintergrund zugestellt werden, werden automatisch erfasst. Zusätzlicher Code in deinem AppDelegate ist nicht nötig. Vorhandene UNUserNotificationCenterDelegate-Implementierungen laufen ganz normal weiter; Kixo hängt sich nur davor.

Registriere das Geräte-Token über das übliche didRegisterForRemoteNotificationsWithDeviceToken:

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

Wenn die App Firebase Messaging verwendet, übergib deren Registration Token mit provider: .firebase. Kixo speichert diesen Provider und versendet über FCM HTTP v1; konfiguriere das Firebase-Servicekonto der App in Kixo, bevor du Kampagnen sendest.

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

Auslieferung und Offline-Verhalten

Das SDK puffert Events lokal, sendet sie gebündelt und wiederholt vorübergehende Fehler mit Backoff. Wenn die Erfassung in den Projekteinstellungen pausiert ist, werden neue Events erst wieder gesendet, sobald die Erfassung wieder aktiviert wird.

Diagnostik

Schreibgeschützter Zustands-Snapshot. Hilfreich in Debug-Ansichten oder Smoke-Tests — beantwortet „Warum kommen meine Events nicht an?“ ohne 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

Flush erzwingen (für Tests)

Synchrone Überladung, die bis zu timeout Sekunden blockiert, bis ein Flush abgeschlossen ist. Gedacht für XCTest-Fixtures — niemals im Main Thread aufrufen.

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

Zurücksetzen

Löscht Identität, Super-Properties und die persistierte Queue. Beim Logout aufrufen, damit nachfolgende Events nicht dem vorherigen Nutzer zugeordnet werden.

Kixo.reset()