Android SDK

Kixo Android SDK toetab Kotlin 2.0+ ja Java't, nõuab minSdk 24 (Android 7.0) ning on ehitatud vastu compileSdk 35. Sinu host-rakendus vastutab endiselt ise oma targetSdk eest. Üks Kixo.configure kutse sinu Application.onCreate sees hakkab automaatselt jälgima ekraane, puudutusi, seansse, krahhe ja elutsükli sündmusi. Push'i jälgimine vajab allpool kirjeldatud FCM bridge'i. Võrgupäringute automaatne jälgimine ei kuulu praegusesse Androidi väljalaskesse. SDK toetab ka seansitaasesitust, identiteeti ja eesmärke.

Kiire algus

Kolm faili. Lisa Maveni repo, lisa sõltuvus ja pane seejärel kaks rida oma Application alamklassi.

Koostamisnõuded: compileSdk 35, minSdk 24, Kotlin 2.0+ või Java ning Java 17 bytecode.

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

Lisa rakendusse

Kixo Maveni repositoorium asub GitHub Pagesis. Lisa see koos google() ja mavenCentral()-ga faili 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")
        }
    }
}

Seejärel deklareeri sõltuvus oma app-moodulis:

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

Mitme mooduliga projektid

Gradle'i konfiguratsioon implementation on ei ole transitiivne: kui deklareerid implementation("io.kixo:kixo-android-sdk:0.1.20") teegi moodulis (nt :core_domain), EI muutu Kixo nähtavaks moodulile :app ega ühelegi teisele tarbijale. Töötab kaks mustrit — vali üks.

Muster A — iga moodul, mis Kixo't kutsub, deklareerib selle ise (soovitatud). hoiab iga mooduli classpath'i minimaalsena ja väldib ahelreaktsiooni moodi ümberkompileerimisi. Kasuta version catalog'it (libs.kixo.sdk), siis muudad versiooni ainult ühest kohast.

// :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
}

Muster B — ekspordi see uuesti läbi api(...). Deklaratsioon on küll üks, kuid teegi mooduli avalik ABI hakkab nüüd sisaldama Kixo tüüpe — iga versioonimuudatus toob kaasa kõigi allavoolu moodulite ümberkompileerimise. Kasuta seda ainult siis, kui teek kasutab Kixo tüüpe oma avalikes signatuurides (näiteks tagastab funktsioonist 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
}

Initsialiseeri

Seadista Kixo oma Application alamklassis — onCreate käivitub enne ühtki activity't, nii et iga ekraanivaade, puudutus ja elutsükli sündmus salvestatakse alates esimesest kaadrist. Registreeri Application manifestis atribuudiga 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",
        )
    }
}

Kui vajad täpsemat häälestust — auto-track'i lipud, flush'i sagedus, taasesituse valim, kohandatud API host — ehita KixoConfiguration käsitsi:

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)

Jälgi sündmusi

Suurem osa instrumentatsioonist põhineb kolmel primitiivil: track sündmuste jaoks, markGoal konversioonisignaalide jaoks ja addBreadcrumb mittesündmusliku konteksti jaoks.

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

Standardsündmused

Mugavuskiht üle Kixo.track nende sündmuste jaoks, mille Kixo nime järgi ära tunneb — täpsed stringivõtmed, mida backend'i standardsündmuste tuvastaja vastendab. Saad compile-time'is kontrolli omaduste kuju üle ja ühe tõeallika nimede jaoks.

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)

Tuvasta kasutajad

Seo järgmised sündmused püsiva kasutaja ID ja tunnuste komplektiga. Anonüümse ja teadaoleva kasutaja kokkuviimine toimub Kixo sees — enne identify kogutud sündmused omistatakse tagantjärele samale kasutajale.

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

⚠️ Kotlini dollarimärgi lõks. Standardsed identiteedivõtmed kasutavad prefiksit $ ($email, $name, $first_name) — ja Kotlin stringiliteraalis peab dollarimärgi esitada kujul "\$email". Kui kirjutad "$email", interpoleeritakse sinna sinu muutuja email, nii et väärtus jõuab vaikselt tunnusena kohandatud ega täida Audience'i e-posti ega nime veerge. Lihtsaim parandus on kasutada tüübitud overload'i (SDK 0.1.13+), millega ei saa eksida: Kixo.setUserProperty(StandardProperty.EMAIL, email).

Märgista kasutaja segmenteerimiseks

Kasuta setUserProperty koos väärtusega boolean, et lisada kasutajale lihtne jah/ei-silt. Silt püsib üle rakenduse käivituste ja seda kasutavad segmendid, e-posti kampaaniad ning vestluspäringud — peale SDK kutse pole muud seadistust vaja.

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

Omadused salvestatakse läbi SharedPreferences, püsivad üle rakenduse käivituste ja lisatakse automaatselt igale väljaminevale sündmusele. Vestluses võid öelda näiteks "saada tervitusmeil kasutajatele, kellel subscribe on true" — Kixo loob siis sinu eest segmendi ja koostab malliteksti. Need tühjendatakse käsuga Kixo.reset().

Standardomaduste kataloog

Reserveeritud omaduste võtmetel on eesliide $, et need ei läheks segi sinu kohandatud tunnustega. Kixo kataloogis on 37 võtit: 3 universaalset pakki (identiteet, geo, elutsükkel) ja 5 B2B vertikaalpakki (tellimus, e-kaubandus, meedia, turg, lojaalsus). Määra need, mis sinu toote puhul kehtivad — töölaud kohandub ja kuvab ainult täidetud pakid.

Identiteet

Alati asjakohane. Määrab profiilipäise veerud.

Geo

Geograafiline kontekst.

Elutsükkel

Millal me neid nägime.

Tellimus

Määra see, kui sinu tootel on paketid.

E-kaubandus

Määra see, kui müüd tooteid.

Meedia

Määra see, kui avaldad sisu.

Turg

Määra see, kui sinu toode on kahepoolne platvorm.

Lojaalsus

Määra see kaasatus- ja preemiaprogrammide puhul.

Super-properties

Seansi võtme-väärtuse paarid, mis lisatakse automaatselt igale väljaminevale sündmusele. Need erinevad kasutaja identify tunnustest, mis kirjeldavad identiteeti; super-properties kirjeldavad seansi konteksti — aktiivne A/B variant, build flavor, lubatud funktsioonilipud. Need püsivad üle rakenduse käivituste ja tühjendatakse käsuga reset(). Kui tekib konflikt, jäävad peale sündmusepõhised properties väärtused, mis anti kaasa track juures.

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

Tõuketeavitused

Integratsiooniks on kaks teed. Vali A, kui kasutad FCM-i ja tahad kõige lühemat töötavat seadistust; vali B, kui sul on juba kohandatud FirebaseMessagingService, mida ei saa ümber teha, või kui tahad täpselt juhtida, milliseid FCM-i kohaletoimetamisi Kixo näeb.

Variant A — laienda KixoFirebaseMessagingService (automaatne jälgimine)

Laienda KixoFirebaseMessagingService ja kutsu oma override'i seest super.onMessageReceived(...) — Kixo saadab automaatselt push_received (nähtav payload) või push_silent (ainult andmed). Baasklass hoolitseb ka onNewToken registreerimise eest, kui sa seda ise üle ei kirjuta. AndroidManifest.xml registreerimine käib samamoodi nagu tavalises FCM teenuses.

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

Variant B — kutsu käsitsi API-d oma FCM teenusest

Registreeri oma FCM token Kixo's läbi FirebaseMessagingService.onNewToken ja logi seejärel iga kohaletoimetamine eraldi. Kasuta seda teed siis, kui soovid, et Kixo näeks ainult osa FCM-i kohaletoimetamistest. Androidi kohaletoimetamise tugi on praegu ainult FCM-i jaoks.

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 ei paku universaalset elutsükli hook'i teavituse avamise, sulgemise ega tegevusnuppude jaoks. Suuna need signaalid edasi teavituse intent'idest või receiver'itest, mille sinu rakendus loob:

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

Seansi taasesitus

Taasesita päris visuaalne rekonstruktsioon sellest, mida kasutaja nägi. Iga salvestuse juures kodeerib SDK ekraanist tihendatud kaadri (JPEG-pildi) koos vaatehierarhia struktuuritõmmisega ning laadib mõlemad üles — nii saab töölaua mängija kuvada pikslitäpse taasesituse koos interaktsioonide ajajoonega. Seadista projekti taasesitus asukohas Töölaud → Seaded → Sessiooni taasesitus. SDK loeb selle projektipoliitika automaatselt sisse ja värskendab seda jooksvalt, sealhulgas maskeerimist, salvestusrežiime ja mobiilside kaudu üleslaadimise õigust.

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)

Kui mobiilside kaudu üleslaadimine on keelatud, jääb järjekorras olev taasesitus ootama lubatud võrku.

Andmete kogumine

SDK kogub need andmed, mis on sinu projektis lubatud, ning need sündmused ja omadused, mida rakendus saadab.

Silumine

Kixo.diagnostics() tagastab SDK seisundi kirjutuskaitstud tõmmise — kasulik peidetud silumisvaates või smoke test'is. Aitab ilma debugger'ita vastata küsimusele „miks mu sündmused ei liigu?”.

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

Sunni testiharness'ist flush käima — see blokeerib kuni timeoutMs võrgu edasi-tagasi päringu ajaks:

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 route'id annavad kohe screen_view sündmused ning lisaks struktureeritud screen_visit kirjed koos ekraanil viibimise ja liikumiste metaandmetega. Kui kasutad Jetpack Compose Navigationit, kutsu Kixo.screen route'i järgi võtmetud LaunchedEffect seest — siis näeb SDK iga sihtkoha kohta üht sündmust, olenemata recomposition'ite arvust.

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

SDK avalik liides on väike ja kujundatud kooditäienduse jaoks — kõik meetodid asuvad singleton'il Kixo, kõik selle juhendi Kotlini näited algavad reaga import io.kixo.sdk.Kixo, ning meie README sisaldab plokki "AI agent quick reference", mille tööriistad nagu Claude Code, Cursor ja Codex saavad otse oma konteksti kleepida. Kui agent jänni jääb, alusta siit:

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