SDK iOS

Le SDK iOS de Kixo prend en charge Swift 5.9+ et iOS 16+ pour l’analytics, l’attribution, les notifications push, le suivi du cycle de vie et le rejeu de session. Le rejeu s’appuie sur des options de capture définies au niveau du projet et sur des réglages prudents par défaut pour ses pipelines les plus lourds ; il n’impose pas de version d’OS ni de modèle d’appareil minimum distincts au-delà de la cible de déploiement iOS 16 du package. Distribué via Swift Package Manager, le SDK suit automatiquement les écrans, les appuis, les sessions, les crashs, les notifications push et les événements du cycle de vie avec un seul appel à Kixo.configure. Le suivi des requêtes réseau est optionnel.

Installation

Swift Package Manager

Dans Xcode, ouvrez File → Add Package Dependencies, puis saisissez :

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

Si vous gérez vos dépendances dans Package.swift, utilisez ce paquet binaire et ce produit :

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

Configurer

Initialisez Kixo dans votre struct SwiftUI App ou dans AppDelegate :

import Kixo

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

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

Options de configuration

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

Événements suivis automatiquement

• screen_view — affichage immédiat des contrôleurs de vue UIKit + navigation SwiftUI
• screen_visit — visite structurée close lors d’une navigation ou d’un passage en arrière-plan, avec temps de présence, compteurs d’engagement, identité de l’écran et métadonnées de parcours
• session_start / session_end
• tap — appuis sur les boutons et détecteurs de gestes
• crash — diagnostics de crash et d’exception collectés
• network — agrégats facultatifs de requêtes nettoyées et diagnostics de routes
• push_received / push_open / push_dismissed / push_silent / push_action — cycle de vie complet des notifications push
• push_permission / push_token_invalidated
• lifecycle — transitions premier plan / arrière-plan / lancement de l’app

Événements personnalisés

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

Helpers d’événements typés

Surcouche de Kixo.track pour les événements que Kixo reconnaît par leur nom (purchase, signup, subscribe_start, trial_start, cancel, upgrade, activation, share, invite). Validation à la compilation de la forme des propriétés, source unique pour les noms de clés ; côté backend, le détecteur d’événements standard compare les noms à l’identique.

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)

Identifier les utilisateurs

Les clés de propriété standard réservées portent le préfixe $ (convention Mixpanel), ce qui les distingue de vos propres attributs personnalisés et les fait remonter dans les colonnes de profil du dashboard. Utilisez l’enum typé StandardProperty ou la chaîne brute préfixée par $ ; consultez le Catalogue des propriétés standard ci-dessous pour la liste complète des 37 clés.

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

Ajouter un tag de segmentation à un utilisateur

Utilisez setUserProperty avec une valeur booléen pour ajouter à l’utilisateur un indicateur simple oui/non. Cet indicateur persiste d’une session à l’autre et sert aux segments, aux campagnes e-mail et aux requêtes dans le chat, sans configuration supplémentaire au-delà de l’appel au 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",
])

Ces propriétés persistent dans UserDefaults entre deux lancements et sont ajoutées automatiquement à chaque événement sortant. Dans le chat, vous pouvez écrire par exemple "envoyer un e-mail de bienvenue aux utilisateurs pour lesquels subscribe est true" ; Kixo crée alors le segment et prépare le modèle pour vous. Elles sont effacées par Kixo.reset().

Catalogue des propriétés standard

Les clés de propriété réservées portent le préfixe $, ce qui les isole de vos attributs personnalisés. Le catalogue de Kixo couvre 37 clés réparties en 3 packs universels (identité, géolocalisation, cycle de vie) et 5 packs métier B2B (abonnement, e-commerce, médias, marketplace, fidélité). Définissez uniquement celles qui s’appliquent à votre produit : le dashboard s’adapte et n’affiche que les packs que vous renseignez.

Identité

Toujours pertinent. Définit les colonnes d’en-tête du profil.

Géographie

Contexte géographique.

Cycle de vie

À quel moment les avons-nous vus ?

Abonnement

À renseigner si votre produit propose des offres.

E-commerce

À renseigner si vous vendez des produits.

Médias

À renseigner si vous publiez du contenu.

Marketplace

À renseigner si votre produit est une plateforme à deux versants.

Fidélité

À renseigner pour les programmes d’engagement et de récompenses.

Super-propriétés

Paires clé/valeur propres à la session, ajoutées automatiquement à chaque événement sortant. À la différence des propriétés identify, qui décrivent l’identité, les super-propriétés décrivent le contexte de session : variante A/B active, variante de build, feature flags activés. Elles persistent dans UserDefaults entre deux lancements et sont effacées par reset(). En cas de collision, les properties passées sur l’événement dans track priment toujours.

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

Suivi des écrans en SwiftUI

Les vues d’écran SwiftUI sont suivies automatiquement lorsque le SDK parvient à résoudre un nom de vue. Pour un contrôle plus fin ou pour définir des noms personnalisés, utilisez le modificateur de vue .kixoScreen() :

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

Replay de session

Replay reconstitue ce que l’utilisateur a réellement vu : le SDK capture des images de l’écran encodées en HEIC, ainsi qu’un instantané structurel de la hiérarchie de vues. Le lecteur du dashboard les assemble ensuite en une lecture navigable, avec curseur, à côté de la chronologie des événements. Configurez Replay pour le projet dans Dashboard → Settings → Relecture de session ; le SDK lit automatiquement cette politique et la met à jour pendant l’exécution de l’app.

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

Le dashboard contrôle l’activation de Replay, le masquage, les modes de capture et l’autorisation d’envoi du replay natif sur réseau cellulaire. Si l’envoi sur réseau cellulaire est désactivé, les images peuvent tout de même être capturées dans un tampon local de taille bornée ; leur envoi attendra ensuite un réseau autorisé.

Le SDK capture les données activées dans votre projet, ainsi que les événements et propriétés envoyés par votre application.

Masquage et confidentialité

Comme Replay capture des pixels, le masquage s’effectue sur l’appareil avant qu’une image ne soit encodée. Les mots de passe et autres champs sensibles sont détectés et masqués automatiquement, et le texte inclus dans l’instantané structurel passe par un filtre PII. Pour masquer un élément spécifique — conversation privée, solde de compte, écran de brouillon — définissez kxRedact sur la vue. Avant l’encodage HEIC, Kixo rastérise un rectangle opaque sur toute la zone de cette vue : ses pixels ne quittent donc jamais l’appareil.

balanceLabel.kxRedact = true
cardNumberField.kxRedact = true

Notifications push

Le SDK installe à l’exécution un proxy AppDelegate sur Kixo.configure : les notifications push silencieuses (content-available: 1) et les notifications visibles reçues en arrière-plan sont capturées automatiquement. Vous n’avez rien à ajouter dans votre AppDelegate. Les implémentations existantes de UNUserNotificationCenterDelegate continuent d’être appelées normalement ; Kixo les encapsule.

Enregistrez le jeton de l’appareil via le didRegisterForRemoteNotificationsWithDeviceToken standard :

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

Si l’app utilise Firebase Messaging, transmettez son jeton d’enregistrement avec provider: .firebase. Kixo enregistre ce fournisseur et assure l’envoi via FCM HTTP v1 ; configurez dans Kixo le compte de service Firebase de l’app avant d’envoyer des campagnes.

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

Envoi et comportement hors ligne

Le SDK met les événements en file d’attente localement, les envoie par lots et réessaie les échecs temporaires avec temporisation exponentielle. Si la collecte est suspendue dans les paramètres du projet, les nouveaux événements ne sont plus envoyés tant qu’elle n’est pas réactivée.

Diagnostic

Instantané d’état en lecture seule. Pratique dans un écran de debug ou un smoke test : répond à « Pourquoi mes événements ne remontent-ils pas ? » sans passer par un débogueur.

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

Forcer l’envoi immédiat (tests)

Surcharge synchrone qui bloque jusqu’à timeout secondes, le temps que l’envoi se termine. Conçue pour les fixtures XCTest ; ne l’appelez jamais depuis le thread principal.

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

Réinitialiser

Efface l’identité, les super-propriétés et la file d’attente persistée. À appeler lors de la déconnexion pour que les événements suivants ne soient pas attribués à l’utilisateur précédent.

Kixo.reset()