iOS SDK

Kixo iOS SDK tukee analytiikkaa, attribuutiota, push-ilmoituksia, elinkaaren seurantaa ja istuntotoistoa ympäristöissä Swift 5.9+ ja iOS 16+. Replay hyödyntää projektitason tallennuskytkimiä ja varovaisia oletuksia raskaammissa käsittelyketjuissa, eikä se vaadi paketin iOS 16 -deployment targetin lisäksi erillistä OS- tai laitemallirajaa. SDK jaetaan Swift Package Managerin kautta, ja yhdellä Kixo.configure-kutsulla saat automaattisesti seurannan näytöille, napautuksille, istunnoille, kaatumisille, push-ilmoituksille ja elinkaaritapahtumille. Verkkopyyntöjen seuranta otetaan käyttöön erikseen.

Asennus

Swift Package Manager

Siirry Xcodessa kohtaan File → Add Package Dependencies ja kirjoita:

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

Jos hallitset riippuvuuksia työkalulla Package.swift, käytä binäärijulkaisun pakettia ja productia:

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

Määritä

Alusta Kixo SwiftUI:n App-rakenteessa tai kohdassa AppDelegate:

import Kixo

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

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

Määritysasetukset

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

Automaattisesti seuratut tapahtumat

• screen_view — välittömät UIKit-näkymäohjainten avautumiset sekä SwiftUI-navigointi
• screen_visit — rakenteinen käynti, joka päättyy navigointiin tai taustalle siirtymiseen ja sisältää viipymän, sitoutumismäärät, näkymän tunnisteen ja kulun metatiedot
• session_start / session_end
• tap — painikenapautukset ja eleentunnistimet
• crash — talteen otettu kaatumis- ja poikkeusdiagnostiikka
• network — valinnaiset puhdistetut pyyntökoosteet ja reittidiagnostiikka
• push_received / push_open / push_dismissed / push_silent / push_action — push-ilmoituksen koko elinkaari
• push_permission / push_token_invalidated
• lifecycle — siirtymät foreground-, background- ja app-launch-tilojen välillä

Mukautetut tapahtumat

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

Tyypitetyt tapahtuma-apurit

Kevyt kerros Kixo.track:n päälle tapahtumille, jotka Kixo tunnistaa nimeltä (purchase, signup, subscribe_start, trial_start, cancel, upgrade, activation, share, invite). Ominaisuuksien muoto tarkistetaan käännösaikana, avainnimille on yksi totuuden lähde, ja backendin vakiotapahtumien tunnistin vertaa nimiä täsmälleen sellaisinaan.

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)

Tunnista käyttäjät

Varatut vakio-ominaisuusavaimet käyttävät etuliitettä $ (Mixpanel-käytäntö), jotta ne pysyvät erillään omista mukautetuista traitseistasi ja nousevat dashboardin profiilisarakkeisiin. Käytä tyypitettyä StandardProperty-enumia tai suoraan $-etuliitteistä merkkijonoa — täydellinen 37 avaimen lista on alempana kohdassa Vakio-ominaisuuksien luettelo.

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

Merkitse käyttäjä segmentointia varten

Käytä setUserProperty-kutsua totuusarvo-arvolla, kun haluat liittää käyttäjään yksinkertaisen kyllä/ei-tunnisteen. Tunniste säilyy istuntojen yli ja toimii segmentoinnin, sähköpostikampanjoiden ja chat-kyselyiden pohjana — muuta kuin SDK-kutsu ei tarvita.

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

Ominaisuudet säilyvät UserDefaults:ssä käynnistysten yli ja liitetään automaattisesti jokaiseen lähtevään tapahtumaan. Kirjoita chatissa esimerkiksi "lähetä tervetulosähköposti käyttäjille, joilla subscribe on true" — Kixo muodostaa segmentin ja luonnostelee viestipohjan puolestasi. Ne tyhjennetään komennolla Kixo.reset().

Vakio-ominaisuuksien luettelo

Varatut ominaisuusavaimet saavat etuliitteen $, jotta ne pysyvät erillään omista mukautetuista ominaisuuksistasi. Kixon luettelossa on 37 avainta 3 yleisessä paketissa (identiteetti, sijainti, elinkaari) ja 5 B2B-vertikaalipaketissa (tilaus, verkkokauppa, media, markkinapaikka, kanta-asiakkuus). Ota käyttöön tuotteellesi olennaiset paketit — dashboard mukautuu ja näyttää vain ne, joihin tuot dataa.

Identiteetti

Aina relevantti. Määrittää profiiliotsikon sarakkeet.

Sijainti

Maantieteellinen konteksti.

Elinkaari

Milloin näimme hänet.

Tilaus

Aseta tämä, jos tuotteessasi on palvelupaketteja.

Verkkokauppa

Aseta tämä, jos myyt tuotteita.

Media

Aseta tämä, jos julkaiset sisältöä.

Markkinapaikka

Aseta tämä, jos tuotteesi on kaksipuolinen alusta.

Kanta-asiakkuus

Aseta tämä, jos käytössäsi on sitouttamis- tai palkitsemisohjelmia.

Super-properties

Istuntokohtaiset avain–arvo-parit, jotka liitetään automaattisesti jokaiseen lähtevään tapahtumaan. Ne eroavat identify-traiteista, jotka kuvaavat identiteettiä; super-properties kuvaavat istunnon kontekstia, kuten aktiivista A/B-varianttia, build flavoria tai käyttöön otettuja feature flageja. Ne säilyvät UserDefaults:ssä käynnistysten yli ja tyhjennetään komennolla reset(). Tapahtumakohtaiset properties-arvot kutsussa track voittavat aina ristiriitatilanteessa.

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-näyttöseuranta

SwiftUI-näyttönäkymät seurataan automaattisesti, kun SDK pystyy päättelemään näkymän nimen. Jos tarvitset tarkempaa hallintaa tai omia nimiä, käytä .kixoScreen()-view modifieria:

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

Istunnon toisto

Replay rakentaa uudelleen sen, mitä käyttäjä oikeasti näki: SDK tallentaa näytöltä pikseliruutuja HEIC-muodossa sekä rakenteellisen tilannekuvan näkymähierarkiasta, ja dashboardin soitin yhdistää ne kelattavaksi toistoksi tapahtuma-aikajanan rinnalle. Määritä projektin replay-asetukset kohdassa Hallintapaneeli → Asetukset → Istunnon tallenne; SDK lukee tämän käytännön automaattisesti ja päivittää sen sovelluksen käytön aikana.

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

Dashboardissa määritetään, onko replay käytössä, peittäminen, tallennustilat ja saako natiivi replay lähettää dataa mobiiliverkon yli. Jos lähetys mobiiliverkon yli on poistettu käytöstä, ruutuja voidaan silti tallentaa laitteella rajattuun puskuriin; lähetys odottaa sallittua verkkoyhteyttä.

SDK kerää projektissasi käyttöön otetut tiedot sekä sovelluksesi lähettämät tapahtumat ja ominaisuudet.

Peittäminen ja tietosuoja

Koska replay tallentaa pikseleitä, peittäminen tehdään laitteella ennen kuin yksikään ruutu koodataan. Salasanat ja muut arkaluonteiset kentät tunnistetaan ja peitetään automaattisesti, ja rakenteelliseen tilannekuvaan tallennettu teksti kulkee PII-suodattimen läpi. Jos haluat peittää jotain omaa — yksityisen viestiketjun, tilin saldon tai luonnosnäkymän — aseta näkymälle kxRedact. Kixo rasteroi ennen HEIC-koodausta näkymän rajojen päälle yhtenäisen suorakulmion, joten sen pikselit eivät koskaan poistu laitteelta.

balanceLabel.kxRedact = true
cardNumberField.kxRedact = true

Push-ilmoitukset

SDK asentaa ajonaikaisen AppDelegate-välityksen kohtaan Kixo.configure — hiljaiset pushit (content-available: 1) ja taustalla toimitetut näkyvät pushit tallentuvat automaattisesti. AppDelegateen ei tarvitse lisätä koodia. Olemassa olevat UNUserNotificationCenterDelegate-toteutukset toimivat normaalisti; Kixo vain kytkeytyy niiden ympärille.

Rekisteröi laitteen token tavalliseen tapaan didRegisterForRemoteNotificationsWithDeviceToken:

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

Jos sovellus käyttää Firebase Messagingia, välitä sen rekisteröintitunnus metodilla provider: .firebase. Kixo tallentaa tämän palveluntarjoajan ja toimittaa viestit FCM HTTP v1:n kautta; määritä sovelluksen Firebase service account Kixossa ennen kampanjoiden lähettämistä.

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

Lähetys ja toiminta offline-tilassa

SDK jonottaa tapahtumat paikallisesti, lähettää ne erissä ja yrittää tilapäiset virheet uudelleen kasvavalla viiveellä. Jos keruu keskeytetään projektiasetuksista, uusia tapahtumia ei lähetetä ennen kuin keruu otetaan taas käyttöön.

Diagnostiikka

Vain luku -tilannekuva järjestelmän tilasta. Hyödyllinen debug-näkymissä ja smoke-testeissä — kertoo ilman debuggeria, miksi tapahtumat eivät kulje.

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

Pakota lähetys (testejä varten)

Synkroninen overload, joka odottaa flushin valmistumista enintään timeout sekuntia. Tarkoitettu XCTest-fixtureihin — älä koskaan kutsu pääsäikeestä.

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

Tyhjennä

Tyhjennä identiteetti, super-properties ja pysyvä jono. Kutsu tätä uloskirjautumisen yhteydessä, jotta seuraavia tapahtumia ei kohdisteta edelliselle käyttäjälle.

Kixo.reset()