iOS SDK

O Kixo iOS SDK suporta Swift 5.9+ e iOS 16+ para analytics, atribuição, push, rastreio do ciclo de vida e replay de sessões. O replay usa opções de captura ao nível do projeto e predefinições conservadoras para os pipelines mais exigentes; não impõe qualquer requisito adicional de OS ou de modelo de dispositivo além do deployment target iOS 16 do pacote. Distribuído através do Swift Package Manager, o SDK rastreia automaticamente ecrãs, toques, sessões, crashes, notificações push e eventos do ciclo de vida com uma única chamada a Kixo.configure. O rastreio de pedidos de rede é opt-in.

Instalação

Swift Package Manager

No Xcode, vá a File → Add Package Dependencies e introduza:

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

Se gere dependências em Package.swift, use o pacote binário de release e o 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

Inicialize a Kixo na sua struct SwiftUI App ou em AppDelegate:

import Kixo

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

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

Opções de configuração

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 recolhidos automaticamente

• screen_view — apresentação imediata de view controllers em UIKit + navegação em SwiftUI
• screen_visit — uma visita estruturada, encerrada na navegação ou quando a app passa para segundo plano, com tempo de permanência, contagens de engagement, identidade do ecrã e metadados de fluxo
• session_start / session_end
• tap — toques em botões e reconhecedores de gestos
• crash — diagnósticos de falhas e exceções captados
• network — agregados opcionais de pedidos com dados saneados e diagnósticos de rotas
• push_received / push_open / push_dismissed / push_silent / push_action — ciclo de vida completo das notificações push
• push_permission / push_token_invalidated
• lifecycle — transições entre primeiro plano, segundo plano e arranque da app

Eventos personalizados

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

Helpers de eventos tipados

Abstração sobre Kixo.track para os eventos que a Kixo reconhece pelo nome (purchase, signup, subscribe_start, trial_start, cancel, upgrade, activation, share, invite). Validação em tempo de compilação da estrutura das propriedades e uma única fonte de verdade para os nomes das chaves — o detetor de eventos padrão no backend faz correspondê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)

Identificar utilizadores

As chaves reservadas das propriedades padrão usam o prefixo $ (convenção Mixpanel), para ficarem separadas dos seus próprios atributos personalizados e serem promovidas às colunas de perfil no dashboard. Use o enum tipado StandardProperty ou a cadeia com o prefixo $ — veja Catálogo de propriedades padrão abaixo para a lista completa das 37 chaves.

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

Marcar um utilizador para segmentação

Use setUserProperty com um valor boolean para associar ao utilizador uma etiqueta simples de sim/não. A etiqueta mantém-se entre sessões e pode ser usada em segmentos, campanhas de email e consultas no chat — sem configuração adicional além 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 propriedades ficam guardadas em UserDefaults entre arranques e são anexadas automaticamente a todos os eventos enviados. No chat, diga algo como "envia um email de boas-vindas aos utilizadores em que subscribe é true" — Kixo cria o segmento e rascunha o modelo por si. São limpas em Kixo.reset().

Catálogo de propriedades padrão

As chaves de propriedade reservadas usam o prefixo $, para ficarem separadas dos seus atributos personalizados. O catálogo da Kixo abrange 37 chaves em 3 pacotes universais (identidade, geografia, ciclo de vida) e 5 pacotes verticais B2B (subscrição, comércio eletrónico, media, marketplace, fidelização). Defina apenas as que se aplicam ao seu produto — o dashboard adapta-se e mostra só os pacotes que preencher.

Identidade

Sempre relevante. Define as colunas do cabeçalho do perfil.

Geo

Contexto geográfico.

Ciclo de vida

Quando o vimos.

Subscrição

Defina se o seu produto tem planos.

Comércio eletrónico

Defina se vende produtos.

Media

Defina se publica conteúdo.

Marketplace

Defina se a sua plataforma é bilateral.

Fidelização

Defina para programas de engagement e recompensas.

Superpropriedades

Pares chave-valor por sessão, anexados automaticamente a todos os eventos enviados. Ao contrário dos atributos em identify (que descrevem a identidade), as superpropriedades descrevem o contexto da sessão — variante A/B ativa, variante de build, feature flags com opt-in. Ficam guardadas em UserDefaults entre arranques e são limpas em reset(). Em caso de colisão, as properties por evento em track prevalecem sempre.

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

Rastreio de ecrãs em SwiftUI

As visualizações de ecrã em SwiftUI são rastreadas automaticamente quando o SDK consegue resolver o nome da vista. Para um controlo mais fino ou nomes personalizados, use o modificador de vista .kixoScreen():

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

Reprodução de sessão

O replay reconstrói aquilo que o utilizador viu realmente — o SDK captura fotogramas do ecrã codificados em HEIC, juntamente com um instantâneo estrutural da hierarquia de vistas, e o leitor do dashboard recompõe tudo numa reprodução navegável ao lado da cronologia de eventos. Configure o replay do projeto em Painel → Definições → Reprodução de sessão; o SDK lê essa política automaticamente e atualiza-a enquanto a app está em execução.

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

O dashboard controla se o replay está ativo, o mascaramento, os modos de captura e se o replay nativo pode enviar dados por rede móvel. Com o envio por rede móvel desativado, os fotogramas podem continuar a ser capturados para um buffer local de tamanho limitado; o envio fica à espera de uma rede permitida.

O SDK capta os dados ativados no seu projeto, bem como os eventos e propriedades enviados pela sua aplicação.

Mascaramento e privacidade

Como o replay capta píxeis, a ocultação acontece no dispositivo antes de qualquer fotograma ser codificado. As palavras-passe e outros campos sensíveis são detetados e ocultados automaticamente, e o texto captado no instantâneo estrutural passa por um filtro de PII. Para ocultar qualquer elemento personalizado — uma conversa privada, um saldo de conta, um ecrã em rascunho — defina kxRedact na view. A Kixo rasteriza um retângulo sólido sobre os limites dessa view antes da codificação HEIC, por isso esses píxeis nunca saem do dispositivo.

balanceLabel.kxRedact = true
cardNumberField.kxRedact = true

Notificações push

O SDK instala em tempo de execução um proxy de AppDelegate em Kixo.configure — pushes silenciosas (content-available: 1) e pushes visíveis entregues em segundo plano são capturadas automaticamente. Não é necessário adicionar código ao AppDelegate. As implementações existentes de UNUserNotificationCenterDelegate continuam a ser chamadas normalmente; a Kixo apenas as encapsula.

Registe o token do dispositivo através de didRegisterForRemoteNotificationsWithDeviceToken:

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

Se a app usar Firebase Messaging, passe o respetivo token de registo com provider: .firebase. A Kixo guarda esse fornecedor e entrega através de FCM HTTP v1; configure a conta de serviço Firebase da app na Kixo antes de enviar campanhas.

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

Entrega e comportamento offline

O SDK coloca os eventos numa fila local, envia-os em lotes e repete tentativas em falhas transitórias com backoff. Se a recolha for suspensa nas definições do projeto, os novos eventos não são enviados até a recolha voltar a ser ativada.

Diagnóstico

Instantâneo do estado, só de leitura. Útil em ecrãs de depuração ou smoke tests — responde a «porque é que os meus eventos não estão a chegar?» sem precisar de um 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çar envio imediato (para testes)

Sobrecarga síncrona que bloqueia até timeout segundos à espera de um flush concluir. Pensada para fixtures de XCTest — nunca a chame a partir da thread principal.

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

Repor

Limpe a identidade, as superpropriedades e a fila persistida. Chame no logout para que os eventos seguintes não sejam atribuídos ao utilizador anterior.

Kixo.reset()