SDK de iOS

El SDK de Kixo per a iOS és compatible amb Swift 5.9+ i iOS 16+ per a analítica, atribució, push, seguiment del cicle de vida i reproducció de sessió. La reproducció de sessió es regeix pels controls de captura del projecte i fa servir valors per defecte prudents per a les canonades més costoses; no estableix cap requisit extra d’OS ni de model de dispositiu més enllà del desplegament a iOS 16 del paquet. Es distribueix amb Swift Package Manager i, amb una sola crida a Kixo.configure, el SDK registra automàticament pantalles, tocs, sessions, fallades, notificacions push i esdeveniments del cicle de vida. El seguiment de peticions de xarxa és opcional.

Instal·lació

Swift Package Manager

A Xcode, ves a File → Add Package Dependencies i introdueix-hi:

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

Si gestiones les dependències amb Package.swift, fes servir el paquet binari de release i aquest producte:

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

Configura

Inicialitza Kixo a l’estructura App de SwiftUI o a AppDelegate:

import Kixo

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

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

Opcions de configuració

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

Esdeveniments registrats automàticament

• screen_view — aparicions immediates de controladors de vista d’UIKit i navegació de SwiftUI
• screen_visit — una visita estructurada que es tanca en navegar o en passar a segon pla, amb temps de permanència, comptadors d’interacció, identitat de pantalla i metadades de flux
• session_start / session_end
• tap — tocs en botons i recognizers de gestos
• crash — diagnòstics capturats de fallades i excepcions
• network — agregats opcionals de peticions sanejades i diagnòstics de ruta
• push_received / push_open / push_dismissed / push_silent / push_action — cicle de vida complet de les notificacions push
• push_permission / push_token_invalidated
• lifecycle — transicions entre primer pla, segon pla i arrencada de l’app

Esdeveniments personalitzats

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

Ajudants tipats d’esdeveniments

Sucre sintàctic sobre Kixo.track per als esdeveniments que Kixo reconeix pel nom (purchase, signup, subscribe_start, trial_start, cancel, upgrade, activation, share, invite). Ofereix validació en temps de compilació de l’estructura de les propietats i una única font de veritat per als noms de clau; el detector d’esdeveniments estàndard del backend hi fa coincidència literal.

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)

Identifica usuaris

Les claus reservades de propietat estàndard porten el prefix $ (convenció de Mixpanel), de manera que queden separades dels teus trets personalitzats i passen a les columnes de perfil del dashboard. Fes servir l’enum tipat StandardProperty o la cadena amb prefix $; al Catàleg estàndard de propietats de sota hi tens la llista completa de 37 claus.

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

Etiqueta un usuari per segmentar-lo

Fes servir setUserProperty amb un valor booleà per afegir a l’usuari una etiqueta senzilla de sí/no. L’etiqueta persisteix entre sessions i serveix per a segments, campanyes de correu i consultes al xat, sense cap configuració més enllà de la crida del 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",
])

Les propietats es conserven a UserDefaults entre arrencades i s’adjunten automàticament a tots els esdeveniments sortints. Al xat pots demanar coses com "envia un correu electrònic de benvinguda als usuaris on subscribe sigui true": Kixo crea el segment i redacta la plantilla per tu. S’esborren amb Kixo.reset().

Catàleg estàndard de propietats

Les claus de propietat reservades porten el prefix $ per no barrejar-se amb els teus trets personalitzats. El catàleg de Kixo inclou 37 claus repartides en 3 paquets universals (identitat, geografia i cicle de vida) i 5 paquets verticals B2B (subscripció, comerç electrònic, mitjans, marketplace i fidelització). Defineix només les que s’apliquin al teu producte: el dashboard s’adapta i només mostra els paquets que tinguis emplenats.

Identitat

Sempre rellevant. Defineix les columnes de capçalera del perfil.

Geo

Context geogràfic.

Cicle de vida

Quan l’hem vist.

Subscripció

Defineix-ho si el teu producte té plans.

Comerç electrònic

Defineix-ho si vens productes.

Mitjans

Defineix-ho si publiques contingut.

Marketplace

Defineix-ho si el teu producte és una plataforma de dues bandes.

Fidelització

Defineix-ho per a programes d’interacció i de recompenses.

Superpropietats

Parells clau-valor per sessió que s’adjunten automàticament a tots els esdeveniments sortints. A diferència dels trets identify (que descriuen la identitat), les superpropietats descriuen el context de la sessió: variant A/B activa, variant de compilació i feature flags activades. Es conserven a UserDefaults entre arrencades i s’esborren amb reset(). Si hi ha conflicte, sempre prevalen les properties de l’esdeveniment a track.

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

Seguiment de pantalles a SwiftUI

Les visualitzacions de pantalla de SwiftUI es registren automàticament quan l’SDK pot resoldre el nom de la vista. Si vols més control o noms personalitzats, fes servir el modificador de vista .kixoScreen():

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

Reproducció de sessions

Replay reconstrueix el que l’usuari ha vist realment: l’SDK captura fotogrames de la pantalla codificats en HEIC juntament amb una instantània estructural de la jerarquia de vistes, i el reproductor del dashboard els combina en una reproducció navegable al costat de la cronologia d’esdeveniments. Configura replay per al projecte a Tauler > Configuració > Reproducció de sessions; l’SDK llegeix aquesta política automàticament i la va actualitzant mentre l’app s’executa.

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

El dashboard controla si replay està activat, l’emmascarament, els modes de captura i si el replay natiu pot pujar dades per xarxa mòbil. Si la pujada per dades mòbils està desactivada, els fotogrames es poden continuar capturant en un buffer limitat al dispositiu; la pujada espera fins a tenir una xarxa permesa.

El SDK captura les dades que tinguis activades al projecte i els esdeveniments i propietats que envia l’aplicació.

Emmascarament i privacitat

Com que replay captura píxels, la redacció es fa al dispositiu abans que s’arribi a codificar cap fotograma. Les contrasenyes i altres camps sensibles es detecten i es redacten automàticament, i el text capturat a la instantània estructural passa per un filtre de PII. Per redactar qualsevol element personalitzat —un fil privat de missatges, un saldo de compte o una pantalla d’esborrany— defineix kxRedact a la vista. Kixo rasteritza un rectangle sòlid sobre els límits d’aquella vista abans de la codificació HEIC, de manera que els seus píxels no surten mai del dispositiu.

balanceLabel.kxRedact = true
cardNumberField.kxRedact = true

Notificacions push

El SDK instal·la un proxy d’AppDelegate en temps d’execució a Kixo.configure: les push silencioses (content-available: 1) i les push visibles lliurades en segon pla es capturen automàticament. No cal afegir cap codi a l’AppDelegate. Les implementacions existents de UNUserNotificationCenterDelegate continuen executant-se amb normalitat; Kixo les encapsula.

Registra el token del dispositiu amb el didRegisterForRemoteNotificationsWithDeviceToken estàndard:

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

Si l’app fa servir Firebase Messaging, passa’n el token de registre amb provider: .firebase. Kixo desa aquest proveïdor i envia a través d’FCM HTTP v1; abans d’enviar campanyes, configura a Kixo el compte de servei de Firebase de l’app.

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

Enviament i comportament fora de línia

L’SDK posa els esdeveniments en cua localment, els envia per lots i reintenta els errors transitoris amb backoff. Si s’atura la recollida des de la configuració del projecte, els esdeveniments nous no s’envien fins que es torna a activar.

Diagnòstics

Instantània d’estat en mode només lectura. Útil en pantalles de depuració o smoke tests: respon per què no arriben els esdeveniments sense necessitat d’un depurador.

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

Força l’enviament immediat (per a proves)

Sobrecàrrega síncrona que bloqueja fins a timeout segons mentre es completa un enviament immediat. Està pensada per a fixtures d’XCTest; no la cridis mai des del fil principal.

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

Restableix

Esborra la identitat, les superpropietats i la cua persistent. Crida-ho en tancar sessió perquè els esdeveniments següents no s’atribueixin a l’usuari anterior.

Kixo.reset()