iOS SDK

Kixo iOS SDK, analiz, ilişkilendirme, push, yaşam döngüsü takibi ve oturum yeniden oynatma için Swift 5.9+ ile iOS 16+ destekler. Yeniden oynatma, proje düzeyindeki yakalama anahtarlarını ve daha ağır işleme hatları için temkinli varsayılanları kullanır; paketin iOS 16 dağıtım hedefinin ötesinde ayrı bir OS ya da cihaz modeli alt sınırı getirmez. Swift Package Manager ile dağıtılan SDK, tek bir Kixo.configure çağrısıyla ekranları, dokunuşları, oturumları, çökmeleri, push bildirimlerini ve yaşam döngüsü olaylarını otomatik olarak izler. Ağ isteği takibi isteğe bağlıdır.

Kurulum

Swift Package Manager

Xcode'da File → Add Package Dependencies bölümüne gidin ve şunu girin:

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

Bağımlılıkları Package.swift ile yönetiyorsanız ikili sürüm paketini ve ürününü kullanın:

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

Yapılandır

Kixo'yu SwiftUI App yapınızda veya AppDelegate içinde başlatın:

import Kixo

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

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

Yapılandırma seçenekleri

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

Otomatik izlenen etkinlikler

• screen_view — anlık UIKit görünüm denetleyicisi gösterimleri + SwiftUI gezinmesi
• screen_visit — gezinme veya arka plana geçişte kapanan; kalma süresi, etkileşim sayıları, ekran kimliği ve akış üst verisini içeren yapılandırılmış ziyaret
• session_start / session_end
• tap — düğme dokunuşları ve hareket tanıyıcıları
• crash — yakalanan çökme ve istisna tanıları
• network — isteğe bağlı olarak temizlenmiş istek toplamları ve rota tanıları
• push_received / push_open / push_dismissed / push_silent / push_action — push bildiriminin tam yaşam döngüsü
• push_permission / push_token_invalidated
• lifecycle — ön plan / arka plan / uygulama açılışı geçişleri

Özel etkinlikler

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

Tür denetimli olay yardımcıları

Kixo'nun adıyla tanıdığı olaylar (purchase, signup,subscribe_start, trial_start,cancel, upgrade, activation,share, invite) için Kixo.track üzerine eklenmiş kolaylık katmanı. Özellik yapısı derleme anında doğrulanır, anahtar adları için tek doğruluk kaynağı sağlar — arka uçtaki standart olay algılayıcısı metni birebir eşleştirir.

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)

Kullanıcıları tanımlayın

Ayrılmış standart özellik anahtarları, kendi özel trait'lerinizle çakışmaması ve panodaki profil sütunlarına taşınabilmesi için $ öneki taşır (Mixpanel geleneği). Tür denetimli StandardProperty enum'unu ya da $ önekli ham dizeyi kullanabilirsiniz — 37 anahtarın tam listesi için aşağıdaki Standart özellik kataloğu bölümüne bakın.

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

Segmentasyon için kullanıcı etiketleyin

Kullanıcıya basit bir evet/hayır etiketi eklemek için setUserProperty metodunu boolean değerle kullanın. Etiket oturumlar arasında korunur ve segmentler, e-posta kampanyaları ve sohbet sorgularında kullanılır; SDK çağrısının dışında ek kurulum gerekmez.

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

Özellikler, uygulama açılışları arasında UserDefaults içinde saklanır ve her gönderilen olaya otomatik eklenir. Sohbette "subscribe değeri true olan kullanıcılara hoş geldin e-postası gönder" gibi şeyler yazın — Kixo segmenti oluşturur ve şablon taslağını sizin için hazırlar. Kixo.reset() ile temizlenir.

Standart özellik kataloğu

Ayrılmış özellik anahtarları, özel trait'lerinizle çakışmaması için $ öneki taşır. Kixo kataloğunda 3 evrensel paket (kimlik, coğrafya, yaşam döngüsü) ve 5 B2B dikey paketinde (abonelik, e-ticaret, medya, pazaryeri, sadakat) toplam 37 anahtar bulunur. Ürününüz için geçerli olanları ayarlayın; pano buna uyum sağlar ve yalnızca doldurduğunuz paketleri gösterir.

Kimlik

Her zaman anlamlıdır. Profil başlığındaki sütunları belirler.

Coğrafi

Coğrafi bağlam.

Yaşam döngüsü

Onu ne zaman gördük?

Abonelik

Ürününüzde planlar varsa ayarlayın.

E-ticaret

Ürün satıyorsanız ayarlayın.

Medya

İçerik yayımlıyorsanız ayarlayın.

Pazaryeri

İki taraflı bir platformsanız ayarlayın.

Sadakat

Etkileşim ve ödül programları için ayarlayın.

Super-properties

Her gönderilen olaya otomatik eklenen, oturum bazlı anahtar/değer çiftleridir. identify trait'lerinden farklıdır; trait'ler kimliği tanımlar, super-properties ise oturum bağlamını tanımlar — aktif A/B varyantı, derleme türü, açık özellik bayrakları gibi. Uygulama açılışları arasında UserDefaults içinde saklanır; reset() ile temizlenir. Anahtar çakışmasında track üzerindeki olay düzeyindeki properties her zaman önceliklidir.

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 izleme

SDK bir görünüm adını çözebildiğinde SwiftUI ekran görüntülemeleri otomatik izlenir. Daha ayrıntılı denetim veya özel adlar için .kixoScreen() görünüm değiştiricisini kullanın:

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

Oturum yeniden oynatma

Replay, kullanıcının ekranda gerçekten ne gördüğünü yeniden kurar — SDK ekranın piksel karelerini (HEIC ile kodlanmış) görünüm hiyerarşisinin yapısal anlık görüntüsüyle birlikte yakalar, pano oynatıcısı da bunları olay zaman akışının yanında ileri geri sarılabilen bir oynatıma dönüştürür. Proje için replay'i Kontrol Paneli → Ayarlar → Oturum tekrarı altında yapılandırın; SDK bu politikayı otomatik okur ve uygulama çalışırken yeniler.

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

Replay'in açık olup olmadığını, maskelemeyi, kayıt modlarını ve yerel replay'in hücresel ağ üzerinden yükleme yapıp yapamayacağını pano belirler. Hücresel yükleme kapalıysa kareler yine de cihazdaki sınırlı bir arabelleğe alınabilir; yükleme, izin verilen bir ağı bekler.

SDK, projenizde etkin olan verileri ve uygulamanızın gönderdiği olaylarla özellikleri yakalar.

Maskeleme ve gizlilik

Replay piksel yakaladığı için, sansürleme herhangi bir kare kodlanmadan önce cihaz üzerinde yapılır. Parola ve diğer hassas alanlar otomatik algılanıp sansürlenir; yapısal anlık görüntüye giren metin de PII filtresinden geçirilir. Özel bir alanı — örneğin özel mesaj dizisini, hesap bakiyesini veya taslak ekranı — sansürlemek için görünümde kxRedact ayarlayın. Kixo, HEIC kodlamasından önce bu görünümün sınırları üzerine düz bir dikdörtgen çizer; böylece ilgili pikseller cihazdan hiç çıkmaz.

balanceLabel.kxRedact = true
cardNumberField.kxRedact = true

Push bildirimleri

SDK, Kixo.configure üzerinde çalışma anında bir AppDelegate proxy’si kurar; sessiz push’lar (content-available: 1) ve arka planda teslim edilen görünür push’lar otomatik olarak yakalanır. AppDelegate’inize herhangi bir kod eklemeniz gerekmez. Mevcut UNUserNotificationCenterDelegate uygulamalarınız normal şekilde çalışmaya devam eder; Kixo bunları sarmalar.

Cihaz jetonunu standart didRegisterForRemoteNotificationsWithDeviceToken ile kaydedin:

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

Uygulama Firebase Messaging kullanıyorsa kayıt jetonunu provider: .firebase ile iletin. Kixo bu sağlayıcıyı kaydeder ve teslimatı FCM HTTP v1 üzerinden yapar; kampanya göndermeden önce uygulamanın Firebase hizmet hesabını Kixo'da yapılandırın.

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

Gönderim ve çevrimdışı davranış

SDK, olayları yerelde kuyruğa alır, toplu gönderir ve geçici hataları artan bekleme süreleriyle yeniden dener. Toplama proje ayarlarından duraklatılırsa, yeniden etkinleştirilene kadar yeni olaylar gönderilmez.

Tanılama

Salt okunur sağlık özeti. Hata ayıklama ekranlarında veya smoke test'lerde kullanışlıdır — ayıklayıcı açmadan "olaylarım neden akmıyor?" sorusunu yanıtlar.

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

Zorla gönder (testler için)

Flush tamamlanana kadar en fazla timeout saniye bekleyen eşzamanlı overload. XCTest fixture'ları için tasarlanmıştır; ana thread'den kesinlikle çağırmayın.

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

Sıfırla

Kimliği, super-properties'i ve kalıcı kuyruğu temizler. Sonraki olayların önceki kullanıcıya yazılmaması için çıkışta çağırın.

Kixo.reset()