iOS SDK

Kixo iOS SDK toetab versioone Swift 5.9+ ja iOS 16+ ning katab analüütika, atributsiooni, tõuketeavitused, elutsükli jälgimise ja seansitaasesituse. Taasesitus kasutab projekti tasemel salvestuslüliteid ja ressursimahukamate torude jaoks ettevaatlikke vaikeseadeid; eraldi OS-i või seadmemudeli miinimumnõuet peale paketi iOS 16 deployment target'i sel ei ole. SDK levib Swift Package Manageri kaudu ja hakkab ühe Kixo.configure kutsega automaatselt jälgima ekraane, puudutusi, seansse, krahhe, tõuketeavitusi ja elutsükli sündmusi. Võrgupäringute jälgimine on valikuline.

Paigaldamine

Swift Package Manager

Xcode’is ava File → Add Package Dependencies ja sisesta:

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

Kui haldad sõltuvusi Package.swift-is, kasuta binaarset release-paketti ja toodet:

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

Seadista

Lähtesta Kixo oma SwiftUI App struktuuris või asukohas AppDelegate:

import Kixo

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

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

Seadistussuvandid

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

Automaatselt jälgitavad sündmused

• screen_view — kohesed UIKit view controller'i ilmumised ja SwiftUI navigeerimine
• screen_visit — struktureeritud külastus, mis suletakse navigeerimisel või taustale minekul ning sisaldab viibimisaega, kaasatuse loendureid, ekraani identiteeti ja voo metaandmeid
• session_start / session_end
• tap — nupupuudutused ja viibetuvastid
• crash — salvestatud krahhi- ja erandidiagnostika
• network — valikulised puhastatud päringukoondid ja marsruudi diagnostika
• push_received / push_open / push_dismissed / push_silent / push_action — tõuketeavituste täielik elutsükkel
• push_permission / push_token_invalidated
• lifecycle — üleminekud esiplaani, tausta ja rakenduse käivitamise vahel

Kohandatud sündmused

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

Tüübitud sündmuseabilised

Mugavuskiht Kixo.track peale sündmustele, mille Kixo tunneb ära nime järgi (purchase, signup, subscribe_start, trial_start, cancel, upgrade, activation, share, invite). Omaduste kuju compile-time valideerimine ja üks tõeallikas võtmenimede jaoks — backendi standardsete sündmuste tuvastaja võrdleb neid üks-ühele.

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)

Tuvasta kasutajad

Reserveeritud standardomaduste võtmetel on eesliide $ (Mixpanel tavakonventsioon), et need eristuksid sinu enda kohandatud tunnustest ja jõuaksid töölaua profiiliveergudesse. Kasuta tüübitud StandardProperty enum'it või toorest $-eesliitega stringi — kõigi 37 võtme täieliku loendi leiad allpool jaotisest Standardomaduste kataloog.

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

Märgista kasutaja segmenteerimiseks

Kasuta setUserProperty koos väärtusega boolean, et lisada kasutajale lihtne jah/ei-silt. Silt püsib seansside vahel ja seda kasutavad segmendid, e-posti kampaaniad ning vestluspäringud — peale SDK kutse pole muud seadistust vaja.

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

Omadused püsivad UserDefaults-is ka pärast rakenduse taaskäivitust ja lisatakse automaatselt igale väljaminevale sündmusele. Ütle vestluses näiteks "saada tervitusmeil kasutajatele, kellel subscribe on true" — Kixo loob segmendi ja koostab sulle malli. Tühjendatakse Kixo.reset() korral.

Standardomaduste kataloog

Reserveeritud omaduste võtmetel on eesliide $, et need ei läheks segi sinu kohandatud tunnustega. Kixo kataloogis on 37 võtit: 3 universaalset pakki (identiteet, geo, elutsükkel) ja 5 B2B vertikaalpakki (tellimus, e-kaubandus, meedia, turg, lojaalsus). Määra need, mis sinu toote puhul kehtivad — töölaud kohandub ja kuvab ainult täidetud pakid.

Identiteet

Alati asjakohane. Määrab profiilipäise veerud.

Geo

Geograafiline kontekst.

Elutsükkel

Millal me neid nägime.

Tellimus

Määra see, kui sinu tootel on paketid.

E-kaubandus

Määra see, kui müüd tooteid.

Meedia

Määra see, kui avaldad sisu.

Turg

Määra see, kui sinu toode on kahepoolne platvorm.

Lojaalsus

Määra see kaasatus- ja preemiaprogrammide puhul.

Super-properties

Seansipõhised võtme-väärtuse paarid, mis lisatakse automaatselt igale väljaminevale sündmusele. Need erinevad identify tunnustest, mis kirjeldavad identiteeti; super-properties kirjeldavad seansi konteksti, näiteks aktiivset A/B varianti, build flavor'it ja lubatud feature flag'e. Need püsivad UserDefaults-is ka pärast rakenduse taaskäivitust ja tühjendatakse reset() korral. Kui tekib kattuvus, jäävad alati peale sündmusepõhised properties väärtused track-s.

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

SwiftUI ekraanijälgimine

SwiftUI ekraanivaateid jälgitakse automaatselt, kui SDK suudab vaate nime tuvastada. Täpsemaks juhtimiseks või kohandatud nimede jaoks kasuta vaatemuundurit .kixoScreen():

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

Seansi taasesitus

Replay taastab selle, mida kasutaja tegelikult nägi — SDK salvestab ekraani pikslikaadrid HEIC-kodeeringus koos vaatehierarhia struktuurse hetkeseisuga ning töölaud ühendab need sündmuste ajajoone kõrval keritavaks taasesituseks. Seadista projekti replay asukohas Töölaud → Seaded → Sessiooni taasesitus; SDK loeb selle poliitika automaatselt sisse ja värskendab seda rakenduse töö ajal.

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

Töölaud juhib, kas replay on lubatud, kuidas maskeerimine töötab, milliseid salvestusrežiime kasutatakse ja kas native replay tohib mobiilside kaudu üles laadida. Kui mobiilside kaudu üleslaadimine on keelatud, võivad kaadrid siiski koguneda seadmes piiratud puhvrisse; üleslaadimine ootab sobiva võrgu olemasolu.

SDK kogub need andmed, mis on sinu projektis lubatud, ning need sündmused ja omadused, mida rakendus saadab.

Maskeerimine ja privaatsus

Kuna replay salvestab piksleid, tehakse varjamine seadmes enne, enne kui ükski kaader kodeeritakse. Parooli- ja muud tundlikud väljad tuvastatakse ning varjatakse automaatselt, ja struktuursesse hetkeseisu salvestatav tekst läbib PII-filtri. Kui tahad varjata midagi kohandatut — näiteks privaatset sõnumilõime, kontojääki või mustandikuva — määra vaatele kxRedact. Kixo rasteriseerib selle vaate piiridesse enne HEIC-kodeerimist ühtlase täitega ristküliku, nii et selle pikslid ei lahku kunagi seadmest.

balanceLabel.kxRedact = true
cardNumberField.kxRedact = true

Tõuketeavitused

SDK paigaldab Kixo.configure jaoks käitusajal AppDelegate proxy — silent push'id (content-available: 1) ja taustal kohale toimetatud nähtavad push'id salvestatakse automaatselt. AppDelegate'i ei ole vaja selleks eraldi koodi lisada. Olemasolevad UNUserNotificationCenterDelegate teostused töötavad edasi tavapäraselt; Kixo mähib need ümber.

Registreeri seadme token standardse didRegisterForRemoteNotificationsWithDeviceToken kaudu:

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

Kui rakendus kasutab Firebase Messagingut, edasta selle registreerimistoken provider: .firebase kaudu. Kixo salvestab selle pakkuja ja saadab teavitused läbi FCM HTTP v1; enne kampaaniate saatmist seadista Kixos rakenduse Firebase service account.

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

Edastamine ja käitumine võrguühenduseta olekus

SDK paneb sündmused kohalikku järjekorda, saadab need pakkidena ja proovib ajutiste tõrgete korral kasvava viitega uuesti. Kui kogumine on projekti seadetest peatatud, uusi sündmusi ei saadeta enne, kui kogumine uuesti lubatakse.

Diagnostika

Kirjutuskaitstud tervise hetkeseis. Kasulik silumisekraanidel või smoke test'ides — vastab küsimusele „miks mu sündmused ei liigu?” ka ilma debugger'ita.

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

Sunni tühjendamine (testide jaoks)

Sünkroonne overload, mis blokeerib kuni timeout sekundit, kuni flush lõpeb. Mõeldud XCTesti fixture'ite jaoks — ära kutsu seda kunagi põhilõimest.

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

Lähtesta

Tühjenda identiteet, super-properties ja püsiv järjekord. Kutsu seda väljalogimisel, et järgmisi sündmusi ei omistataks eelmisele kasutajale.

Kixo.reset()