iOS SDK

Kixo iOS SDK падтрымлівае Swift 5.9+ і iOS 16+ для аналітыкі, атрыбуцыі, push-паведамленняў, адсочвання жыццёвага цыклу і паўтору сесій. Для replay выкарыстоўваюцца праектныя пераключальнікі захопу і стрыманыя налады па змаўчанні для больш цяжкіх канвеераў; асобнага ніжняга парога па версіі OS або мадэлі прылады, акрамя iOS 16 як deployment target пакета, няма. SDK распаўсюджваецца праз Swift Package Manager і пасля аднаго выкліку Kixo.configure аўтаматычна адсочвае экраны, націскі, сесіі, збоі, push-паведамленні і падзеі жыццёвага цыклу. Адсочванне сеткавых запытаў уключаецца асобна.

Усталёўка

Swift Package Manager

У Xcode перайдзіце ў File → Add Package Dependencies і ўвядзіце:

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

Калі кіруеце залежнасцямі ў Package.swift, выкарыстоўвайце бінарны release package і product:

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 у вашай структуры App SwiftUI або ў 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 — імгненныя з’яўленні view controller у UIKit + навігацыя 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). Праверка структуры ўласцівасцей на этапе кампіляцыі і адзіная крыніца праўды для назваў ключоў — дэтэктар стандартных падзей на бэкендзе супастаўляе іх літаральна.

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), таму не канфліктуюць з вашымі ўласнымі traits і трапляюць у слупкі профілю ў dashboard. Можна выкарыстоўваць тыпізаваны 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-кампаніях і запытах у чатах — без дадатковай налады, толькі праз выклік 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 можна пісаць запыты кшталту "адправіць вітальны email карыстальнікам, у якіх subscribe = true" — Kixo сам створыць сегмент і падрыхтуе шаблон. Ачышчаюцца праз Kixo.reset().

Стандартны каталог уласцівасцей

Зарэзерваваныя ключы ўласцівасцей маюць прэфікс $, таму не канфліктуюць з вашымі ўласнымі traits. Каталог Kixo ахоплівае 37 ключоў у 3 універсальных пакетах (ідэнтычнасць, геа, жыццёвы цыкл) і 5 вертыкальных пакетах B2B (падпіска, e-commerce, медыя, маркетплэйс, лаяльнасць). Задавайце толькі тое, што пасуе вашаму прадукту, — dashboard сам адаптуецца і пакажа толькі запоўненыя пакеты.

Identity

Заўсёды актуальна. Задае слупкі ў загалоўку профілю.

Geo

Геаграфічны кантэкст.

Жыццёвы цыкл

Калі мы бачылі гэтага карыстальніка.

Падпіска

Задавайце, калі ў вашага прадукту ёсць тарыфныя планы.

Электронная камерцыя

Задавайце, калі прадаяце тавары.

Медыя

Задавайце, калі публікуеце кантэнт.

Маркетплэйс

Задавайце, калі ваш прадукт — двухбаковая платформа.

Лаяльнасць

Задавайце для праграм узаемадзеяння і ўзнагарод.

Super-properties

Пары ключ/значэнне на ўзроўні сесіі, якія аўтаматычна дадаюцца да кожнай выходнай падзеі. У адрозненне ад traits identify (яны апісваюць асобу), super-properties апісваюць кантэкст сесіі — актыўны варыянт A/B, варыянт зборкі, уключаныя 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 .kixoScreen():

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

Прайграванне сесій

Replay аднаўляе тое, што карыстальнік сапраўды бачыў: SDK захоплівае піксельныя кадры экрана (у кадаванні HEIC) разам са структурным здымкам іерархіі view, а прайгравальнік у dashboard зшывае гэта ў пракручвальнае прайграванне побач са стужкай падзей. Наладзьце replay для праекта ў Панэль кіравання → Налады → Паўтор сесіі; SDK аўтаматычна счытвае гэтую палітыку і абнаўляе яе падчас працы прыкладання.

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

Dashboard вызначае, ці ўключаны replay, маскіраванне, рэжымы захопу і ці можна native replay загружаць даныя праз мабільную сетку. Калі загрузка праз мабільную сетку выключана, кадры ўсё роўна могуць трапляць у абмежаваны буфер на прыладзе; загрузка пачакае дазволенай сеткі.

SDK збірае даныя, уключаныя ў вашым праекце, а таксама падзеі і ўласцівасці, якія адпраўляе ваша праграма.

Маскіраванне і прыватнасць

Паколькі replay захоплівае пікселі, рэдагаванне адбываецца на прыладзе перад таго, як будзе закодаваны хоць адзін кадр. Полі для пароляў і іншыя адчувальныя палі выяўляюцца і хаваюцца аўтаматычна, а тэкст са структурнага здымка праходзіць праз фільтр PII. Каб схаваць уласны кантэнт — прыватную гутарку, баланс акаўнта, экран чарнавіка — задайце kxRedact для view. Kixo раструе суцэльны прамавугольнік па межах гэтага view яшчэ да HEIC-кадавання, таму яго пікселі ніколі не пакідаюць прыладу.

balanceLabel.kxRedact = true
cardNumberField.kxRedact = true

Push-апавяшчэнні

SDK усталёўвае runtime-праксі AppDelegate у Kixo.configure — ціхія push-паведамленні (content-available: 1) і бачныя push-паведамленні, дастаўленыя ў фоне, захопліваюцца аўтаматычна. Код у AppDelegate для гэтага не патрэбны. Існуючыя рэалізацыі UNUserNotificationCenterDelegate працягваюць нармальна выклікацца; Kixo проста абгортвае іх.

Зарэгіструйце токен прылады праз стандартны 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 захоўвае гэтага правайдара і дастаўляе паведамленні праз FCM HTTP v1; перад адпраўкай кампаній наладзьце ў Kixo service account вашага прыкладання ў Firebase.

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

Дастаўка і паводзіны ў афлайне

SDK трымае падзеі ў лакальнай чарзе, адпраўляе іх пакетамі і паўтарае часовыя збоі з backoff. Калі збор спынены ў наладах праекта, новыя падзеі не адпраўляюцца, пакуль яго зноў не ўключаць.

Дыягностыка

Здымак стану толькі для чытання. Карысны на экранах адладкі або ў smoke tests — адказвае на пытанне «чаму мае падзеі не паступаюць?» без дэбагера.

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 — ніколі не выклікайце яе з галоўнага патоку.

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

Скінуць

Ачысціць ідэнтычнасць, super-properties і захаваную чаргу. Выклікайце пры выхадзе з акаўнта, каб наступныя падзеі не прыпісваліся папярэдняму карыстальніку.

Kixo.reset()