iOS SDK

Il-Kixo iOS SDK jappoġġja Swift 5.9+ u iOS 16+ għal analytics, attribution, push, lifecycle tracking u session replay. Ir-replay juża swiċċijiet ta’ capture fil-livell tal-project u settings konservattivi għall-pipelines itqal tiegħu; ma jdaħħalx limitu separat ta’ OS jew ta’ mudell ta’ apparat lil hinn mit-target ta’ deployment iOS 16 tal-package. Jitqassam permezz ta’ Swift Package Manager, u b’sejħa waħda ta’ Kixo.configure l-SDK jittraċċa awtomatikament screens, taps, sessions, crashes, push notifications u lifecycle events. It-traċċar tan-network requests huwa opt-in.

Installazzjoni

Swift Package Manager

F’Xcode, mur File → Add Package Dependencies u daħħal:

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

Jekk tmexxi d-dependencies f’Package.swift, uża l-binary release package u l-product li ġej:

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

Ikkonfigura

Inizjalizza Kixo fl-istruttura SwiftUI App tiegħek jew f’AppDelegate:

import Kixo

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

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

Għażliet ta’ konfigurazzjoni

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

Events ittraċċjati awtomatikament

• screen_view — dehriet immedjati ta’ UIKit view-controller + SwiftUI navigation
• screen_visit — żjara strutturata li tingħalaq fuq navigation/background b’dwell, għadd ta’ involviment, identità tal-iskrin u metadata tal-flow
• session_start / session_end
• tap — taps fuq buttons u gesture recognizers
• crash — dijanjostika maqbuda ta’ crashes u exceptions
• network — aggregates sanitiżżati tar-requests u dijanjostika tar-routes, jekk attivati
• push_received / push_open / push_dismissed / push_silent / push_action — iċ-ċiklu sħiħ tal-push
• push_permission / push_token_invalidated
• lifecycle — tranżizzjonijiet ta’ foreground / background / app-launch

Avvenimenti personalizzati

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

Helpers typed għall-events

Saff ta’ konvenjenza fuq Kixo.track għall-events li Kixo jagħraf bl-isem (purchase, signup,subscribe_start, trial_start,cancel, upgrade, activation,share, invite). Validazzjoni waqt il-compile tal-forma tal-properties, u sors wieħed tal-verità għall-ismijiet taċ-ċwievet — id-detector tal-standard events fil-backend jaqbel verbatim.

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)

Identifika l-utenti

Iċ-ċwievet riservati tal-standard properties iġorru prefiss $ (konvenzjoni Mixpanel) biex jinżammu separati mit-traits personalizzati tiegħek u jidhru fil-kolonni tal-profile fid-dashboard. Uża l-enum typed StandardProperty jew is-string raw bil-prefiss $ — ara l-Katalgu standard tal-properties hawn taħt għal-lista sħiħa tas-37 ċavetta.

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

Ittikketta utent għas-segmentazzjoni

Uża setUserProperty b’valur ta’ boolean biex iżżid tikketta sempliċi iva/le mal-utent. It-tikketta tibqa’ bejn is-sessions u tintuża għas-segments, email campaigns u chat queries — bla setup ieħor barra s-sejħa tal-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",
])

Il-properties jinżammu f’UserDefaults bejn launches u jitwaħħlu awtomatikament ma’ kull event li joħroġ. Fiċ-chat għid affarijiet bħal "ibgħat email ta’ merħba lill-utenti fejn subscribe huwa true" — Kixo jibni s-segment u jabbozza t-template għalik. Jitħassru fuq Kixo.reset().

Katalgu standard tal-properties

Iċ-ċwievet riservati tal-properties iġorru prefiss $ biex jinżammu separati mit-traits personalizzati tiegħek. Il-katalgu ta’ Kixo jkopri 37 ċavetta f’3 pakketti universali (identity, geo, lifecycle) u 5 pakketti vertikali B2B (subscription, e-commerce, media, marketplace, loyalty). Issettja biss dawk li japplikaw għall-prodott tiegħek — id-dashboard jadatta u juri biss il-pakketti li timla.

Identità

Dejjem rilevanti. Tissettja l-kolonni tal-header tal-profil.

Geo

Kuntest ġeografiku.

Ċiklu tal-ħajja

Meta rajniehom.

Abbonament

Issettja dan jekk il-prodott tiegħek għandu plans.

E-commerce

Issettja dan jekk tbigħ prodotti.

Midja

Issettja dan jekk tippubblika kontenut.

Suq

Issettja dan jekk inti pjattaforma b’żewġ naħat.

Lealtà

Issettja dan għal programmi ta’ involviment u rewards.

Super-properties

Pari ċavetta/valur għal kull session, imwaħħla awtomatikament ma’ kull event li joħroġ. Huma differenti mit-traits ta’ identify (li jiddeskrivu l-identità); is-super-properties jiddeskrivu l-kuntest tas-session — varjant A/B attiv, build flavor, feature flags attivati b’opt-in. Jinżammu f’UserDefaults bejn launches; jitħassru fuq reset(). Jekk ikun hemm collision, dejjem jirbħu l-properties ta’ kull event fuq track.

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

Screen tracking ta’ SwiftUI

L-iskrins ta’ SwiftUI jittraċċjaw ruħhom awtomatikament meta l-SDK ikun jista’ jsolvi isem ta’ view. Għal aktar kontroll jew ismijiet personalizzati, uża l-view modifier .kixoScreen():

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

Ripetizzjoni tas-sessjoni

Replay jerġa’ jibni dak li l-utent verament ra — l-SDK jaqbad frames tal-pixels tal-iskrin (encoded b’HEIC) flimkien ma’ snapshot strutturali tal-view hierarchy, u l-player tad-dashboard jgħaqqadhom f’playback li tista’ tgħaddi minnu ħdejn it-timeline tal-events. Ikkonfigura replay għall-project f’Dashboard → Settings → Ripetizzjoni tas-sessjoni; l-SDK jaqra dik il-policy awtomatikament u jġeddedha waqt li l-app tkun miftuħa.

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

Id-dashboard jikkontrolla jekk replay huwiex attivat, il-masking, il-modi tal-qbid, u jekk native replay jistax itella’ fuq cellular. Jekk l-upload fuq cellular ikun diżattivat, il-frames xorta jistgħu jinġabru f’buffer limitat fuq l-apparat; l-upload jistenna netwerk permess.

L-SDK jaqbad id-data attivata fil-project tiegħek, kif ukoll l-events u l-properties li tibgħat l-applikazzjoni tiegħek.

Masking u privatezza

Minħabba li replay jaqbad pixels, ir-redaction isseħħ fuq l-apparat qabel ma jiġi encoded xi frame. Passwords u fields sensittivi oħra jinstabu u jitħbew awtomatikament, u t-test maqbud fis-structural snapshot jgħaddi minn filtru PII. Biex taħbi xi ħaġa personalizzata — thread privat ta’ messaġġi, bilanċ ta’ kont, screen ta’ draft — issettja kxRedact fuq il-view. Kixo jirrasterizza rettanglu solidu fuq il-limiti ta’ dik il-view qabel l-encoding HEIC, għalhekk il-pixels tagħha qatt ma jitilqu mill-apparat.

balanceLabel.kxRedact = true
cardNumberField.kxRedact = true

Notifiki push

L-SDK jinstalla proxy runtime ta’ AppDelegate fuq Kixo.configure — silent pushes (content-available: 1) u pushes viżibbli li jitwasslu fil-background jinqabdu awtomatikament. Ma hemm bżonn ta’ ebda kodiċi fl-AppDelegate tiegħek. Implementazzjonijiet eżistenti ta’ UNUserNotificationCenterDelegate jibqgħu jissejħu kif suppost; Kixo sempliċement jgħaddihom minnu.

Irreġistra d-device token permezz tal-didRegisterForRemoteNotificationsWithDeviceToken standard:

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

Jekk l-app tuża Firebase Messaging, għaddi r-registration token tagħha ma’ provider: .firebase. Kixo jaħżen dak il-provider u jwassal permezz ta’ FCM HTTP v1; ikkonfigura l-Firebase service account tal-app f’Kixo qabel tibgħat campaigns.

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

Konsenja u mġiba offline

L-SDK iżomm l-events f’kju lokalment, jibgħathom f’batches, u jerġa’ jipprova fallimenti temporanji b’backoff. Jekk il-ġbir jitwaqqaf mis-settings tal-project, events ġodda ma jintbagħtux sakemm il-ġbir jerġa’ jiġi attivat.

Dijanjostiċi

Snapshot read-only tas-saħħa tas-sistema. Utli fi debug screens jew smoke tests — iwieġeb "għaliex l-events tiegħi mhumiex deħlin?" mingħajr 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

Sforza flush (għat-tests)

Overload sinkroniku li jimblokka sa timeout sekondi sakemm jitlesta flush. Maħsub għal XCTest fixtures — qatt issejjaħhiex mill-main thread.

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

Irrisettja

Ħassar l-identità, is-super-properties u l-kju persistit. Sejjaħha fuq logout biex events sussegwenti ma jiġux attribwiti lill-utent ta’ qabel.

Kixo.reset()