SDK iOS

SDK-ul Kixo pentru iOS suportă Swift 5.9+ și iOS 16+ pentru analytics, atribuire, push, urmărirea ciclului de viață și session replay. Replay folosește comutatoare de captură la nivel de proiect și valori implicite prudente pentru fluxurile sale mai costisitoare; nu impune o versiune minimă separată de OS sau un prag pe model de dispozitiv peste deployment target-ul iOS 16 al pachetului. Distribuit prin Swift Package Manager, SDK-ul urmărește automat ecrane, atingeri, sesiuni, crash-uri, notificări push și evenimente de ciclu de viață printr-un singur apel Kixo.configure. Urmărirea cererilor de rețea este opțională.

Instalare

Swift Package Manager

În Xcode, mergi la File → Add Package Dependencies și introdu:

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

Dacă gestionezi dependențele în Package.swift, folosește pachetul binar de release și produsul:

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

Configurează

Inițializează Kixo în structura SwiftUI App sau în 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țiuni de configurare

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

Evenimente urmărite automat

• screen_view — apariții imediate ale controllerelor de vizualizare UIKit + navigare SwiftUI
• screen_visit — o vizită structurată, încheiată la navigare sau la trecerea în fundal, cu timp petrecut, număr de interacțiuni, identitatea ecranului și metadate de flux
• session_start / session_end
• tap — apăsări pe butoane și recognizere de gesturi
• crash — diagnostic pentru crash-uri și excepții capturate
• network — agregări opționale de cereri sanitizate și diagnostic de rute
• push_received / push_open / push_dismissed / push_silent / push_action — ciclul complet de viață al notificărilor push
• push_permission / push_token_invalidated
• lifecycle — tranziții între prim-plan / fundal / lansarea aplicației

Evenimente personalizate

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

Helpere de evenimente tipate

Un strat de conveniență peste Kixo.track pentru evenimentele pe care Kixo le recunoaște după nume (purchase, signup, subscribe_start, trial_start, cancel, upgrade, activation, share, invite). Primești validare la compilare pentru forma proprietăților și o singură sursă de adevăr pentru numele cheilor — detectorul de evenimente standard din backend caută o potrivire exactă.

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)

Identifică utilizatorii

Cheile rezervate pentru proprietățile standard au prefixul $ (convenția Mixpanel), ca să nu intre în conflict cu trăsăturile tale personalizate și să fie promovate în coloanele de profil din dashboard. Folosește enumul tipizat StandardProperty sau șirul cu prefixul $ — vezi Catalogul standard de proprietăți mai jos pentru lista completă, cu 37 de chei.

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

Etichetează un utilizator pentru segmentare

Folosește setUserProperty cu o valoare boolean pentru a atașa utilizatorului o etichetă simplă de tip da/nu. Eticheta persistă între sesiuni și poate fi folosită în segmente, campanii de e-mail și interogări în chat — fără configurare suplimentară în afară de apelul 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",
])

Proprietățile se păstrează în UserDefaults între lansări și se atașează automat fiecărui eveniment trimis. În chat poți spune, de exemplu, "trimite un email de bun venit utilizatorilor unde subscribe este true" — Kixo construiește segmentul și îți pregătește șablonul. Se șterg la Kixo.reset().

Catalogul standard de proprietăți

Cheile de proprietăți rezervate folosesc prefixul $, ca să nu intre în conflict cu trăsăturile tale personalizate. Catalogul Kixo acoperă 37 de chei în 3 pachete universale (identitate, geo, ciclu de viață) și 5 pachete verticale B2B (abonamente, e-commerce, media, marketplace, loialitate). Setează doar ce se aplică produsului tău — dashboardul se adaptează și afișează doar pachetele pe care le populezi.

Identitate

Întotdeauna relevant. Definește coloanele din antetul profilului.

Geo

Context geografic.

Ciclu de viață

Când l-am văzut.

Abonament

Folosește-l dacă produsul tău are planuri.

Comerț electronic

Folosește-l dacă vinzi produse.

Media

Folosește-l dacă publici conținut.

Marketplace

Folosește-l dacă produsul tău este o platformă cu două laturi.

Loialitate

Folosește-l pentru programe de engagement și recompense.

Super-proprietăți

Perechi cheie-valoare la nivel de sesiune, atașate automat fiecărui eveniment trimis. Spre deosebire de trăsăturile identify, care descriu identitatea, super-proprietățile descriu contextul sesiunii — varianta A/B activă, tipul de build și feature flag-urile activate. Se păstrează în UserDefaults între lansări și se șterg la reset(). Dacă apare un conflict, proprietățile properties setate pe track la nivel de eveniment au întotdeauna prioritate.

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

Urmărirea ecranelor în SwiftUI

Vizualizările de ecran din SwiftUI sunt urmărite automat când SDK poate determina numele view-ului. Pentru control mai fin sau nume personalizate, folosește modificatorul de view .kixoScreen():

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

Reluarea sesiunii

Replay reconstruiește ce a văzut efectiv utilizatorul: SDK capturează cadre ale ecranului, codate HEIC, împreună cu un instantaneu structural al ierarhiei de view-uri, iar playerul din dashboard le îmbină într-o redare derulabilă lângă cronologia evenimentelor. Configurezi replay la nivel de proiect în Panou de control → Setări → Redare sesiune; SDK citește automat politica și o reîmprospătează cât timp aplicația rulează.

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

Dashboardul controlează dacă replay este activ, regulile de mascare, modurile de captură și dacă replay-ul nativ poate încărca prin rețeaua celulară. Dacă încărcarea prin rețeaua celulară este dezactivată, cadrele pot fi totuși capturate într-un buffer local cu dimensiune limitată; încărcarea așteaptă o rețea permisă.

SDK-ul captează datele activate în proiectul tău, precum și evenimentele și proprietățile trimise de aplicație.

Mascare și confidențialitate

Pentru că replay captează pixeli, redactarea are loc pe dispozitiv înainte să fie codificat vreun cadru. Parolele și alte câmpuri sensibile sunt detectate și redactate automat, iar textul capturat în instantaneul structural trece printr-un filtru PII. Ca să redactezi orice element personalizat — un fir privat de mesaje, soldul unui cont, un ecran în lucru — setează kxRedact pe view. Kixo rasterizează un dreptunghi plin peste limitele acelui view înainte de codarea HEIC, astfel încât pixelii lui să nu părăsească niciodată dispozitivul.

balanceLabel.kxRedact = true
cardNumberField.kxRedact = true

Notificări push

SDK-ul instalează la runtime un proxy AppDelegate pe Kixo.configure — push-urile silențioase (content-available: 1) și push-urile vizibile livrate în fundal sunt capturate automat. Nu trebuie să adaugi cod în AppDelegate. Implementările existente pentru UNUserNotificationCenterDelegate continuă să fie apelate normal; Kixo le interceptează.

Înregistrează tokenul dispozitivului prin didRegisterForRemoteNotificationsWithDeviceToken standard:

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

Dacă aplicația folosește Firebase Messaging, transmite tokenul de înregistrare prin provider: .firebase. Kixo reține acel furnizor și livrează prin FCM HTTP v1; configurează în Kixo contul de serviciu Firebase al aplicației înainte de a trimite campanii.

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

Livrare și comportament offline

SDK-ul pune evenimentele în coadă local, le trimite în loturi și reîncearcă erorile tranzitorii cu backoff. Dacă colectarea este pusă pe pauză din setările proiectului, evenimentele noi nu mai sunt trimise până când colectarea este reactivată.

Diagnosticare

Instantaneu read-only al stării de sănătate. Util în ecrane de depanare sau în smoke test-uri — răspunde la „de ce nu ajung evenimentele?” fără 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

Flush forțat (pentru teste)

Supraincărcare sincronă care blochează până la timeout secunde, până se termină un flush. Gândită pentru fixture-uri XCTest — nu o apela niciodată din firul principal.

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

Resetează

Șterge identitatea, super-proprietățile și coada persistentă. Apelează la logout, ca evenimentele ulterioare să nu mai fie atribuite utilizatorului anterior.

Kixo.reset()