iOS SDK

O SDK de Kixo para iOS admite Swift 5.9+ e iOS 16+ para analítica, atribución, push, seguimento do ciclo de vida e repetición de sesións. A repetición usa controis de captura a nivel de proxecto e valores predeterminados conservadores para os fluxos máis pesados; non require ningún mínimo adicional de OS nin de modelo de dispositivo máis alá do destino de despregamento iOS 16 do paquete. Distribuído mediante Swift Package Manager, o SDK rexistra automaticamente pantallas, toques, sesións, fallos, notificacións push e eventos do ciclo de vida cunha única chamada a Kixo.configure. O seguimento das solicitudes de rede é opcional.

Instalación

Swift Package Manager

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

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

Se xestionas as dependencias en Package.swift, usa o paquete binario de release e este produto:

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 na túa struct App de SwiftUI ou 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() }
    }
}

Opcións 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 rexistrados automaticamente

• screen_view — aparicións inmediatas de controladores de vista en UIKit + navegación de SwiftUI
• screen_visit — unha visita estruturada que se pecha ao navegar ou ao pasar a segundo plano, con tempo de permanencia, contadores de interacción, identidade da pantalla e metadatos do fluxo
• session_start / session_end
• tap — toques en botóns e recoñecedores de xestos
• crash — diagnósticos capturados de fallos e excepcións
• network — agregados opcionais de peticións saneadas e diagnósticos de rutas
• push_received / push_open / push_dismissed / push_silent / push_action — ciclo de vida completo das push
• push_permission / push_token_invalidated
• lifecycle — transicións entre primeiro plano, segundo plano e lanzamento da app

Eventos personalizados

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

Axudantes tipados para eventos

Atallo sobre Kixo.track para os eventos que Kixo recoñece polo nome (purchase, signup, subscribe_start, trial_start, cancel, upgrade, activation, share, invite). Ofrece validación en compilación da forma das propiedades e unha única fonte de verdade para os nomes das claves; o detector de eventos estándar do backend fai a correspondencia 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)

Identificar usuarios

As claves reservadas de propiedades estándar levan o prefixo $ (convención de Mixpanel) para separarse dos teus atributos personalizados e promocionarse ás columnas de perfil do dashboard. Usa o enum tipado StandardProperty ou a cadea literal co prefixo $; consulta Catálogo estándar de propiedades máis abaixo para ver a lista completa das 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 un usuario para segmentación

Usa setUserProperty cun valor boolean para engadir ao usuario unha etiqueta simple de si/non. A etiqueta mantense entre sesións e serve para segmentos, campañas de correo e consultas de chat, sen ningunha configuración adicional máis alá da chamada ao 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",
])

As propiedades persisten en UserDefaults entre lanzamentos e engádense automaticamente a cada evento saínte. No chat podes dicir cousas como "enviar un correo electrónico de benvida aos usuarios onde subscribe sexa true": Kixo crea o segmento e redacta a plantilla por ti. Límpanse con Kixo.reset().

Catálogo estándar de propiedades

As claves de propiedade reservadas levan o prefixo $ para separarse dos teus atributos personalizados. O catálogo de Kixo inclúe 37 claves repartidas en 3 paquetes universais (identidade, xeografía e ciclo de vida) e 5 paquetes verticais B2B (subscrición, e-commerce, media, marketplace e fidelización). Define as que se apliquen ao teu produto: o dashboard adáptase e só mostra os paquetes que estean cubertos.

Identidade

Sempre relevante. Define as columnas da cabeceira do perfil.

Geo

Contexto xeográfico.

Ciclo de vida

Cando o vimos.

Subscrición

Defíneo se o teu produto ten plans.

E-commerce

Defíneo se vendes produtos.

Media

Defíneo se publicas contido.

Marketplace

Defíneo se o teu produto é unha plataforma de dúas partes.

Fidelización

Defíneo se tes programas de participación e recompensas.

Superpropiedades

Pares clave/valor de sesión que se engaden automaticamente a cada evento saínte. A diferenza dos atributos identify (que describen a identidade), as superpropiedades describen o contexto da sesión: variante A/B activa, tipo de compilación e feature flags activadas. Persístense en UserDefaults entre lanzamentos e límpanse con reset(). Se hai conflito, as properties do evento en track sempre teñen prioridade.

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

Seguimento de pantallas en SwiftUI

As pantallas de SwiftUI rexístranse automaticamente cando o SDK pode resolver o nome da vista. Se precisas máis control ou nomes personalizados, usa o modificador de vista .kixoScreen():

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

Reprodución de sesións

Replay reconstrúe o que viu realmente o usuario: o SDK captura fotogramas da pantalla codificados en HEIC xunto cunha instantánea estrutural da xerarquía de vistas, e o reprodutor do dashboard úneos nunha reprodución navegable ao lado da liña temporal de eventos. Configura replay para o proxecto en Panel → Configuración → Repetición de sesións; o SDK le esa política automaticamente e actualízaa mentres a app está en execución.

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

O dashboard controla se replay está activado, o enmascaramento, os modos de captura e se o replay nativo pode subir datos por rede móbil. Coa subida por rede móbil desactivada, os fotogramas poden seguir capturándose nun búfer acoutado no dispositivo; a subida queda á espera dunha rede permitida.

O SDK captura os datos activados no proxecto e os eventos e propiedades que envía a túa aplicación.

Enmascaramento e privacidade

Como replay captura píxeles, a redacción faise no dispositivo antes de codificar ningún fotograma. Os campos de contrasinal e outros campos sensibles detéctanse e redáctanse automaticamente, e o texto incluído na instantánea estrutural pasa por un filtro de PII. Para redactar contido personalizado —un fío de mensaxes privadas, o saldo dunha conta ou unha pantalla en borrador— define kxRedact na vista. Kixo rasteriza un rectángulo sólido sobre os límites desa vista antes da codificación en HEIC, así que eses píxeles nunca saen do dispositivo.

balanceLabel.kxRedact = true
cardNumberField.kxRedact = true

Notificacións push

O SDK instala en tempo de execución un proxy de AppDelegate en Kixo.configure: as push silenciosas (content-available: 1) e as push visibles entregadas en segundo plano captúranse automaticamente. Non tes que engadir código no teu AppDelegate. As implementacións existentes de UNUserNotificationCenterDelegate seguen executándose con normalidade; Kixo limítase a encapsulalas.

Rexistra o token do dispositivo mediante o didRegisterForRemoteNotificationsWithDeviceToken estándar:

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

Se a app usa Firebase Messaging, pasa o seu token de rexistro con provider: .firebase. Kixo garda ese provedor e entrega a través de FCM HTTP v1; configura en Kixo a conta de servizo de Firebase da app antes de enviar campañas.

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

Entrega e funcionamento sen conexión

O SDK garda os eventos nunha cola local, envíaos por lotes e reintenta os fallos transitorios con backoff. Se a recollida se pausa desde a configuración do proxecto, os eventos novos non se envían ata que se reactive.

Diagnóstico

Instantánea de estado de só lectura. Útil en pantallas de depuración ou en smoke tests: responde a "por que non están chegando os eventos?" sen necesidade 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 o flush (para probas)

Sobrecarga síncrona que bloquea ata timeout segundos mentres remata un flush. Está pensada para fixtures de XCTest; non a chames nunca desde o fío principal.

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

Restablecer

Borra a identidade, as superpropiedades e a cola persistida. Chámao ao pechar sesión para que os eventos seguintes non se atribúan ao usuario anterior.

Kixo.reset()