Android SDK

Kixo Android SDK podpira Kotlin 2.0+ in Javo, zahteva minSdk 24 (Android 7.0) in je zgrajen proti compileSdk 35. Vaša gostiteljska aplikacija ostaja sama odgovorna za svoj targetSdk. En sam klic Kixo.configure v vašem Application.onCreate samodejno beleži zaslone, dotike, seje, zrušitve in dogodke življenjskega cikla. Sledenje potisnim obvestilom zahteva spodaj opisani most za FCM. Samodejno sledenje omrežnim zahtevam trenutno ni del izdaje za Android. SDK podpira tudi replay sej, identiteto in cilje.

Hitri začetek

Tri datoteke. Dodajte repozitorij Maven, dodajte odvisnost, nato pa v svoj podrazred Application vstavite dve vrstici.

Zahteve za gradnjo: compileSdk 35, minSdk 24, Kotlin 2.0+ ali Java ter 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")
        }
    }
}

Dodajte v svojo aplikacijo

Repozitorij Kixo Maven gostuje na GitHub Pages. Dodajte ga poleg google() in mavenCentral() v 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")
        }
    }
}

Nato v modulu aplikacije deklarirajte odvisnost:

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

Večmodulni projekti

Konfiguracija implementation v Gradle je ni tranzitivno: če v modulu knjižnice (na primer :core_domain) deklarirate implementation("io.kixo:kixo-android-sdk:0.1.20"), to NE pomeni, da bo Kixo viden v :app ali kateremu koli drugemu porabniku. Delujeta dva pristopa — izberite enega.

Vzorec A — vsak modul, ki kliče Kixo, ga tudi deklarira (priporočeno). ohrani classpath posameznega modula čim manjši in prepreči verižno ponovno gradnjo. Uporabite katalog različic (libs.kixo.sdk), da različico urejate na enem mestu.

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

Vzorec B — ponovni izvoz prek api(...). Ena sama deklaracija, vendar javni ABI modula knjižnice odslej vključuje tipe Kixo — vsak dvig različice zato sproži ponovno gradnjo vseh odvisnih modulov. To uporabite le, če knjižnica tipe Kixo uporablja tudi v svojih javnih podpisih, na primer ko funkcija vrne 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
}

Inicializacija

Kixo nastavite v podrazredu Application — onCreate se izvede pred katero koli activity, zato se vsak ogled zaslona, dotik in dogodek življenjskega cikla zajamejo že od prve sličice. V manifestu registrirajte Application z 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",
        )
    }
}

Za natančnejše nastavitve (zastavice samodejnega sledenja, ritem pošiljanja, vzorčenje replaya, gostitelj API po meri) KixoConfiguration sestavite izrecno:

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)

Beleženje dogodkov

Večino vaše instrumentacije pokrivajo trije gradniki: track za dogodke, markGoal za signale konverzije in addBreadcrumb za kontekst, ki ni vezan na dogodek.

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

Standardni dogodki

Tanka plast nad Kixo.track za dogodke, ki jih Kixo prepozna po imenu — dobesedni nizovni ključi, ki se ujemajo z detektorjem standardnih dogodkov v zaledju. Oblika lastnosti je preverjena med prevajanjem, poimenovanje pa ima en sam vir resnice.

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)

Identificirajte uporabnike

Naslednje dogodke povežite s stabilnim ID-jem uporabnika in naborom lastnosti. Povezovanje anonimnega in prepoznanega uporabnika se izvede v Kixo — dogodki, zajeti pred identify, se za nazaj pripišejo istemu uporabniku.

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

⚠️ Past z znakom dolarja v Kotlinu. Standardni identitetni ključi imajo predpono $ ($email, $name, $first_name) — v dobesednem nizu v Kotlinu pa mora znak dolarja ubežati kot "\$email". Če napišete "$email", se interpolira vrednost spremenljivke email, zato ta tiho pristane kot lastnost po meri in nikoli ne zapolni stolpcev Audience za e-pošto ali ime. Najpreprostejši popravek je tipizirana preobremenitev (SDK 0.1.13+), pri kateri se ne morete zmotiti: Kixo.setUserProperty(StandardProperty.EMAIL, email).

Označite uporabnika za segmentacijo

Uporabite setUserProperty z vrednostjo logična vrednost, da uporabniku dodate preprosto oznako da/ne. Oznaka se ohrani med zagoni in se uporablja v segmentih, e-poštnih kampanjah ter poizvedbah v klepetu — brez dodatnih nastavitev, samo s klicem 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",
))

Lastnosti se prek SharedPreferences ohranijo med zagoni in se samodejno pripnejo vsakemu odhodnemu dogodku. V Kixo Chat lahko napišete na primer "pošlji pozdravno e-pošto uporabnikom, pri katerih je subscribe nastavljen na true" — Kixo za vas sestavi segment in pripravi osnutek predloge. Počistijo se ob Kixo.reset().

Katalog standardnih lastnosti

Rezervirani ključi lastnosti imajo predpono $, zato so ločeni od vaših lastnosti po meri. Kixo vključuje 37 ključev v 3 univerzalnih paketih (identiteta, geo, življenjski cikel) in 5 B2B vertikalnih paketih (naročnine, e-trgovina, mediji, tržnica, zvestoba). Nastavite samo tiste, ki veljajo za vaš izdelek — nadzorna plošča se prilagodi in prikaže le pakete, ki jih uporabljate.

Identiteta

Vedno relevantno. Določa stolpce v glavi profila.

Geo

Geografski kontekst.

Življenjski cikel

Kdaj smo ga zaznali.

Naročnina

Nastavite, če ima vaš izdelek pakete.

E-trgovina

Nastavite, če prodajate izdelke.

Mediji

Nastavite, če objavljate vsebine.

Tržnica

Nastavite, če je vaš izdelek dvostranska platforma.

Zvestoba

Nastavite, če uporabljate programe angažiranja in nagrajevanja.

Superlastnosti

Pari ključ/vrednost na ravni seje, ki se samodejno pripnejo vsakemu odhodnemu dogodku. Za razliko od lastnosti identify, ki opisujejo identiteto, superlastnosti opisujejo kontekst seje — aktivno različico A/B, variantno gradnjo in vključene zastavice funkcij. Ohranijo se med zagoni in se počistijo ob reset(). Če pride do prekrivanja, imajo lastnosti dogodka properties v track vedno prednost.

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

Potisna obvestila

Na voljo sta dve poti integracije. Izberite A, če uporabljate FCM in želite najkrajšo delujočo nastavitev; izberite B, če že imate prilagojen FirebaseMessagingService, ki ga ne morete preurediti, ali če želite natančen nadzor nad tem, katere dostave FCM vidi Kixo.

Možnost A — razširite KixoFirebaseMessagingService (samodejno sledenje)

Razširite KixoFirebaseMessagingService in iz svoje prepisane metode pokličite super.onMessageReceived(...) — Kixo samodejno odda push_received (vidna vsebina) ali push_silent (samo podatki). Osnovni razred poskrbi tudi za registracijo onNewToken, če je ne prepišete. Registracija AndroidManifest.xml ostane enaka kot pri običajni storitvi 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
    }
}

Možnost B — iz lastne storitve FCM pokličite ročni API

Svoj FCM token registrirajte v Kixo prek FirebaseMessagingService.onNewToken, nato pa vsako dostavo zabeležite posebej. To pot izberite, če želite, da Kixo vidi le del dostav FCM. Dostava na Android trenutno podpira samo 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 ne ponuja enotne kljuke življenjskega cikla za odpiranje obvestil, opustitve ali gumbe dejanj. Te signale zato posredujte iz intentov obvestil ali receiverjev, ki jih ustvari vaša aplikacija:

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

Posnetek seje

Predvajajte dejansko vizualno rekonstrukcijo tega, kar je videl uporabnik. SDK pri vsakem zajemu zakodira stisnjeno sličico zaslona (sliko JPEG) skupaj s strukturnim posnetkom hierarhije pogledov in naloži oboje — tako lahko predvajalnik v nadzorni plošči prikaže pikselno natančen posnetek ob časovnici interakcij. Replay za projekt nastavite v Nadzorna plošča → Nastavitve → Posnetki sej. SDK to projektno politiko samodejno bere in osvežuje, vključno z maskiranjem, načini zajema in dovoljenjem za nalaganje prek mobilnega omrežja.

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)

Če je nalaganje prek mobilnega omrežja izklopljeno, replay v čakalni vrsti počaka na dovoljeno omrežje.

Zbiranje podatkov

SDK zajame podatke, ki so v vašem projektu omogočeni, ter dogodke in lastnosti, ki jih pošilja aplikacija.

Razhroščevanje

Kixo.diagnostics() vrne posnetek zdravja SDK samo za branje — uporaben na skritem razhroščevalnem zaslonu ali v smoke testu. Brez razhroščevalnika odgovori na vprašanje »zakaj moji dogodki ne tečejo?«.

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

Iz testnega ogrodja sprožite flush na silo — klic blokira do timeoutMs, kolikor traja en omrežni krog:

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

Poti Activity / Fragment takoj ustvarijo dogodke screen_view in strukturirane zapise screen_visit s podatki o zadrževanju in toku, brez dodatnih nastavitev. Pri Jetpack Compose Navigation prožite Kixo.screen iz LaunchedEffect, vezanega na pot; SDK bo tako za vsak cilj videl en dogodek ne glede na število rekompozicij.

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 agenti za programiranje

Javna površina SDK je majhna in prilagojena dopolnjevanju kode — vse metode so na singletonu Kixo, vsak primer v Kotlinu v tem vodiču se začne z import io.kixo.sdk.Kixo, naš README pa vsebuje blok »AI agent quick reference«, ki ga lahko orodja, kot so Claude Code, Cursor in Codex, neposredno prilepijo v svoj kontekst. Če se agent zatakne, začnite s tem:

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