SDK de iOS

El SDK de Kixo para iOS es compatible con Swift 5.9+ e iOS 16+ para analítica, atribución, push, seguimiento del ciclo de vida y repetición de sesiones. Replay usa controles de captura a nivel de proyecto y ajustes conservadores en los flujos más pesados; no exige una versión mínima adicional de OS ni un modelo de dispositivo mínimo más allá del objetivo de despliegue iOS 16 del paquete. Se distribuye mediante Swift Package Manager y, con una sola llamada a Kixo.configure, registra automáticamente pantallas, toques, sesiones, cierres inesperados, notificaciones push y eventos del ciclo de vida. El seguimiento de solicitudes de red es opcional.

Instalación

Swift Package Manager

En Xcode, ve a File → Add Package Dependencies e introduce:

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

Si gestionas las dependencias en Package.swift, usa el paquete binario de release y este producto:

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

Configurar

Inicializa Kixo en tu struct App de SwiftUI o en AppDelegate:

import Kixo

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

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

Opciones de configuración

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

Eventos registrados automáticamente

• screen_view — apariciones inmediatas de controladores de vista de UIKit y navegación en SwiftUI
• screen_visit — una visita estructurada que se cierra al navegar o al pasar a segundo plano, con tiempo de permanencia, recuentos de interacción, identidad de pantalla y metadatos de flujo
• session_start / session_end
• tap — pulsaciones en botones y reconocedores de gestos
• crash — diagnósticos capturados de cierres inesperados y excepciones
• network — agregados opcionales depurados de peticiones y diagnósticos de rutas
• push_received / push_open / push_dismissed / push_silent / push_action — ciclo de vida completo de las notificaciones push
• push_permission / push_token_invalidated
• lifecycle — transiciones entre primer plano, segundo plano y arranque de la app

Eventos personalizados

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

Helpers tipados de eventos

Azúcar sintáctico sobre Kixo.track para los eventos que Kixo reconoce por nombre (purchase, signup, subscribe_start, trial_start, cancel, upgrade, activation, share, invite). Valida en compilación la estructura de las propiedades y centraliza los nombres de las claves; el detector de eventos estándar del backend compara literalmente.

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)

Identificar usuarios

Las claves reservadas de las propiedades estándar llevan el prefijo $ (convención de Mixpanel) para separarlas de tus atributos personalizados y promocionarlas a las columnas de perfil del panel. Usa el enum tipado StandardProperty o la cadena sin procesar con prefijo $; consulta la Catálogo estándar de propiedades más abajo para ver la lista completa de 37 claves.

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

Etiquetar a un usuario para segmentarlo

Usa setUserProperty con un valor booleano para añadir al usuario una etiqueta sencilla de sí o no. La etiqueta se conserva entre sesiones y sirve para segmentos, campañas de correo y consultas en el chat, sin más configuración que la llamada al 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",
])

Las propiedades se guardan en UserDefaults entre arranques y se adjuntan automáticamente a todos los eventos salientes. En el chat, di algo como "envía un correo de bienvenida a los usuarios cuyo subscribe sea true": Kixo crea el segmento y te prepara la plantilla. Se borran con Kixo.reset().

Catálogo estándar de propiedades

Las claves de propiedad reservadas llevan el prefijo $ para separarlas de tus atributos personalizados. El catálogo de Kixo incluye 37 claves repartidas en 3 bloques universales (identidad, geografía y ciclo de vida) y 5 bloques verticales B2B (suscripción, comercio electrónico, medios, marketplace y fidelización). Define solo las que encajen con tu producto: el panel se adapta y muestra únicamente los bloques que hayas rellenado.

Identidad

Siempre relevante. Define las columnas de la cabecera del perfil.

Geolocalización

Contexto geográfico.

Ciclo de vida

Cuándo lo vimos.

Suscripción

Úsalo si tu producto tiene planes.

Comercio electrónico

Úsalo si vendes productos.

Medios

Úsalo si publicas contenido.

Marketplace

Úsalo si tu producto es una plataforma de dos caras.

Fidelización

Úsalo para programas de fidelización y recompensas.

Superpropiedades

Pares clave/valor por sesión que se adjuntan automáticamente a todos los eventos salientes. A diferencia de los atributos de identify, que describen la identidad, las superpropiedades describen el contexto de la sesión: la variante A/B activa, la variante de compilación o las feature flags activadas. Se guardan en UserDefaults entre arranques y se borran con reset(). Si hay colisión, las properties por evento en track tienen prioridad.

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

Seguimiento de pantallas en SwiftUI

Las vistas de pantalla en SwiftUI se registran automáticamente cuando el SDK puede resolver el nombre de la vista. Si necesitas más control o nombres personalizados, usa el modificador de vista .kixoScreen():

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

Replay de sesiones

Replay reconstruye lo que el usuario vio realmente: el SDK captura fotogramas de la pantalla codificados en HEIC junto con una instantánea estructural de la jerarquía de vistas, y el reproductor del panel los recompone en una reproducción navegable junto a la cronología de eventos. Configura replay para el proyecto en Dashboard → Ajustes → Reproducción de sesiones; el SDK lee esa política automáticamente y la actualiza mientras la app está en ejecución.

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

El panel controla si Replay está activado, el enmascarado, los modos de captura y si el replay nativo puede subir datos por red móvil. Si la subida por red móvil está desactivada, los fotogramas pueden seguir capturándose en un búfer limitado del dispositivo; la subida esperará a una red permitida.

El SDK captura los datos activados en tu proyecto, además de los eventos y las propiedades que envía tu aplicación.

Enmascarado y privacidad

Como replay captura píxeles, la redacción se hace en el dispositivo antes de que se codifique cualquier fotograma. Los campos de contraseña y otros campos sensibles se detectan y se redactan automáticamente, y el texto capturado en la instantánea estructural pasa por un filtro de PII. Si quieres redactar algo específico —un hilo de mensajes privados, un saldo de cuenta o una pantalla en borrador—, define kxRedact en la vista. Kixo rasteriza un rectángulo sólido sobre los límites de esa vista antes de codificar en HEIC, así que sus píxeles nunca salen del dispositivo.

balanceLabel.kxRedact = true
cardNumberField.kxRedact = true

Notificaciones push

El SDK instala en tiempo de ejecución un proxy de AppDelegate en Kixo.configure: las push silenciosas (content-available: 1) y las push visibles entregadas en segundo plano se capturan automáticamente. No hace falta añadir código en tu AppDelegate. Las implementaciones existentes de UNUserNotificationCenterDelegate siguen ejecutándose con normalidad; Kixo las envuelve.

Registra el token del dispositivo con el didRegisterForRemoteNotificationsWithDeviceToken estándar:

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

Si la app usa Firebase Messaging, pasa su token de registro con provider: .firebase. Kixo guarda ese proveedor y envía a través de FCM HTTP v1; antes de enviar campañas, configura en Kixo la cuenta de servicio de Firebase de la app.

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

Entrega y comportamiento sin conexión

El SDK pone los eventos en cola localmente, los envía por lotes y reintenta los fallos transitorios con backoff. Si la recogida se pausa desde la configuración del proyecto, los eventos nuevos no se envían hasta que se vuelva a activar.

Diagnóstico

Instantánea de estado de solo lectura. Útil en pantallas de depuración o pruebas de humo: responde a «¿por qué no están llegando mis eventos?» sin necesidad de 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

Forzar el envío inmediato (para pruebas)

Sobrecarga síncrona que bloquea hasta timeout segundos mientras termina un vaciado. Está pensada para fixtures de XCTest; no la llames nunca desde el hilo principal.

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

Restablecer

Borra la identidad, las superpropiedades y la cola persistida. Llámalo al cerrar sesión para que los eventos posteriores no se atribuyan al usuario anterior.

Kixo.reset()