iOS SDK

Kixo iOS SDK поддржува Swift 5.9+ и iOS 16+ за аналитика, атрибуција, push, следење на lifecycle и session replay. Replay ги користи поставките за снимање на ниво на проект и претпазливите стандардни вредности за потешките процеси; не воведува посебен минимум за OS или модел на уред над iOS 16 deployment target на пакетот. Се испорачува преку Swift Package Manager, а SDK автоматски следи екрани, допири, сесии, падови, push известувања и lifecycle настани со еден повик до Kixo.configure. Следењето на мрежни барања е opt-in.

Инсталација

Swift Package Manager

Во Xcode, одете на File → Add Package Dependencies и внесете:

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

Ако зависностите ги управувате во Package.swift, користете го бинарниот release package и производот:

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

Конфигурирај

Иницијализирајте го Kixo во вашата SwiftUI структура App или AppDelegate:

import Kixo

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

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

Опции за конфигурација

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

Автоматски следени настани

• screen_view — непосредни појавувања на UIKit view controller-и + SwiftUI навигација
• screen_visit — структурирана посета затворена при навигација или преминување во заднина, со задржување, бројачи на интеракции, идентитет на екранот и метаподатоци за текот
• session_start / session_end
• tap — допири на копчиња и препознавачи на гестови
• crash — снимени дијагностички податоци за падови и исклучоци
• network — опционални прочистени агрегати на барања и дијагностика на рути
• push_received / push_open / push_dismissed / push_silent / push_action — целосен животен циклус на push известувања
• push_permission / push_token_invalidated
• lifecycle — премини foreground / background / app-launch

Сопствени настани

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

Типизирани помошници за настани

Скратена обвивка над Kixo.track за настаните што Kixo ги препознава по име (purchase, signup,subscribe_start, trial_start,cancel, upgrade, activation,share, invite). Валидација на обликот на својствата при компајлирање и едно место за вистината за имињата на клучевите — backend-скиот детектор за стандардни настани совпаѓа дословно.

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)

Идентификувајте корисници

Резервираните стандардни клучеви на својства носат префикс $ (Mixpanel convention), за да бидат одвоени од вашите сопствени traits и да се појават во колоните на профилот во контролниот панел. Користете го типизираниот enum StandardProperty или суровата низа со префикс $ — подолу во Стандарден каталог на својства е целосната листа од 37 клучеви.

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

Означете корисник за сегментација

Користете setUserProperty со вредност boolean за да додадете едноставна да/не ознака на корисникот. Ознаката останува низ сесии и се користи за сегменти, email кампањи и chat пребарувања — без дополнително местење освен повикот кон 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",
])

Својствата се чуваат во UserDefaults и по повторно стартување и автоматски се прикачуваат на секој излезен настан. Во chat кажете работи како "испрати welcome email до корисници каде subscribe is true" — Kixo го гради сегментот и го подготвува шаблонот за вас. Се бришат на Kixo.reset().

Стандарден каталог на својства

Резервираните клучеви на својства имаат префикс $, за да бидат одвоени од вашите сопствени traits. Каталогот на Kixo опфаќа 37 клучеви во 3 универзални пакети (идентитет, гео, животен циклус) и 5 вертикални B2B пакети (претплата, е-трговија, медиуми, пазар, лојалност). Поставете ги само оние што важат за вашиот производ — контролниот панел се приспособува и ги прикажува само пакетите што ги пополнувате.

Identity

Секогаш е релевантно. Ги поставува колоните во заглавјето на профилот.

Geo

Географски контекст.

Животен циклус

Кога сме го виделе.

Претплата

Поставете го ако вашиот производ има планови.

Е-трговија

Поставете го ако продавате производи.

Медиуми

Поставете го ако објавувате содржина.

Пазар

Поставете го ако сте двострана платформа.

Лојалност

Поставете го ако имате програми за ангажман и награди.

Super-properties

Парови клуч/вредност по сесија што автоматски се прикачуваат на секој излезен настан. Се разликуваат од identify traits (кои го опишуваат идентитетот); super-properties го опишуваат контекстот на сесијата — активна A/B варијанта, тип на build, вклучени feature flags. Се чуваат во UserDefaults и по повторно стартување; се бришат на reset(). При судир, предност секогаш имаат properties на 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

Прегледите на екрани во SwiftUI се следат автоматски кога SDK може да разреши име на view. За попрецизна контрола или сопствени имиња, користете го view modifier-от .kixoScreen():

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

Репродукција на сесија

Replay реконструира што корисникот навистина видел — SDK снима пикселски кадри од екранот (HEIC-encoded) заедно со структурна снимка од хиерархијата на view-ови, а плеерот во контролниот панел ги спојува во репродукција што може да се прегледува покрај временската линија на настани. Конфигурирајте replay за проектот во Контролна табла → Поставки → Снимање на сесии; SDK автоматски ја чита таа политика и ја освежува додека апликацијата работи.

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

Контролниот панел одредува дали replay е вклучен, како се маскира, кои режими на снимање се користат и дали native replay смее да прикачува преку мобилна мрежа. Ако прикачувањето преку мобилна мрежа е исклучено, кадрите и понатаму може да се снимаат во ограничен buffer на уредот; прикачувањето чека дозволена мрежа.

SDK ги снима податоците што се овозможени во вашиот проект, како и настаните и својствата што ги испраќа апликацијата.

Маскирање и приватност

Бидејќи replay снима пиксели, редакирањето се случува на уредот пред да се кодира кој било frame. Password и други чувствителни полиња се препознаваат и редакираат автоматски, а текстот снимен во structural snapshot поминува низ PII филтер. За какво било сопствено редакирање — приватна нишка со пораки, состојба на сметка, нацрт-екран — поставете kxRedact на view-то. Kixo растеризира полн правоаголник врз границите на тоа view пред HEIC кодирањето, така што неговите пиксели никогаш не го напуштаат уредот.

balanceLabel.kxRedact = true
cardNumberField.kxRedact = true

Push известувања

SDK инсталира runtime AppDelegate proxy на Kixo.configure — silent push известувањата (content-available: 1) и видливите push известувања испорачани во заднина се снимаат автоматски. Не е потребен никаков код во AppDelegate. Постоечките имплементации на UNUserNotificationCenterDelegate и понатаму се повикуваат нормално; Kixo само ги обвиткува.

Регистрирајте го device token преку стандардниот didRegisterForRemoteNotificationsWithDeviceToken:

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

Ако апликацијата користи Firebase Messaging, проследете го неговиот registration token со provider: .firebase. Kixo го зачувува тој provider и испорачува преку FCM HTTP v1; пред да испраќате кампањи, конфигурирајте ја Firebase service account сметката на апликацијата во Kixo.

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

Испорака и однесување офлајн

SDK ги реди настаните локално, ги испраќа во пакети и повторува при привремени неуспеси со backoff. Ако собирањето е паузирано од поставките на проектот, новите настани нема да се испраќаат додека повторно не се вклучи.

Дијагностика

Слика за состојбата само за читање. Корисна е во debug екрани или smoke тестови — одговара на „зошто не ми течат настаните?“ без debugger.

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

Присилно празнење (за тестови)

Синхрон преоптоварен метод што блокира до timeout секунди додека не заврши flush. Наменет е за XCTest fixtures — никогаш не го повикувајте од main thread.

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

Ресетирај

Исчистете ги идентитетот, super-properties и зачуваниот ред. Повикајте го при одјава за следните настани да не се припишат на претходниот корисник.

Kixo.reset()