iOS SDK

Kixo iOS SDK palaiko Swift 5.9+ ir iOS 16+; jis apima analitiką, atribuciją, push pranešimus, gyvavimo ciklo stebėjimą ir sesijų atkūrimą. Atkūrimas naudoja projekto lygmens fiksavimo jungiklius ir atsargius numatytuosius nustatymus apkrovesniems apdorojimo srautams; papildomų minimalių OS ar įrenginio modelio reikalavimų nėra, tik paketo iOS 16 diegimo tikslas. SDK platinamas per Swift Package Manager, o vienas Kixo.configure iškvietimas automatiškai įjungia ekranų, bakstelėjimų, sesijų, strigčių, push pranešimų ir gyvavimo ciklo įvykių sekimą. Tinklo užklausų sekimas yra pasirenkamas.

Diegimas

Swift Package Manager

Xcode atidarykite File → Add Package Dependencies ir įveskite:

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

Jei priklausomybes valdote per Package.swift, naudokite dvejetainį leidimo paketą ir produktą:

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

Konfigūruoti

Inicijuokite Kixo savo SwiftUI App struktūroje arba AppDelegate:

import Kixo

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

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

Konfigūravimo parinktys

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

Automatiškai sekami įvykiai

• screen_view — momentiniai UIKit view-controller parodymai ir SwiftUI navigacija
• screen_visit — struktūruotas apsilankymas, užbaigiamas pereinant kitur arba programai persikėlus į foną; apima buvimo trukmę, įsitraukimo skaitiklius, ekrano tapatybę ir srauto metaduomenis
• session_start / session_end
• tap — mygtukų bakstelėjimai ir gestų atpažinimo įvykiai
• crash — užfiksuota strigčių ir išimčių diagnostika
• network — pasirenkamos išvalytos užklausų suvestinės ir maršrutų diagnostika
• push_received / push_open / push_dismissed / push_silent / push_action — visas push gyvavimo ciklas
• push_permission / push_token_invalidated
• lifecycle — perėjimai tarp foreground / background / app-launch būsenų

Pasirinktiniai įvykiai

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

Tipizuoti įvykių pagalbiniai metodai

Patogesnis Kixo.track apvalkalas įvykiams, kuriuos Kixo atpažįsta pagal pavadinimą (purchase, signup, subscribe_start, trial_start, cancel, upgrade, activation, share, invite). Savybių struktūra tikrinama kompiliavimo metu, o raktų pavadinimai apibrėžiami vienoje vietoje — standartinių įvykių atpažinimas serveryje remiasi tiksliu atitikimu.

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)

Identifikuokite naudotojus

Rezervuoti standartinių savybių raktai turi $ prefiksą (Mixpanel konvencija), todėl nesikerta su jūsų pasirinktiniais požymiais ir patenka į suvestinės profilio stulpelius. Naudokite tipizuotą StandardProperty enum arba neapdorotą eilutę su $ prefiksu — visą 37 raktų sąrašą rasite toliau, skiltyje Standartinių savybių katalogas.

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

Pažymėkite naudotoją segmentavimui

Naudokite setUserProperty su boolean reikšme, jei naudotojui norite priskirti paprastą taip / ne žymą. Ji išlieka per visas sesijas ir naudojama segmentams, el. pašto kampanijoms bei pokalbio užklausoms — nieko daugiau nei SDK iškvietimo nereikia.

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

Savybės išsaugomos UserDefaults tarp paleidimų ir automatiškai pridedamos prie kiekvieno išsiunčiamo įvykio. Kixo Chat galite rašyti, pavyzdžiui, "išsiųsti pasveikinimo el. laišką naudotojams, kurių subscribe yra true" — Kixo sukurs segmentą ir parengs šablono juodraštį. Išvalomos per Kixo.reset().

Standartinių savybių katalogas

Rezervuoti savybių raktai turi $ prefiksą, todėl nesikerta su jūsų pasirinktiniais požymiais. Kixo kataloge yra 37 raktai: 3 universalūs paketai (tapatybė, geografiniai duomenys, gyvavimo ciklas) ir 5 B2B sritiniai paketai (prenumerata, e. prekyba, medija, prekyvietė, lojalumas). Pildykite tik tai, kas tinka jūsų produktui — suvestinė prisitaikys ir rodys tik tuos paketus, kuriuos naudojate.

Tapatybė

Visada aktualu. Nustato profilio antraštės stulpelius.

Geo

Geografinis kontekstas.

Gyvavimo ciklas

Kada juos matėme.

Prenumerata

Nurodykite, jei jūsų produktas turi planus.

El. prekyba

Nurodykite, jei parduodate produktus.

Medija

Nurodykite, jei publikuojate turinį.

Prekyvietė

Nurodykite, jei jūsų platforma jungia dvi puses.

Lojalumas

Nurodykite, jei naudojate įsitraukimo ar lojalumo programas.

Super-properties

Sesijos lygmens rakto ir reikšmės poros, automatiškai pridedamos prie kiekvieno išsiunčiamo įvykio. Skirtingai nei identify požymiai, kurie aprašo tapatybę, super-properties aprašo sesijos kontekstą — aktyvų A/B variantą, build flavor ir įjungtas funkcijų vėliavėles. Išsaugomos UserDefaults tarp paleidimų; išvalomos per reset(). Jei raktai sutampa, įvykio lygmens properties iš track visada turi pirmenybę.

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 ekranų sekimas

SwiftUI ekranų peržiūros sekamos automatiškai, kai SDK gali nustatyti rodinio pavadinimą. Jei reikia tikslesnio valdymo arba pasirinktinių pavadinimų, naudokite .kixoScreen() rodinio modifikatorių:

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

Sesijos atkūrimas

Replay atkuria tai, ką naudotojas iš tikrųjų matė — SDK fiksuoja ekrano kadrus pikselių lygiu (HEIC formatu) kartu su struktūrine rodinių hierarchijos momentine kopija, o suvestinės grotuvas juos sujungia į prasukamą peržiūrą šalia įvykių laiko juostos. Projekto replay nustatymus konfigūruokite Valdymo skydelis → Nustatymai → Sesijų atkūrimas; SDK šią politiką nuskaito automatiškai ir atnaujina programai veikiant.

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

Suvestinėje nustatoma, ar replay įjungtas, kaip taikomas maskavimas, kokie naudojami fiksavimo režimai ir ar vietinis replay gali siųsti duomenis per mobilųjį ryšį. Jei siuntimas per mobilųjį ryšį išjungtas, kadrai vis tiek gali būti kaupiami riboto dydžio įrenginio buferyje; įkėlimas palaukiamas, kol atsiras leidžiamas tinklas.

SDK fiksuoja projekte įjungtus duomenis, taip pat įvykius ir savybes, kurias siunčia jūsų programa.

Maskavimas ir privatumas

Kadangi atkūrimas fiksuoja pikselius, užmaskavimas įvyksta įrenginyje prieš prieš užkoduojant bent vieną kadrą. Slaptažodžiai ir kiti jautrūs laukai aptinkami ir užmaskuojami automatiškai, o į struktūrinę momentinę kopiją patenkantis tekstas papildomai filtruojamas pagal PII. Jei norite užmaskuoti ką nors savo — privačių žinučių giją, sąskaitos likutį ar juodraščio ekraną — nustatykite kxRedact tam rodiniui. Kixo prieš HEIC kodavimą uždengia to rodinio ribas vientisu stačiakampiu, todėl jo pikseliai niekada nepalieka įrenginio.

balanceLabel.kxRedact = true
cardNumberField.kxRedact = true

Push pranešimai

SDK vykdymo metu įdiegia AppDelegate proxy į Kixo.configure — tylieji push (content-available: 1) ir fone pristatyti matomi push pranešimai užfiksuojami automatiškai. Jokio papildomo kodo jūsų AppDelegate nereikia. Esamos UNUserNotificationCenterDelegate implementacijos ir toliau veikia įprastai; Kixo jas tik apgaubia.

Užregistruokite įrenginio raktą per standartinį didRegisterForRemoteNotificationsWithDeviceToken:

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

Jei programa naudoja Firebase Messaging, perduokite jos registracijos raktą per provider: .firebase. Kixo išsaugos tą teikėją ir pristatys pranešimus per FCM HTTP v1; prieš siųsdami kampanijas Kixo aplinkoje sukonfigūruokite programos Firebase service account.

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

Pristatymas ir veikimas neprisijungus

SDK lokaliai kaupia įvykių eilę, siunčia juos paketais ir laikinų klaidų atveju kartoja siuntimą su ilgėjančiomis pauzėmis. Jei rinkimas pristabdytas projekto nustatymuose, nauji įvykiai nebus siunčiami, kol rinkimas vėl nebus įjungtas.

Diagnostika

Tik skaitoma būsenos suvestinė. Naudinga derinimo ekranuose ar smoke testuose — be derintuvo atsako į klausimą „kodėl įvykiai nekeliauja?“.

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

Priverstinai išsiųsti (testams)

Sinchroninis variantas, kuris blokuoja iki timeout sekundžių, kol baigiamas flush. Skirta XCTest scenarijams — niekada nekvieskite iš pagrindinės gijos.

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

Atkurti pradinę būseną

Išvalykite tapatybę, super-properties ir išsaugotą eilę. Kvieskite atsijungiant, kad vėlesni įvykiai nebūtų priskirti ankstesniam naudotojui.

Kixo.reset()