Android SDK

Kixo Android SDK palaiko Kotlin 2.0+ ir Java, reikalauja minSdk 24 (Android 7.0) ir yra sukompiliuotas su compileSdk 35. Jūsų pagrindinė programa ir toliau pati atsako už savo targetSdk. Vienas Kixo.configure iškvietimas jūsų Application.onCreate klasėje automatiškai įjungia ekranų, bakstelėjimų, sesijų, strigčių ir gyvavimo ciklo įvykių sekimą. Push sekimui reikia toliau aprašyto FCM tilto. Automatinio tinklo užklausų sekimo dabartinėje Android laidoje nėra. SDK taip pat palaiko sesijų atkūrimą, tapatybę ir tikslus.

Greita pradžia

Trys failai. Pridėkite Maven saugyklą, pridėkite priklausomybę, tada į savo Application poklasį įrašykite dvi eilutes.

Rinkimo reikalavimai: compileSdk 35, minSdk 24, Kotlin 2.0+ arba Java ir Java 17 baitkodas.

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

Pridėkite į programą

Kixo Maven saugykla talpinama per GitHub Pages. Pridėkite ją šalia google() ir mavenCentral() faile settings.gradle.kts:

// 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")
        }
    }
}

Tada deklaruokite priklausomybę programos modulyje:

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

Kelių modulių projektai

Gradle implementation konfigūracija yra netranzityvi: jei bibliotekos modulyje (pvz., :core_domain) deklaruojate implementation("io.kixo:kixo-android-sdk:0.1.20"), tai NEREIŠKIA, kad Kixo bus matomas :app ar bet kuriam kitam vartotojui. Veikia du būdai — pasirinkite vieną.

A šablonas — kiekvienas modulis, kuris kviečia Kixo, pats deklaruoja priklausomybę (rekomenduojama). Taip kiekvieno modulio classpath išlieka kuo mažesnis ir išvengiama grandininių perkompiliavimų. Naudokite versijų katalogą (libs.kixo.sdk), kad versiją reikėtų keisti tik vienoje vietoje.

// :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 šablonas — reeksportuokite per api(...). Deklaracija viena, bet bibliotekos modulio viešasis ABI dabar apima Kixo tipus, todėl kiekvienas versijos atnaujinimas priverčia perkompiliuoti visus priklausomus modulius. Taip darykite tik tada, kai biblioteka naudoja Kixo tipus savo viešose signatūrose, pvz., grąžina 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
}

Inicializuokite

Konfigūruokite Kixo savo Application poklasyje — onCreate įvykdomas dar prieš bet kurią activity, todėl kiekviena ekrano peržiūra, bakstelėjimas ir gyvavimo ciklo įvykis užfiksuojami nuo pirmojo kadro. Užregistruokite Application manifeste su 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",
        )
    }
}

Jei reikia detalių nustatymų — automatinio sekimo vėliavėlių, flush dažnio, atkūrimo imties ar pasirinktinio API serverio — KixoConfiguration susikurkite aiškiai:

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)

Sekite įvykius

Didžiąją dalį instrumentavimo sudaro trys pagrindiniai elementai: track įvykiams, markGoal konversijos signalams ir addBreadcrumb kontekstui, kuris nėra atskiras įvykis.

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

Standartiniai įvykiai

Patogesnis sluoksnis virš Kixo.track įvykiams, kuriuos Kixo atpažįsta pagal pavadinimą — tai tikslūs string raktai, kuriuos backend standartinių įvykių detektorius susieja. Gaunate kompiliavimo metu tikrinamą savybių struktūrą ir vieną tiesos šaltinį pavadinimams.

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)

Identifikuokite naudotojus

Susiekite tolesnius įvykius su stabiliu naudotojo ID ir požymių rinkiniu. Anoniminio ir atpažinto naudotojo sujungimą atlieka Kixo — įvykiai, užfiksuoti prieš identify, atgaline tvarka priskiriami tam pačiam naudotojui.

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 dolerio ženklo spąstai. Standartiniai tapatybės raktai turi $ prefiksą ($email, $name, $first_name) — o Kotlin eilutės literale privaloma dolerio ženklą reikia escape'inti kaip "\$email". Jei parašysite "$email", bus interpoliuotas jūsų email kintamasis, todėl reikšmė tyliai nukeliaus kaip pasirinktinis požymis ir niekada neužpildys Audience el. pašto ar vardo stulpelių. Paprasčiausias sprendimas — naudoti tipizuotą overload'ą (SDK 0.1.13+), su kuriuo suklysti neįmanoma: Kixo.setUserProperty(StandardProperty.EMAIL, email).

Pažymėkite naudotoją segmentavimui

Naudokite setUserProperty su boolean reikšme, jei naudotojui norite priskirti paprastą taip / ne žymą. Ji išlieka tarp paleidimų ir naudojama segmentuose, el. pašto kampanijose bei pokalbio užklausose — nieko daugiau nei SDK iškvietimo nereikia.

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

Savybės per SharedPreferences išlieka tarp paleidimų ir automatiškai pridedamos prie kiekvieno siunčiamo įvykio. Pokalbyje galite parašyti, pavyzdžiui, "išsiųsti pasveikinimo el. laišką naudotojams, kurių subscribe yra true" — Kixo pats sukurs segmentą ir parengs šablono juodraštį. Išvaloma per Kixo.reset().

Standartinių savybių katalogas

Rezervuoti savybių raktai turi $ prefiksą, todėl nesikerta su jūsų pasirinktiniais požymiais. Kixo kataloge yra 37 raktai: 3 universalūs paketai (tapatybė, geografiniai duomenys, gyvavimo ciklas) ir 5 B2B sritiniai paketai (prenumerata, e. prekyba, medija, prekyvietė, lojalumas). Pildykite tik tai, kas tinka jūsų produktui — suvestinė prisitaikys ir rodys tik tuos paketus, kuriuos naudojate.

Tapatybė

Visada aktualu. Nustato profilio antraštės stulpelius.

Geo

Geografinis kontekstas.

Gyvavimo ciklas

Kada juos matėme.

Prenumerata

Nurodykite, jei jūsų produktas turi planus.

El. prekyba

Nurodykite, jei parduodate produktus.

Medija

Nurodykite, jei publikuojate turinį.

Prekyvietė

Nurodykite, jei jūsų platforma jungia dvi puses.

Lojalumas

Nurodykite, jei naudojate įsitraukimo ar lojalumo programas.

Super-properties

Sesijos lygmens rakto ir reikšmės poros, kurios automatiškai pridedamos prie kiekvieno siunčiamo įvykio. Jos skiriasi nuo identify požymių, kurie apibūdina tapatybę; super-savybės aprašo sesijos kontekstą — aktyvų A/B variantą, build flavor, įjungtas funkcijų vėliavėles. Išlieka tarp paleidimų, išvalomos per reset(). Jei raktai sutampa, įvykio lygmens properties ties track visada turi pirmenybę.

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 pranešimai

Yra du integravimo keliai. Rinkitės A, jei naudojate FCM ir norite trumpiausios veikiančios sąrankos; rinkitės B, jei jau turite nuosavą FirebaseMessagingService, kurio negalite pertvarkyti, arba jei norite aiškiai valdyti, kuriuos FCM pristatymus mato Kixo.

A variantas — paveldėkite iš KixoFirebaseMessagingService (automatinis sekimas)

Paveldėkite iš KixoFirebaseMessagingService ir savo override'e iškvieskite super.onMessageReceived(...) — Kixo automatiškai išsiųs push_received (matomas payload) arba push_silent (tik duomenys). Bazinė klasė taip pat tvarko onNewToken registraciją, jei jos neperrašote. AndroidManifest.xml registracija nesiskiria nuo įprastos FCM tarnybos.

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 variantas — kvieskite rankinį API iš savo FCM tarnybos

Užregistruokite savo FCM žetoną Kixo per FirebaseMessagingService.onNewToken, tada kiekvieną pristatymą registruokite aiškiai. Šį kelią rinkitės, jei norite, kad Kixo matytų tik dalį FCM pristatymų. Šiuo metu Android pristatymas palaikomas tik per 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 nesiūlo universalaus gyvavimo ciklo kablio pranešimų atidarymui, atmetimui ar veiksmų mygtukams. Šiuos signalus perduokite iš jūsų programos kuriamų pranešimų intent arba receiver komponentų:

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

Sesijos atkūrimas

Atkurkite tikrą vaizdinę to, ką matė naudotojas, rekonstrukciją. Kiekvieno fiksavimo metu SDK užkoduoja suspaustą ekrano kadrą (JPEG vaizdą) kartu su rodinių hierarchijos struktūrine momentine kopija ir įkelia abu — kad valdymo skydelio grotuvas galėtų rodyti pikseliškai tikslų atkūrimą greta sąveikų laiko juostos. Projekto atkūrimo nustatymus konfigūruokite per Valdymo skydelis → Nustatymai → Sesijų atkūrimas. SDK šią projekto politiką, įskaitant maskavimą, fiksavimo režimus ir leidimą įkelti duomenis per mobilųjį ryšį, automatiškai nuskaito ir atnaujina.

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)

Kai įkėlimas per mobilųjį ryšį išjungtas, eilėje laukiantys atkūrimo duomenys bus siunčiami tik prisijungus prie leidžiamo tinklo.

Duomenų rinkimas

SDK fiksuoja projekte įjungtus duomenis, taip pat įvykius ir savybes, kurias siunčia jūsų programa.

Derinimas

Kixo.diagnostics() grąžina tik skaitymui skirtą SDK būsenos momentinę kopiją — praverčia paslėptame derinimo ekrane ar smoke teste. Padeda suprasti, kodėl įvykiai neteka, net ir be derintuvo.

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

Priverstinai paleiskite flush iš testų aplinkos — tinklo round-trip'ui gali blokuoti iki 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 maršrutai iš karto sukuria screen_view įvykius ir struktūrinius screen_visit įrašus su buvimo trukmės ir srauto metaduomenimis. Jei naudojate Jetpack Compose Navigation, kvieskite Kixo.screen iš LaunchedEffect, susieto su maršrutu — tada SDK matys po vieną įvykį kiekvienam tikslui, nepriklausomai nuo rekompozicijų skaičiaus.

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 programavimo agentai

SDK viešasis paviršius yra nedidelis ir pritaikytas code completion — visi metodai yra ant Kixo singleton, visi šiame gide esantys Kotlin pavyzdžiai prasideda nuo import io.kixo.sdk.Kixo, o mūsų README pateikia „AI agent quick reference“ bloką, kurį tokie įrankiai kaip Claude Code, Cursor ir Codex gali tiesiog įsikelti į savo kontekstą. Jei agentas užstringa, pradinis kanoninis variantas yra toks:

// 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."