iOS SDK

Kixo iOS SDK podpira Swift 5.9+ in iOS 16+ za analitiko, atribucijo, potisna obvestila, sledenje življenjskemu ciklu in replay sej. Replay uporablja projektna stikala za zajem in zadržane privzete nastavitve za zahtevnejše cevovode; poleg ciljne različice iOS 16, določene v paketu, ne uvaja dodatne spodnje meje za OS ali modele naprav. SDK se distribuira prek Swift Package Managerja in z enim klicem Kixo.configure samodejno beleži zaslone, dotike, seje, zrušitve, potisna obvestila in dogodke življenjskega cikla. Sledenje omrežnim zahtevam je izbirno.

Namestitev

Swift Package Manager

V Xcode odprite File → Add Package Dependencies in vnesite:

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

Če odvisnosti upravljate v Package.swift, uporabite binarni paket izdaje in izdelek:

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

Nastavite

Kixo inicializirajte v svoji strukturi SwiftUI App ali v AppDelegate:

import Kixo

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

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

Možnosti konfiguracije

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

Samodejno zabeleženi dogodki

• screen_view — takojšnji prikazi krmilnikov pogledov v UIKit + navigacija v SwiftUI
• screen_visit — strukturiran obisk, zaključen ob navigaciji ali prehodu v ozadje, z metrikami zadrževanja, števci angažiranosti, identiteto zaslona in metapodatki toka
• session_start / session_end
• tap — dotiki gumbov in prepoznava potez
• crash — zajeta diagnostika zrušitev in izjem
• network — izbirni očiščeni agregati zahtevkov in diagnostika poti
• push_received / push_open / push_dismissed / push_silent / push_action — celoten življenjski cikel potisnih obvestil
• push_permission / push_token_invalidated
• lifecycle — prehodi v ospredje / ozadje / zagon aplikacije

Dogodki po meri

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

Tipizirani pomočniki za dogodke

Priročna plast nad Kixo.track za dogodke, ki jih Kixo prepozna po imenu (purchase, signup, subscribe_start, trial_start, cancel, upgrade, activation, share, invite). Oblika lastnosti se preveri že med prevajanjem, imena ključev pa so določena na enem mestu — detektor standardnih dogodkov v zaledju se ujema dobesedno.

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)

Identificirajte uporabnike

Rezervirani ključi standardnih lastnosti imajo predpono $ (konvencija Mixpanel), zato so ločeni od vaših lastnih lastnosti po meri in se prikažejo v stolpcih profila na nadzorni plošči. Uporabite tipizirani enum StandardProperty ali surov niz s predpono $ — spodaj v Katalog standardnih lastnosti je celoten seznam 37 ključev.

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

Označite uporabnika za segmentacijo

Uporabite setUserProperty z vrednostjo logična vrednost, da uporabniku dodate preprosto oznako da/ne. Oznaka se ohrani med sejami in se uporablja v segmentih, e-poštnih kampanjah ter poizvedbah v klepetu — brez dodatnih nastavitev, samo s klicem 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",
])

Lastnosti se med zagoni hranijo v UserDefaults in se samodejno pripnejo vsakemu poslanemu dogodku. V Kixo Chat lahko rečete na primer "pošlji pozdravno e-pošto uporabnikom, pri katerih je subscribe nastavljen na true" — Kixo za vas sestavi segment in pripravi osnutek predloge. Izbrišejo se ob Kixo.reset().

Katalog standardnih lastnosti

Rezervirani ključi lastnosti imajo predpono $, zato so ločeni od vaših lastnosti po meri. Kixo vključuje 37 ključev v 3 univerzalnih paketih (identiteta, geo, življenjski cikel) in 5 B2B vertikalnih paketih (naročnine, e-trgovina, mediji, tržnica, zvestoba). Nastavite samo tiste, ki veljajo za vaš izdelek — nadzorna plošča se prilagodi in prikaže le pakete, ki jih uporabljate.

Identiteta

Vedno relevantno. Določa stolpce v glavi profila.

Geo

Geografski kontekst.

Življenjski cikel

Kdaj smo ga zaznali.

Naročnina

Nastavite, če ima vaš izdelek pakete.

E-trgovina

Nastavite, če prodajate izdelke.

Mediji

Nastavite, če objavljate vsebine.

Tržnica

Nastavite, če je vaš izdelek dvostranska platforma.

Zvestoba

Nastavite, če uporabljate programe angažiranja in nagrajevanja.

Superlastnosti

Pari ključ–vrednost na ravni seje, ki se samodejno pripnejo vsakemu poslanemu dogodku. Za razliko od lastnosti identify, ki opisujejo identiteto, superlastnosti opisujejo kontekst seje — aktivno različico A/B, različico gradnje in vključene zastavice funkcij. Med zagoni se hranijo v UserDefaults; izbrišejo se ob reset(). Ob trku imajo vedno prednost lastnosti posameznega dogodka properties v 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()

Sledenje zaslonom v SwiftUI

Ogledi zaslonov v SwiftUI se beležijo samodejno, kadar SDK lahko razbere ime pogleda. Če želite natančnejši nadzor ali ime po meri, uporabite modifikator pogleda .kixoScreen():

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

Posnetek seje

Replay rekonstruira, kaj je uporabnik dejansko videl — SDK zajame slikovne sličice zaslona, kodirane v HEIC, skupaj s strukturnim posnetkom hierarhije pogledov, predvajalnik v nadzorni plošči pa jih sestavi v predvajanje, po katerem se lahko premikate, ob časovnici dogodkov. Replay za projekt nastavite v Nadzorna plošča → Nastavitve → Posnetki sej; SDK to pravilo samodejno prebere in ga osvežuje med delovanjem aplikacije.

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

Na nadzorni plošči določite, ali je replay vklopljen, kako se izvaja maskiranje, katere načine zajema uporabljate in ali sme izvorni replay nalagati podatke prek mobilnega omrežja. Če je nalaganje prek mobilnega omrežja izklopljeno, se sličice še vedno lahko zajemajo v omejen medpomnilnik v napravi; prenos počaka na dovoljeno omrežje.

SDK zajame podatke, ki so v vašem projektu omogočeni, ter dogodke in lastnosti, ki jih pošilja aplikacija.

Maskiranje in zasebnost

Ker replay zajema slikovne pike, se zakrivanje izvede na napravi preden se sploh kodira katera koli sličica. Gesla in druga občutljiva polja se samodejno prepoznajo in zakrijejo, besedilo, zajeto v strukturni posnetek, pa gre skozi filter PII. Če želite zakriti karkoli po meri — zasebno nit sporočil, stanje računa ali zaslon osnutka — na pogled nastavite kxRedact. Kixo pred kodiranjem HEIC čez meje tega pogleda izriše poln pravokotnik, zato njegove slikovne pike nikoli ne zapustijo naprave.

balanceLabel.kxRedact = true
cardNumberField.kxRedact = true

Potisna obvestila

SDK med izvajanjem namesti posredniški AppDelegate na Kixo.configure — tihi pushi (content-available: 1) in vidna obvestila, dostavljena v ozadju, se zajamejo samodejno. V AppDelegate ni treba dodati nobene kode. Obstoječe implementacije UNUserNotificationCenterDelegate še naprej delujejo normalno; Kixo jih samo ovije.

Žeton naprave registrirajte prek standardnega didRegisterForRemoteNotificationsWithDeviceToken:

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

Če aplikacija uporablja Firebase Messaging, posredujte njegov registracijski žeton z provider: .firebase. Kixo shrani tega ponudnika in dostavlja prek FCM HTTP v1; pred pošiljanjem kampanj v Kixo nastavite račun storitve Firebase za aplikacijo.

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

Pošiljanje in delovanje brez povezave

SDK dogodke lokalno postavi v vrsto, jih pošilja v paketih in pri prehodnih napakah poskuse ponavlja z odlogom. Če je zbiranje v nastavitvah projekta začasno ustavljeno, se novi dogodki ne pošiljajo, dokler zbiranja znova ne omogočite.

Diagnostika

Posnetek stanja samo za branje. Uporaben na razhroščevalnih zaslonih ali pri hitrih preverjanjih — brez razhroščevalnika odgovori na vprašanje »zakaj moji dogodki ne prihajajo?«.

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

Prisilno pošiljanje (za teste)

Sinhrona preobremenitev, ki čaka največ timeout sekund, da se pošiljanje zaključi. Namenjena je ogrodju XCTest — nikoli je ne kličite z glavne niti.

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

Ponastavi

Počisti identiteto, superlastnosti in shranjeno vrsto. Pokličite ob odjavi, da se naslednji dogodki ne pripišejo prejšnjemu uporabniku.

Kixo.reset()