SDK iOS

Il Kixo iOS SDK supporta Swift 5.9+ e iOS 16+ per analytics, attribuzione, push, tracciamento del ciclo di vita e replay delle sessioni. Il replay usa interruttori di acquisizione configurati a livello di progetto e impostazioni conservative per i flussi più pesanti; non richiede una versione minima di OS né un modello di dispositivo diversi oltre al deployment target iOS 16 del pacchetto. Distribuito tramite Swift Package Manager, l’SDK traccia automaticamente schermate, tocchi, sessioni, crash, notifiche push ed eventi del ciclo di vita con una sola chiamata a Kixo.configure. Il tracciamento delle richieste di rete è opzionale.

Installazione

Swift Package Manager

In Xcode, vai in File → Add Package Dependencies e inserisci:

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

Se gestisci le dipendenze con Package.swift, usa il pacchetto binario di release e il relativo prodotto:

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

Inizializza Kixo nella struct App della tua app SwiftUI oppure 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() }
    }
}

Opzioni di configurazione

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

Eventi tracciati automaticamente

• screen_view — apparizioni immediate dei view controller UIKit e navigazione SwiftUI
• screen_visit — una visita strutturata che si chiude al cambio di schermata o al passaggio in background, con tempo di permanenza, conteggi di coinvolgimento, identità della schermata e metadati del flusso
• session_start / session_end
• tap — tocchi sui pulsanti e gesture recognizer
• crash — diagnostica acquisita di crash ed eccezioni
• network — aggregati facoltativi e sanitizzati delle richieste e diagnostica delle route
• push_received / push_open / push_dismissed / push_silent / push_action — ciclo di vita completo delle notifiche push
• push_permission / push_token_invalidated
• lifecycle — transizioni tra foreground, background e avvio dell’app

Eventi personalizzati

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

Helper tipizzati per gli eventi

Scorciatoia su Kixo.track per gli eventi che Kixo riconosce per nome (purchase, signup, subscribe_start, trial_start, cancel, upgrade, activation, share, invite). Offre validazione della forma delle proprietà in fase di compilazione e un’unica fonte di verità per i nomi delle chiavi: il rilevatore degli eventi standard nel backend fa corrispondenza letterale.

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 gli utenti

Le chiavi di proprietà standard riservate usano un prefisso $ (convenzione Mixpanel), così restano separate dai tuoi trait personalizzati e popolano le colonne profilo della dashboard. Usa l’enum tipizzato StandardProperty oppure la stringa con prefisso $; sotto trovi Catalogo standard delle proprietà con l’elenco completo delle 37 chiavi.

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

Assegna un tag a un utente per la segmentazione

Usa setUserProperty con un valore boolean per assegnare all’utente un semplice tag sì/no. Il tag persiste tra le sessioni e alimenta segmenti, campagne email e query in chat, senza alcuna configurazione oltre alla chiamata dell’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",
])

Le proprietà restano salvate in UserDefaults tra un avvio e l’altro e vengono aggiunte automaticamente a ogni evento in uscita. In chat puoi scrivere richieste come "invia un’email di benvenuto agli utenti per cui subscribe è true": Kixo crea il segmento e prepara per te la bozza del template. Vengono cancellate con Kixo.reset().

Catalogo standard delle proprietà

Le chiavi di proprietà riservate usano il prefisso $, così restano separate dai tuoi trait personalizzati. Il catalogo di Kixo comprende 37 chiavi distribuite in 3 pacchetti universali (identità, geolocalizzazione, ciclo di vita) e 5 pacchetti verticali B2B (abbonamenti, e-commerce, media, marketplace, fedeltà). Imposta solo quelle rilevanti per il tuo prodotto: la dashboard si adatta e mostra soltanto i pacchetti che popolari.

Identità

Sempre rilevante. Imposta le colonne dell'intestazione del profilo.

Geo

Contesto geografico.

Ciclo di vita

Quando l’abbiamo visto.

Abbonamento

Impostalo se il tuo prodotto prevede piani.

E-commerce

Impostalo se vendi prodotti.

Media

Impostalo se pubblichi contenuti.

Marketplace

Impostalo se il tuo prodotto è una piattaforma a due versanti.

Fedeltà

Impostalo per programmi di coinvolgimento e ricompense.

Super-property

Coppie chiave/valore di sessione aggiunte automaticamente a ogni evento in uscita. A differenza dei trait identify, che descrivono l’identità, le super-property descrivono il contesto della sessione: variante A/B attiva, flavor della build, feature flag attivate. Restano salvate in UserDefaults tra un avvio e l’altro e vengono cancellate con reset(). In caso di collisione, le properties del singolo evento passate a track hanno sempre la precedenza.

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

Tracciamento delle schermate in SwiftUI

Le schermate SwiftUI vengono tracciate automaticamente quando l’SDK riesce a risolvere il nome della view. Se ti serve più controllo o vuoi assegnare nomi personalizzati, usa il modificatore di view .kixoScreen():

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

Replay delle sessioni

Il replay ricostruisce ciò che l’utente ha visto davvero: l’SDK acquisisce i fotogrammi dello schermo codificati in HEIC insieme a uno snapshot strutturale della gerarchia delle view, e il player della dashboard li ricompone in una riproduzione navigabile accanto alla cronologia degli eventi. Configura il replay del progetto in Dashboard → Impostazioni → Replay sessione; l’SDK legge automaticamente questa policy e la aggiorna mentre l’app è in esecuzione.

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

Dalla dashboard puoi controllare se il replay è abilitato, il mascheramento, le modalità di acquisizione e se il replay nativo può caricare su rete cellulare. Se il caricamento su rete cellulare è disabilitato, i fotogrammi possono comunque essere acquisiti in un buffer locale a capacità limitata; il caricamento attende una rete consentita.

L’SDK raccoglie i dati abilitati nel progetto, oltre agli eventi e alle proprietà inviati dalla tua applicazione.

Mascheramento e privacy

Poiché il replay acquisisce i pixel, l’oscuramento avviene sul dispositivo prima di che un fotogramma venga codificato. Password e altri campi sensibili vengono rilevati e oscurati automaticamente, e il testo acquisito nello snapshot strutturale passa attraverso un filtro PII. Per oscurare elementi personalizzati — una conversazione privata, il saldo di un conto, una schermata in bozza — imposta kxRedact sulla view. Kixo rasterizza un rettangolo pieno sui limiti della view prima della codifica HEIC, quindi quei pixel non lasciano mai il dispositivo.

balanceLabel.kxRedact = true
cardNumberField.kxRedact = true

Notifiche push

L’SDK installa a runtime un proxy AppDelegate su Kixo.configure: le push silenziose (content-available: 1) e le push visibili consegnate in background vengono rilevate automaticamente. Non serve aggiungere codice al tuo AppDelegate. Le implementazioni esistenti di UNUserNotificationCenterDelegate continuano a essere eseguite normalmente; Kixo si limita a intercettarle.

Registra il token del dispositivo tramite il consueto didRegisterForRemoteNotificationsWithDeviceToken:

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

Se l’app usa Firebase Messaging, passa il token di registrazione con provider: .firebase. Kixo memorizza quel provider e recapita tramite FCM HTTP v1; prima di inviare campagne, configura in Kixo il service account Firebase dell’app.

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

Invio e comportamento offline

L’SDK accoda gli eventi in locale, li invia in batch e ritenta gli errori temporanei con backoff. Se la raccolta viene sospesa dalle impostazioni del progetto, i nuovi eventi non vengono inviati finché non viene riattivata.

Diagnostica

Stato di salute in sola lettura. Utile nelle schermate di debug o negli smoke test: risponde a "perché i miei eventi non stanno arrivando?" senza bisogno di un 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

Forza l’invio immediato (per i test)

Overload sincrono che blocca fino a timeout secondi in attesa del completamento di un flush. Pensato per le fixture XCTest: non chiamarlo mai dal thread principale.

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

Azzera

Cancella l’identità, le super-property e la coda persistita. Chiamalo al logout per evitare che gli eventi successivi vengano attribuiti all’utente precedente.

Kixo.reset()