Android SDK

Kixo Android SDK Kotlin 2.0+ және Java тілдерін қолдайды, кемінде minSdk 24 (Android 7.0) нұсқасын талап етеді және compileSdk 35 нұсқасымен құрастырылған. Негізгі қолданба өзінің targetSdk параметріне өзі жауап береді. Application.onCreate ішіндегі жалғыз Kixo.configure шақыруы экрандарды, түртулерді, сессияларды, істен шығуларды және өмірлік цикл оқиғаларын автоматты түрде тіркейді. Push-хабарламаларды қадағалау үшін төменде сипатталған FCM көпірі қажет. Желілік сұрауларды автоматты түрде тіркеу Android-тің қазіргі шығарылымына кірмейді. SDK сессияны қайта ойнатуды, пайдаланушыны сәйкестендіруді және мақсаттарды да қолдайды.

Жылдам бастау

Үш файл. Maven репозиторийін қосыңыз, тәуелділікті қосыңыз, содан соң Application subclass-ыңызға екі жол енгізіңіз.

Құрастыру талаптары: compileSdk 35, minSdk 24, Kotlin 2.0+ немесе Java, әрі Java 17 байткоды.

dependencyResolutionManagement {
    repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
    repositories {
        google()
        mavenCentral()
        maven {
            url = uri("https://raw.githubusercontent.com/kixoio/kixo-android-sdk/main/repo")
        }
    }
}

Қолданбаға қосу

Kixo Maven репозиторийі GitHub Pages-та хостталады. Оны settings.gradle.kts ішінде google() және mavenCentral() репозиторийлерімен қатар қосыңыз:

// settings.gradle.kts
dependencyResolutionManagement {
    repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
    repositories {
        google()
        mavenCentral()
        maven {
            url = uri("https://raw.githubusercontent.com/kixoio/kixo-android-sdk/main/repo")
        }
    }
}

Содан кейін тәуелділікті қолданба модулінде жариялаңыз:

// app/build.gradle.kts
dependencies {
    implementation("io.kixo:kixo-android-sdk:0.1.20")
}

Көпмодульді жобалар

Gradle-дегі implementation конфигурациясы транзитивті емес: кітапхана модулінде implementation("io.kixo:kixo-android-sdk:0.1.20") көрсету (мысалы, :core_domain) Kixo тәуелділігін :app не кез келген басқа тұтынушыға көрінетін етпейді. Жұмыс істейтін екі тәсіл бар — біреуін таңдаңыз.

A үлгісі — Kixo шақыратын әр модуль оны өзі жариялайды (ұсынылады). әр модульдің classpath-ын ықшам ұстап, тізбекті rebuild-тердің алдын алады. Нұсқаны бір жерден ғана өзгерту үшін version catalog (libs.kixo.sdk) қолданыңыз.

// :core_domain/build.gradle.kts
dependencies {
    implementation("io.kixo:kixo-android-sdk:0.1.20")   // local use only
}

// :app/build.gradle.kts
dependencies {
    implementation(project(":core_domain"))
    implementation("io.kixo:kixo-android-sdk:0.1.20")   // declared again — fine
}

B үлгісі — api(...) арқылы қайта экспорттау. Бір ғана декларация, бірақ кітапхана модулінің public ABI-іне енді Kixo типтері де кіреді — нұсқа өзгерсе, төмендегі барлық модуль қайта жиналады. Мұны кітапхана өзінің public сигнатураларында Kixo типтерін қайта пайдаланғанда ғана қолданыңыз (мысалы, функция KixoDiagnostics қайтаратын болса).

// :core_domain/build.gradle.kts
dependencies {
    api("io.kixo:kixo-android-sdk:0.1.20")              // re-exposed
}

// :app/build.gradle.kts
dependencies {
    implementation(project(":core_domain"))            // gets Kixo for free
}

Инициализация

Kixo-ны өз Application subclass-ыңызда баптаңыз — onCreate кез келген activity-ден бұрын орындалады, сондықтан әр экран қаралымы, түрту және lifecycle оқиғасы алғашқы кадрдан бастап тіркеледі. Manifest ішінде Application мәнін android:name=".MyApp" арқылы тіркеңіз.

import android.app.Application
import io.kixo.sdk.Kixo

class MyApp : Application() {
    override fun onCreate() {
        super.onCreate()
        Kixo.configure(
            context   = this,
            projectId = "kx_proj_YOUR_PROJECT_ID",
            apiKey    = "kx_key_YOUR_API_KEY",
        )
    }
}

Ұсақ-түйек баптаулар керек болса (auto-track жалаушалары, flush жиілігі, replay sampling, custom API host), KixoConfiguration нысанын ашық түрде құрыңыз:

import io.kixo.sdk.Kixo
import io.kixo.sdk.KixoConfiguration

val config = KixoConfiguration.Builder(
    projectId = "kx_proj_YOUR_PROJECT_ID",
    apiKey    = "kx_key_YOUR_API_KEY",
)
    .autoTrackScreens(true)
    .autoTrackTaps(true)
    .autoTrackNetwork(false)  // reserved; no-op in the current Android release
    .autoTrackCrashes(true)
    .autoTrackSessions(true)
    .autoTrackPush(true)
    .flushIntervalMillis(30_000)
    .flushAt(20)
    .maxBufferSize(200)
    .build(applicationContext)

Kixo.configure(this, config)

Оқиғаларды тіркеу

Инструментацияның негізгі бөлігі үш примитивке сүйенеді: оқиғалар үшін track, конверсия сигналдары үшін markGoal, ал оқиғаға жатпайтын контекст үшін addBreadcrumb.

import io.kixo.sdk.Kixo

Kixo.track("video_played", mapOf(
    "video_id"    to "vid_42",
    "duration_ms" to 18_500,
    "autoplay"    to false,
))

// markGoal(name, value?, currency?, properties?) — pass extra context
// through the named 'properties' argument (a Map can't be the 2nd
// positional arg; that slot is the Double 'value').
Kixo.markGoal("activated", properties = mapOf(
    "step" to "onboarding_completed",
))

// Revenue goals use the typed value + currency parameters:
Kixo.markGoal("purchase_completed", value = 49.99, currency = "USD")

Kixo.addBreadcrumb(
    message  = "user toggled dark mode",
    category = "ui",
    level    = "info",
)

Стандартты оқиғалар

Kixo атауы бойынша танитын оқиғалар үшін Kixo.track үстіндегі ыңғайлы қабат — backend-тегі стандарт оқиға детекторы дәл сәйкестендіретін өзгеріссіз жол кілттері. Қасиеттер пішіні compile-time кезінде тексеріледі, атаулардың бірыңғай көзі де осы болады.

import io.kixo.sdk.Kixo
import io.kixo.sdk.SubscriptionInterval

Kixo.trackPurchase(
    amount    = 49.99,
    currency  = "USD",
    productId = "pro_yearly",
)

Kixo.trackSubscriptionStart(
    plan     = "pro",
    amount   = 9.99,
    currency = "USD",
    interval = SubscriptionInterval.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)

Пайдаланушыларды анықтау

Келесі оқиғаларды тұрақты user id-ге және traits жиынына байлаңыз. Анонимді пайдаланушыны белгілі пайдаланушымен байланыстыру Kixo ішінде жасалады — identify дейін жиналған оқиғалар кейін сол пайдаланушыға телінеді.

import io.kixo.sdk.Kixo

// Reserved standard property keys carry a $-prefix (Mixpanel
// convention) so they namespace away from your own custom traits
// and promote to the dashboard's profile columns. See
// io.kixo.sdk.StandardProperty for the typed catalogue, or the
// "Standard property catalog" section below for the full 37-key list.
Kixo.identify("user_123", mapOf(
    "$email" to "jane@example.com",     // identity
    "$name"  to "Jane Doe",              // identity
    "$plan"  to "pro",                   // subscription pack
    "$lifetime_orders" to 12,            // e-commerce pack
    "signup_source" to "twitter_ad",     // custom trait
))

// Logout: clear identity, super-properties, and the persisted queue.
Kixo.reset()

⚠️ Kotlin-тағы доллар белгісінің қақпаны. Стандарт identity кілттері $ префиксімен жазылады ($email, $name, $first_name) — ал Kotlin жол литералында доллар белгісін "\$email" түрінде міндетті көрсету керек. "$email" деп жазсаңыз, email айнымалысы жолға интерполяцияланады, соның салдарынан мән үнсіз түрде теңшелетін trait болып кетеді де, Audience ішіндегі email / name бағандары толмай қалады. Ең оңай түзету — қате жіберу мүмкін емес типтелген overload-ты пайдалану (SDK 0.1.13+): Kixo.setUserProperty(StandardProperty.EMAIL, email).

Пайдаланушыны сегменттеуге белгілеу

Пайдаланушыға қарапайым иә/жоқ белгісін бекіту үшін логикалық мән мәнімен setUserProperty қолданыңыз. Белгі қолданба қайта ашылғаннан кейін де сақталады және сегменттерде, email науқандарында және chat сұрауларында бірден қолданылады — SDK шақыруынан басқа ештеңе керек емес.

// Tag a user as subscribed — segments + campaigns can target this
Kixo.setUserProperty("subscribe", true)

// VIP membership
Kixo.setUserProperty("vip", true)

// String + numeric values work too
Kixo.setUserProperty("plan_tier", "enterprise")
Kixo.setUserProperty("lifetime_orders", 42)

// Bulk-set
Kixo.setUserProperties(mapOf(
    "subscribe" to true,
    "plan_tier" to "enterprise",
))

Қасиеттер SharedPreferences арқылы сақталады, қолданба қайта ашылғаннан кейін де әр сыртқа жіберілетін оқиғаға автоматты түрде қосылады. Chat-та "subscribe мәні true болатын пайдаланушыларға welcome email жібер" сияқты жазыңыз — Kixo сіз үшін сегментті құрып, хабарлама үлгісін дайындап береді. Kixo.reset() кезінде тазарады.

Стандартты property каталогы

Резервтелген property кілттері $ префиксімен беріледі, сондықтан олар custom traits-пен бір атау кеңістігінде қақтығыспайды. Kixo каталогында 3 әмбебап pack (identity, geo, lifecycle) және 5 B2B салалық pack (subscription, e-commerce, media, marketplace, loyalty) бойынша 37 кілт бар. Өніміңізге сәйкес келетіндерін ғана орнатыңыз — дашборд соған бейімделіп, тек толтырылған pack-терді көрсетеді.

Идентификация

Әрдайым қажет. Профиль тақырыбындағы бағандарды орнатады.

Гео

Географиялық контекст.

Өмірлік цикл

Оларды қашан көрдік.

Жазылым

Өніміңізде тарифтер болса, орнатыңыз.

E-commerce

Өнім сатсаңыз, орнатыңыз.

Медиа

Контент жарияласаңыз, орнатыңыз.

Маркетплейс

Екіжақты платформа болсаңыз, орнатыңыз.

Адалдық

Белсенділік пен сыйақы бағдарламалары болса, орнатыңыз.

Super-properties

Әр сыртқа жіберілетін оқиғаға автоматты түрде қосылатын, сессияға ортақ key/value жұптары. identify traits-пен шатастырмаңыз (олар identity-ді сипаттайды); super-properties сессия контексін сипаттайды — белсенді A/B нұсқасы, build flavor, қосылған feature flag-тер. Қолданба қайта ашылса да сақталады; reset() кезінде тазарады. Қақтығыс болса, track ішіндегі әр оқиғаға берілген properties әрқашан басым түседі.

import io.kixo.sdk.Kixo

Kixo.setSuperProperty("build_flavor", "beta")
Kixo.setSuperProperties(mapOf(
    "ab_variant"        to "B",
    "referrer_campaign" to "autumn-launch",
))

// Sugar for A/B tracking — stored as 'experiment_<id>'.
Kixo.setExperimentVariant("checkout_v2", "variant_a")

Kixo.unsetSuperProperty("build_flavor")
Kixo.clearSuperProperties()

Push хабарландырулар

Интеграцияның екі жолы бар. FCM қолданып, ең қысқа жұмыс істейтін баптауды қаласаңыз, A нұсқасын таңдаңыз; ал қайта құрылымдай алмайтын custom FirebaseMessagingService болса немесе Kixo қай FCM жеткізілімдерін көретінін өзіңіз нақты басқарғыңыз келсе, B нұсқасын таңдаңыз.

A нұсқасы — KixoFirebaseMessagingService класын кеңейту (автоматты tracking)

KixoFirebaseMessagingService класын кеңейтіп, override ішінде super.onMessageReceived(...) шақырыңыз — Kixo push_received (көрінетін payload) не push_silent (тек data) оқиғасын автоматты түрде жібереді. Егер override жасамасаңыз, базалық класс onNewToken тіркеуін де өзі өңдейді. AndroidManifest.xml тіркеуі кәдімгі FCM сервисіндегідей қалады.

import com.google.firebase.messaging.RemoteMessage
import io.kixo.sdk.KixoFirebaseMessagingService

class MyMessagingService : KixoFirebaseMessagingService() {
    override fun onMessageReceived(remoteMessage: RemoteMessage) {
        super.onMessageReceived(remoteMessage)  // Kixo auto-tracks push_received
        // … your own routing / notification display
    }
}

B нұсқасы — manual API-ды өз FCM сервисіңізден шақыру

FCM токенін FirebaseMessagingService.onNewToken арқылы Kixo-ға тіркеңіз, содан кейін әр жеткізілімді бөлек тіркеңіз. Kixo FCM жеткізілімдерінің тек бір бөлігін ғана көрсін десеңіз, осы жолды таңдаңыз. Қазір Android-та жеткізілімді бақылау тек FCM үшін қолжетімді.

import com.google.firebase.messaging.FirebaseMessagingService
import com.google.firebase.messaging.RemoteMessage
import io.kixo.sdk.Kixo
import io.kixo.sdk.PushProvider

class MyMessagingService : FirebaseMessagingService() {
    override fun onNewToken(token: String) {
        Kixo.setPushToken(token, PushProvider.FCM)
    }

    override fun onMessageReceived(message: RemoteMessage) {
        // Convert the FCM payload to a Map<String, Any?> and log it —
        // Kixo correlates this with the open / dismiss it sees later.
        Kixo.logPushReceived(message.data.toMap(), appState = "background")
    }
}

Android хабарландыру ашылғанын, жабылғанын немесе action button басылғанын ұстайтын әмбебап lifecycle hook бермейді. Бұл сигналдарды қолданбаңыз жасайтын notification intent-терінен не receiver-лерінен өзіңіз жіберіңіз:

import io.kixo.sdk.Kixo

Kixo.logPushOpened(payload = pushPayload)            // open
Kixo.logPushOpened(payload = pushPayload, actionId = "reply")  // action-button tap
Kixo.logPushDismissed(payload = pushPayload)         // swipe-away

Сессияны қайта ойнату

Пайдаланушы экранда не көргенін көзбен шынайы түрде қайта ойнатыңыз. Әр capture кезінде SDK экранның сығылған кадрын (JPEG кескіні) және view иерархиясының құрылымдық snapshot-ын кодтап, екеуін де жүктейді — соның арқасында дашбордтағы ойнатқыш әрекеттер таймлайнымен қатар пиксель деңгейінде дәл көрсетеді. Жобаға арналған replay баптауларын Басқару тақтасы → Баптаулар → Сессияны қайта ойнату ішінде орнатыңыз. SDK жоба саясатын, соның ішінде маскалау, capture режимдері және ұялы желі арқылы жүктеуге рұқсат параметрлерін автоматты түрде оқып, жаңартып отырады.

import io.kixo.sdk.Kixo
import io.kixo.sdk.KixoConfiguration

val config = KixoConfiguration.Builder(
    projectId = "kx_proj_YOUR_PROJECT_ID",
    apiKey    = "kx_key_YOUR_API_KEY",
)
    .build(applicationContext)

Kixo.configure(this, config)

Ұялы желі арқылы жүктеу өшірулі болса, кезектегі replay рұқсат етілген желі шыққанша күтіп тұрады.

Деректерді жинау

SDK жобаңызда қосылған деректерді және қолданбаңыз жіберетін оқиғалар мен қасиеттерді жинайды.

Жөндеу

Kixo.diagnostics() SDK күйінің тек оқуға арналған snapshot-ын қайтарады — жасырын debug экранында не smoke test-те ыңғайлы. «Оқиғаларым неге өтпей жатыр?» деген сұраққа debugger қоспай-ақ жауап береді.

import io.kixo.sdk.Kixo

val diag = Kixo.diagnostics()
Log.d("Kixo", "queued=${diag.queue.bufferedEventCount}")
Log.d("Kixo", "paused=${diag.paused}")                  // collection paused state
Log.d("Kixo", "lifecycleState=${diag.lifecycleState}")  // SDK lifecycle state

Тест қаптамасынан буферді күштеп жіберіңіз — желіге барып-қайтуға timeoutMs дейін бөгеледі:

import io.kixo.sdk.Kixo

// Async fire-and-forget — returns immediately.
Kixo.flush()

// Blocking variant for instrumentation tests. Never call on the main thread.
val landed: Boolean = Kixo.flushBlocking(timeoutMs = 5_000L)
assertTrue(landed)

Compose Navigation

Activity / Fragment маршруттары бірден screen_viewevents және dwell пен flow метадеректері бар құрылымды screen_visit жазбаларын береді. Jetpack Compose Navigation үшін route-қа байланған LaunchedEffect ішінен Kixo.screen шақырыңыз — сонда SDK recomposition санына қарамастан әр destination үшін бір оқиға көреді.

import androidx.compose.runtime.Composable
import androidx.compose.runtime.LaunchedEffect
import androidx.navigation.NavHostController
import androidx.navigation.compose.NavHost
import androidx.navigation.compose.composable
import io.kixo.sdk.Kixo

@Composable
fun AppNavHost(nav: NavHostController) {
    NavHost(navController = nav, startDestination = "home") {
        composable("home") {
            LaunchedEffect("home") { Kixo.screen("HomeScreen") }
            HomeScreen()
        }
        composable("settings") {
            LaunchedEffect("settings") { Kixo.screen("SettingsScreen") }
            SettingsScreen()
        }
    }
}

AI код агенттері

SDK-ның public беті шағын және code completion-ға ыңғайланып жасалған — барлық әдіс Kixo singleton-ында, осы нұсқаулықтағы әр Kotlin мысалы import io.kixo.sdk.Kixo-ден басталады, ал біздің README ішінде Claude Code, Cursor және Codex сияқты құралдар контексіне сол күйі қоя салатын "AI agent quick reference" блогы бар. Агентіңіз тұрып қалса, негізгі бастапқы үлгі мынау:

// Tell your AI coding agent:
// "Integrate the Kixo Android SDK using io.kixo:kixo-android-sdk
//  from https://raw.githubusercontent.com/kixoio/kixo-android-sdk/main/repo.
//  Call Kixo.configure(this, projectId, apiKey) in Application.onCreate.
//  Then use Kixo.track / Kixo.identify / Kixo.markGoal as needed."