iOS SDK

Kixo iOS SDK obsługuje Swift 5.9+ i iOS 16+ oraz zapewnia analitykę, atrybucję, push, śledzenie cyklu życia i odtwarzanie sesji. Odtwarzanie korzysta z przełączników przechwytywania ustawianych na poziomie projektu i z ostrożnych ustawień domyślnych dla bardziej obciążających ścieżek przetwarzania; poza docelowym iOS 16 pakiet nie narzuca wyższej wersji OS ani konkretnego modelu urządzenia. SDK jest dystrybuowane przez Swift Package Manager i po pojedynczym wywołaniu Kixo.configure automatycznie śledzi ekrany, stuknięcia, sesje, awarie, powiadomienia push i zdarzenia cyklu życia. Śledzenie żądań sieciowych jest opcjonalne.

Instalacja

Swift Package Manager

W Xcode przejdź do File → Add Package Dependencies i wpisz:

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

Jeśli zarządzasz zależnościami w Package.swift, użyj binarnego pakietu release i tego 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"),
        ]
    )
]

Skonfiguruj

Zainicjalizuj Kixo w strukturze SwiftUI App albo w AppDelegate:

import Kixo

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

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

Opcje konfiguracji

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

Zdarzenia śledzone automatycznie

• screen_view — natychmiastowe pojawienia się kontrolerów widoku UIKit oraz nawigacja SwiftUI
• screen_visit — ustrukturyzowana wizyta zamykana przy nawigacji lub przejściu aplikacji w tło; zawiera czas trwania, liczniki zaangażowania, identyfikator ekranu i metadane przepływu
• session_start / session_end
• tap — stuknięcia przycisków i rozpoznane gesty
• crash — przechwycone dane diagnostyczne awarii i wyjątków
• network — opcjonalne oczyszczone agregaty żądań i diagnostyka tras
• push_received / push_open / push_dismissed / push_silent / push_action — pełny cykl życia powiadomień push
• push_permission / push_token_invalidated
• lifecycle — przejścia między foreground, background i uruchomieniem aplikacji

Zdarzenia niestandardowe

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

Typowane helpery zdarzeń

Wygodna nakładka na Kixo.track dla zdarzeń, które Kixo rozpoznaje po nazwie (purchase, signup, subscribe_start, trial_start, cancel, upgrade, activation, share, invite). Daje walidację kształtu właściwości na etapie kompilacji i jedno źródło prawdy dla nazw kluczy — detektor zdarzeń standardowych po stronie backendu dopasowuje je dosłownie.

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)

Identyfikuj użytkowników

Zarezerwowane standardowe klucze właściwości mają prefiks $ (zgodnie z konwencją Mixpanel), więc nie kolidują z własnymi cechami i trafiają do kolumn profilu w dashboardzie. Użyj typowanego enumu StandardProperty albo bezpośrednio ciągu z prefiksem $ — pełną listę 37 kluczy znajdziesz niżej w Katalog standardowych właściwości.

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

Oznacz użytkownika na potrzeby segmentacji

Użyj setUserProperty z wartością wartość logiczna, aby przypisać użytkownikowi prostą flagę tak/nie. Flaga jest zachowywana między sesjami i zasila segmenty, kampanie e-mail oraz zapytania w Kixo Chat — bez żadnej dodatkowej konfiguracji poza wywołaniem 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",
])

Właściwości są przechowywane w UserDefaults między uruchomieniami i automatycznie dołączane do każdego wysyłanego zdarzenia. W czacie wpisuj polecenia w stylu "wyślij powitalny e-mail do użytkowników, gdzie subscribe ma wartość true" — Kixo sam zbuduje segment i przygotuje szkic szablonu. Czyszczone przy Kixo.reset().

Katalog standardowych właściwości

Zarezerwowane klucze właściwości mają prefiks $, więc nie kolidują z własnymi cechami. Katalog Kixo obejmuje 37 kluczy w 3 uniwersalnych pakietach (tożsamość, geo, cykl życia) oraz 5 pakietach wertykalnych B2B (subskrypcja, e-commerce, media, marketplace, lojalność). Ustaw tylko te, które pasują do Twojego produktu — dashboard dostosuje się i pokaże wyłącznie uzupełnione pakiety.

Tożsamość

Zawsze istotne. Ustawia kolumny nagłówka profilu.

Geo

Kontekst geograficzny.

Cykl życia

Kiedy ostatnio go widzieliśmy.

Subskrypcja

Ustaw, jeśli Twój produkt ma plany.

E-commerce

Ustaw, jeśli sprzedajesz produkty.

Media

Ustaw, jeśli publikujesz treści.

Marketplace

Ustaw, jeśli Twój produkt działa jako platforma dwustronna.

Lojalność

Ustaw, jeśli korzystasz z programów lojalnościowych lub nagród.

Super-properties

Pary klucz-wartość przypisane do sesji, automatycznie dołączane do każdego wysyłanego zdarzenia. To nie to samo co cechy identify, które opisują tożsamość; super-properties opisują kontekst sesji — aktywny wariant A/B, wariant buildu czy włączone flagi funkcji. Są przechowywane w UserDefaults między uruchomieniami i czyszczone przy reset(). Przy kolizji kluczy pierwszeństwo zawsze mają właściwości per-event properties w 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()

Śledzenie ekranów w SwiftUI

Wyświetlenia ekranów w SwiftUI są śledzone automatycznie, gdy SDK potrafi ustalić nazwę widoku. Jeśli chcesz mieć większą kontrolę albo nadać własne nazwy, użyj modyfikatora widoku .kixoScreen():

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

Replay sesji

Replay odtwarza to, co użytkownik rzeczywiście widział — SDK przechwytuje klatki ekranu kodowane w HEIC razem ze strukturalną migawką hierarchii widoków, a odtwarzacz w dashboardzie składa je w przewijalne odtworzenie obok osi czasu zdarzeń. Replay dla projektu skonfigurujesz w Dashboard → Ustawienia → Odtwarzanie sesji; SDK automatycznie odczytuje tę politykę i odświeża ją podczas działania aplikacji.

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

W dashboardzie ustawiasz, czy replay jest włączony, jakie obowiązuje maskowanie, tryby przechwytywania oraz czy natywny replay może wysyłać dane przez sieć komórkową. Gdy wysyłka przez sieć komórkową jest wyłączona, klatki nadal mogą trafiać do ograniczonego bufora na urządzeniu; przesyłanie ruszy dopiero w dozwolonej sieci.

SDK zbiera dane włączone w projekcie oraz zdarzenia i właściwości wysyłane przez aplikację.

Maskowanie i prywatność

Ponieważ replay przechwytuje piksele, redakcja odbywa się na urządzeniu przed, zanim zostanie zakodowana choćby jedna klatka. Hasła i inne pola wrażliwe są wykrywane i redagowane automatycznie, a tekst przechwycony do migawki strukturalnej przechodzi przez filtr PII. Aby ukryć dowolny własny element — prywatny wątek wiadomości, saldo konta czy ekran wersji roboczej — ustaw kxRedact na widoku. Kixo rasteryzują jednolity prostokąt na obszarze tego widoku przed kodowaniem HEIC, więc jego piksele nigdy nie opuszczają urządzenia.

balanceLabel.kxRedact = true
cardNumberField.kxRedact = true

Powiadomienia push

SDK instaluje w czasie działania proxy AppDelegate na Kixo.configure — ciche powiadomienia push (content-available: 1) i widoczne powiadomienia dostarczane w tle są przechwytywane automatycznie. Nie musisz dodawać żadnego kodu do AppDelegate. Istniejące implementacje UNUserNotificationCenterDelegate nadal wywołują się normalnie; Kixo jedynie je opakowuje.

Zarejestruj token urządzenia przez standardowe didRegisterForRemoteNotificationsWithDeviceToken:

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

Jeśli aplikacja używa Firebase Messaging, przekaż jego token rejestracji przez provider: .firebase. Kixo zapisze tego dostawcę i będzie dostarczać wiadomości przez FCM HTTP v1; przed wysyłką kampanii skonfiguruj w Kixo konto serwisowe Firebase dla tej aplikacji.

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

Wysyłka danych i działanie offline

SDK lokalnie kolejkowuje zdarzenia, wysyła je partiami i ponawia przejściowe błędy z użyciem backoffu. Jeśli zbieranie danych zostanie wstrzymane w ustawieniach projektu, nowe zdarzenia nie będą wysyłane, dopóki nie zostanie ponownie włączone.

Diagnostyka

Migawka stanu tylko do odczytu. Przydaje się na ekranach debugowych i w smoke testach — odpowiada na pytanie „dlaczego moje zdarzenia nie docierają?” bez użycia debuggera.

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

Wymuś opróżnienie kolejki (do testów)

Przeciążenie synchroniczne, które blokuje wykonanie maksymalnie na timeout sekund, aż zakończy się opróżnianie kolejki. Przeznaczone do fikstur XCTest — nigdy nie wywołuj go z głównego wątku.

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

Reset

Wyczyść tożsamość, super-properties i zapisaną kolejkę. Wywołaj przy wylogowaniu, żeby kolejne zdarzenia nie zostały przypisane poprzedniemu użytkownikowi.

Kixo.reset()