iOS SDK

Kixo iOS SDK atbalsta Swift 5.9+ un iOS 16+ analītikai, atribūcijai, push paziņojumiem, dzīvescikla izsekošanai un sesiju atkārtošanai. Replay izmanto projekta līmeņa tveršanas slēdžus un piesardzīgus noklusējumus resursietilpīgākajām plūsmām; tam nav atsevišķu minimālo prasību ne attiecībā uz OS, ne ierīču modeļiem ārpus pakotnes iOS 16 deployment target. SDK tiek izplatīts caur Swift Package Manager un ar vienu Kixo.configure izsaukumu automātiski izseko ekrānus, pieskārienus, sesijas, avārijas, push paziņojumus un dzīvescikla notikumus. Tīkla pieprasījumu izsekošana ir izvēles iespēja.

Instalācija

Swift Package Manager

Xcode atveriet File → Add Package Dependencies un ievadiet:

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

Ja atkarības pārvaldāt ar Package.swift, izmantojiet bināro release pakotni un produktu:

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

Konfigurēt

Inicializējiet Kixo savā SwiftUI struktūrā App vai AppDelegate:

import Kixo

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

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

Konfigurācijas opcijas

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

Automātiski izsekoti notikumi

• screen_view — tūlītēja UIKit view-controller parādīšanās un SwiftUI navigācija
• screen_visit — strukturēts apmeklējums, kas tiek noslēgts navigācijas vai fona režīma brīdī un ietver uzturēšanās ilgumu, iesaistes skaitītājus, ekrāna identitāti un plūsmas metadatus
• session_start / session_end
• tap — pogu pieskārieni un žestu atpazīšana
• crash — fiksēta avāriju un izņēmumu diagnostika
• network — izvēles sanitizēti pieprasījumu apkopojumi un maršrutu diagnostika
• push_received / push_open / push_dismissed / push_silent / push_action — pilns push paziņojumu dzīves cikls
• push_permission / push_token_invalidated
• lifecycle — pārejas starp foreground / background / app-launch

Pielāgoti notikumi

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

Tipizēti notikumu palīgi

Ērtāka kārta virs Kixo.track notikumiem, kurus Kixo atpazīst pēc nosaukuma (purchase, signup, subscribe_start, trial_start, cancel, upgrade, activation, share, invite). Īpašību struktūras pārbaude kompilēšanas laikā un viens patiesības avots atslēgu nosaukumiem — backend standarta notikumu detektors salīdzina burtiski.

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)

Identificēt lietotājus

Rezervētajām standarta īpašību atslēgām ir prefikss $ (Mixpanel konvencija), lai tās nepārklātos ar jūsu pielāgotajām pazīmēm un tiktu parādītas paneļa profila kolonnās. Izmantojiet tipizēto StandardProperty enum vai neapstrādātu virkni ar prefiksu $ — pilnu 37 atslēgu sarakstu skatiet zemāk sadaļā Standarta īpašību katalogs.

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

Atzīmēt lietotāju segmentēšanai

Izmantojiet setUserProperty ar boolean vērtību, lai lietotājam pievienotu vienkāršu jā/nē atzīmi. Tā saglabājas starp sesijām un tiek izmantota segmentos, e-pasta kampaņās un čata vaicājumos — nekas nav jākonfigurē ārpus SDK izsaukuma.

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

Īpašības tiek saglabātas UserDefaults arī starp lietotnes palaišanas reizēm un automātiski pievienotas katram izejošajam notikumam. Čatā varat rakstīt, piemēram, "nosūti sagaidīšanas e-pastu lietotājiem, kuriem subscribe ir true" — Kixo izveidos segmentu un sagatavos veidnes melnrakstu. Notīrās ar Kixo.reset().

Standarta īpašību katalogs

Rezervētajām īpašību atslēgām ir prefikss $, lai tās nepārklātos ar jūsu pielāgotajām pazīmēm. Kixo katalogā ir 37 atslēgas 3 universālās pakās (identitāte, ģeogrāfija, dzīves cikls) un 5 B2B vertikālajās pakās (abonementi, e-komercija, mediji, tirdzniecības platformas, lojalitāte). Norādiet tikai tās, kas attiecas uz jūsu produktu — panelis pielāgosies un rādīs tikai aizpildītās pakas.

Identitāte

Vienmēr aktuāli. Nosaka profila galvenes kolonnas.

Geo

Ģeogrāfiskais konteksts.

Dzīves cikls

Kad mēs viņu redzējām.

Abonementi

Iestatiet, ja jūsu produktam ir plāni.

E-komercija

Iestatiet, ja pārdodat preces.

Mediji

Iestatiet, ja publicējat saturu.

Tirdzniecības platforma

Iestatiet, ja jūsu produkts ir divpusēja platforma.

Lojalitāte

Iestatiet, ja izmantojat iesaistes vai atlīdzību programmas.

Super-properties

Sesijas atslēgu/vērtību pāri, ko automātiski pievieno katram izejošajam notikumam. Tie atšķiras no identify pazīmēm, kas raksturo identitāti; super-properties raksturo sesijas kontekstu — aktīvo A/B variantu, būvējuma veidu un ieslēgtos feature flags. Tie tiek saglabāti UserDefaults arī starp lietotnes palaišanas reizēm un notīrīti ar reset(). Ja rodas kolīzija, vienmēr virsroku ņem notikuma līmeņa properties parametrā 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()

SwiftUI ekrānu izsekošana

SwiftUI ekrānu skatījumi tiek izsekoti automātiski, ja SDK var noteikt skata nosaukumu. Precīzākai kontrolei vai pielāgotiem nosaukumiem izmantojiet skata modifikatoru .kixoScreen():

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

Sesiju ieraksts

Replay atjauno to, ko lietotājs tiešām redzēja — SDK uztver ekrāna pikseļu kadrus (kodētus HEIC formātā) kopā ar skatu hierarhijas strukturālu momentuzņēmumu, un paneļa atskaņotājs tos saliek pārtinamā atskaņojumā līdzās notikumu laika skalai. Konfigurējiet replay projektam sadaļā Pārskats → Iestatījumi → Sesiju atkārtojums; SDK šo politiku nolasa automātiski un atjauno arī lietotnes darbības laikā.

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

Panelis nosaka, vai replay ir ieslēgts, kāda maskēšana tiek lietota, kādi ir tveršanas režīmi un vai vietējais replay drīkst augšupielādēt datus mobilajā tīklā. Ja augšupielāde mobilajā tīklā ir izslēgta, kadrus joprojām var uztvert ierobežotā ierīces buferī; augšupielāde gaidīs atļautu tīklu.

SDK tver jūsu projektā ieslēgtos datus, kā arī notikumus un īpašības, ko nosūta lietotne.

Maskēšana un privātums

Tā kā replay uztver pikseļus, aizklāšana notiek ierīcē jau pirms, pirms tiek iekodēts kaut viens kadrs. Paroles un citi sensitīvi lauki tiek automātiski atpazīti un aizklāti, bet strukturālajā momentuzņēmumā uztvertais teksts iziet cauri PII filtram. Ja jāaizklāj kas pielāgots — privāta sarakste, konta atlikums vai melnraksta ekrāns — iestatiet skatam kxRedact. Kixo pirms HEIC kodēšanas pārklāj šī skata robežās vienkrāsainu taisnstūri, tāpēc tā pikseļi nekad nepamet ierīci.

balanceLabel.kxRedact = true
cardNumberField.kxRedact = true

Push paziņojumi

SDK uz Kixo.configure uzstāda AppDelegate starpniekobjektu izpildlaikā — klusie push (content-available: 1) un fonā piegādātie redzamie push tiek uztverti automātiski. AppDelegate nav jāpievieno nekāds kods. Esošās UNUserNotificationCenterDelegate implementācijas turpina izpildīties kā parasti; Kixo tās tikai aptin.

Reģistrējiet ierīces tokenu ar standarta didRegisterForRemoteNotificationsWithDeviceToken:

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

Ja lietotne izmanto Firebase Messaging, nododiet tās reģistrācijas tokenu ar provider: .firebase. Kixo saglabā šo pakalpojumu sniedzēju un piegādā ziņojumus caur FCM HTTP v1; pirms kampaņu sūtīšanas konfigurējiet lietotnes Firebase servisa kontu Kixo.

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

Piegāde un darbība bezsaistē

SDK lokāli saliek notikumus rindā, sūta tos paketēs un pārejošu kļūmju gadījumā mēģina atkārtoti ar pieaugošu pauzi. Ja datu vākšana ir apturēta projekta iestatījumos, jaunie notikumi netiek sūtīti, līdz vākšana atkal tiek ieslēgta.

Diagnostika

Tikai lasāms veselības stāvokļa momentuzņēmums. Noder atkļūdošanas ekrānos vai smoke testos — atbild uz jautājumu “kāpēc mani notikumi netiek sūtīti?” bez atkļūdotāja.

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

Piespiedu nosūtīšana (testiem)

Sinhrons overload, kas bloķē līdz timeout sekundēm, kamēr pabeidzas flush. Paredzēts XCTest fixture vajadzībām — nekad neizsauciet no galvenā pavediena.

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

Atiestatīt

Notīra identitāti, super-properties un saglabāto rindu. Izsauciet to pie izrakstīšanās, lai nākamie notikumi netiktu piesaistīti iepriekšējam lietotājam.

Kixo.reset()