iOS SDK

SDK i Kixo për iOS mbështet Swift 5.9+ dhe iOS 16+ për analitikë, atribim, push, gjurmim të ciklit të jetës dhe riprodhim sesioni. Replay përdor çelësa kapjeje në nivel projekti dhe parazgjedhje konservatore për rrjedhat më të rënda; nuk vendos një kufi më vete për OS ose model pajisjeje përtej objektivit iOS 16 të paketës. Shpërndahet përmes Swift Package Manager dhe gjurmon automatikisht ekranet, tap-et, sesionet, crash-et, njoftimet push dhe ngjarjet e ciklit të jetës me një thirrje të vetme Kixo.configure. Gjurmimi i kërkesave të rrjetit aktivizohet vetëm nëse e zgjidhni vetë.

Instalimi

Swift Package Manager

Në Xcode, shko te File → Add Package Dependencies dhe vendos:

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

Nëse i menaxhon varësitë në Package.swift, përdor paketën binare release dhe produktin përkatës:

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

Konfiguro

Inicializo Kixo në strukturën tënde SwiftUI App ose te AppDelegate:

import Kixo

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

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

Opsionet e konfigurimit

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

Evente të gjurmuara automatikisht

• screen_view — shfaqje të menjëhershme të view controller-ave të UIKit + lundrim SwiftUI
• screen_visit — një vizitë e strukturuar që mbyllet në lundrim ose kur aplikacioni kalon në sfond, me kohë qëndrimi, numërime ndërveprimesh, identitet ekrani dhe metatëdhëna rrjedhe
• session_start / session_end
• tap — prekje butonash dhe njohës gjestesh
• crash — diagnostikim i kapur për crash-e dhe exception-e
• network — përmbledhje të sanitizuara të kërkesave dhe diagnostikë opsionale të rrugëve
• push_received / push_open / push_dismissed / push_silent / push_action — cikli i plotë i push-it
• push_permission / push_token_invalidated
• lifecycle — kalime mes foreground / background / app-launch

Evente të personalizuara

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

Ndihmës me tipe për eventet

Shtresë lehtësuese mbi Kixo.track për eventet që Kixo i njeh nga emri (purchase, signup, subscribe_start, trial_start, cancel, upgrade, activation, share, invite). Verifikim në compile-time i formës së vetive dhe një burim i vetëm i së vërtetës për emrat e çelësave — detektori i eventeve standarde në backend përputhet fjalë për fjalë.

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)

Identifiko përdoruesit

Çelësat standardë të rezervuar të vetive mbajnë prefiksin $ (sipas konventës Mixpanel), që të dallohen nga tiparet e tua të personalizuara dhe të shfaqen në kolonat e profilit në dashboard. Përdor enum-in me tipe StandardProperty ose vargun me prefiks $ — shih Katalogu standard i vetive më poshtë për listën e plotë me 37 çelësa.

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

Etiketo një përdorues për segmentim

Përdorni setUserProperty me një vlerë boolean për t’i shtuar përdoruesit një etiketë të thjeshtë po/jo. Etiketa ruhet mes sesioneve dhe përdoret nga segmentet, fushatat me email dhe pyetjet në chat — pa asnjë konfigurim tjetër përtej thirrjes së 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",
])

Vetitë ruhen në UserDefaults edhe pas rihapjes së aplikacionit dhe i bashkëngjiten automatikisht çdo eventi dalës. Në chat mund të thuash gjëra si "dërgo një email mirëseardhjeje për përdoruesit ku subscribe është true" — Kixo ndërton segmentin dhe përgatit draftin e shabllonit për ty. Pastrohen në Kixo.reset().

Katalogu standard i vetive

Çelësat e rezervuar të vetive mbajnë prefiksin $, që të dallohen nga tiparet e tua të personalizuara. Katalogu i Kixo mbulon 37 çelësa në 3 paketa universale (identitet, gjeografi, cikël jete) dhe 5 paketa vertikale B2B (abonim, e-commerce, media, treg, besnikëri). Vendos vetëm ato që vlejnë për produktin tënd — dashboard-i përshtatet dhe shfaq vetëm paketat që ke plotësuar.

Identiteti

Gjithmonë e vlefshme. Përcakton kolonat e header-it të profilit.

Geo

Kontekst gjeografik.

Cikli i jetës

Kur e kemi parë.

Abonim

Vendose nëse produkti yt ka plane.

E-commerce

Vendose nëse shet produkte.

Media

Vendose nëse publikon përmbajtje.

Treg

Vendose nëse je platformë me dy anë.

Besnikëri

Vendose nëse ke programe angazhimi dhe shpërblimesh.

Super-properties

Çifte çelës/vlerë për sesionin, që i bashkëngjiten automatikisht çdo eventi dalës. Ndryshe nga tiparet identify (që përshkruajnë identitetin), super-properties përshkruajnë kontekstin e sesionit — varianti aktiv A/B, varianti i build-it, feature flags të aktivizuara me opt-in. Ruhen në UserDefaults edhe pas rihapjes së aplikacionit; pastrohen në reset(). Në rast përplasjeje, properties për event në track kanë gjithmonë përparësi.

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

Gjurmimi i ekraneve në SwiftUI

Shikimet e ekraneve në SwiftUI gjurmohen automatikisht kur SDK arrin të përcaktojë emrin e pamjes. Për kontroll më të imtësishëm ose për emra të personalizuar, përdor view modifier-in .kixoScreen():

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

Riprodhim sesioni

Replay rindërton atë që përdoruesi ka parë realisht — SDK regjistron kuadrot me pikselë të ekranit (të koduar me HEIC) bashkë me një fotografi strukturore të hierarkisë së pamjeve, dhe luajtësi në dashboard i bashkon në një riprodhim të navigueshëm pranë kronologjisë së eventeve. Konfiguro replay për projektin te Paneli → Cilësimet → Riluajtja e sesionit; SDK e lexon automatikisht këtë politikë dhe e rifreskon ndërsa aplikacioni është në punë.

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

Dashboard-i kontrollon nëse replay është aktiv, maskimin, mënyrat e regjistrimit dhe nëse replay vendas mund të ngarkojë përmes rrjetit celular. Kur ngarkimi përmes celularit është i çaktivizuar, kuadrot mund të regjistrohen sërish në një buffer të kufizuar në pajisje; ngarkimi pret derisa të ketë një rrjet të lejuar.

SDK kap të dhënat që janë aktivizuar në projektin tuaj, si edhe ngjarjet dhe vetitë që dërgon aplikacioni juaj.

Maskimi dhe privatësia

Meqë replay regjistron pikselët, redaktimi ndodh në pajisje para të kodohet qoftë edhe një kuadër. Fjalëkalimet dhe fushat e tjera sensitive dallohen dhe redaktohen automatikisht, ndërsa teksti i kapur në fotografinë strukturore kalon përmes një filtri PII. Për të redaktuar çfarëdo elementi të personalizuar — një bisedë private, një bilanc llogarie, një ekran draft — vendos kxRedact te pamja përkatëse. Kixo vizaton një drejtkëndësh të plotë mbi kufijtë e asaj pamjeje përpara kodimit HEIC, kështu që pikselët e saj nuk dalin kurrë nga pajisja.

balanceLabel.kxRedact = true
cardNumberField.kxRedact = true

Njoftime push

SDK instalon një proxy runtime të AppDelegate në Kixo.configure — silent pushes (content-available: 1) dhe push-et e dukshme të dorëzuara në sfond kapen automatikisht. Nuk nevojitet kod në AppDelegate. Zbatimet ekzistuese të UNUserNotificationCenterDelegate vazhdojnë të thirren normalisht; Kixo thjesht i mbështjell.

Regjistro token-in e pajisjes përmes didRegisterForRemoteNotificationsWithDeviceToken standard:

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

Nëse aplikacioni përdor Firebase Messaging, kalo token-in e regjistrimit me provider: .firebase. Kixo ruan atë ofrues dhe dërgon përmes FCM HTTP v1; përpara se të dërgosh fushata, konfiguro llogarinë e shërbimit të Firebase të aplikacionit në Kixo.

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

Dërgimi dhe sjellja jashtë linje

SDK i ruan eventet lokalisht në radhë, i dërgon me paketa dhe riprovon dështimet e përkohshme me backoff. Nëse mbledhja pezullohet nga cilësimet e projektit, eventet e reja nuk dërgohen derisa mbledhja të riaktivizohet.

Diagnostikim

Pamje e gjendjes vetëm për lexim. E dobishme në ekrane debug ose smoke tests — i përgjigjet pyetjes "pse nuk po mbërrijnë eventet?" pa hapur 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

Detyro flush-in (për teste)

Overload sinkron që bllokon deri në timeout sekonda derisa të përfundojë një flush. Është menduar për fixture të XCTest — mos e thirr kurrë nga main thread.

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

Rivendos

Pastro identitetin, super-properties dhe radhën e ruajtur. Thirre në dalje, që eventet pasuese të mos i atribuohen përdoruesit të mëparshëm.

Kixo.reset()