Android SDK

Kixo Android SDK podporuje Kotlin 2.0+ aj Javu, vyžaduje minSdk 24 (Android 7.0) a je zostavené proti compileSdk 35. Vaša hostiteľská aplikácia si naďalej spravuje vlastné targetSdk. Jediné volanie Kixo.configure vo vašej triede Application.onCreate automaticky sleduje obrazovky, ťuknutia, relácie, pády a udalosti životného cyklu. Sledovanie push notifikácií vyžaduje nižšie opísaný FCM bridge. Automatické sledovanie sieťových požiadaviek zatiaľ nie je súčasťou aktuálneho vydania pre Android. SDK podporuje aj replay relácií, identitu a ciele.

Rýchly štart

Tri súbory. Pridajte Maven repozitár, pridajte závislosť a potom vložte dva riadky do svojej podtriedy Application.

Požiadavky na build: compileSdk 35, minSdk 24, Kotlin 2.0+ alebo Java a bytecode pre 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")
        }
    }
}

Pridajte do aplikácie

Kixo Maven repozitár je hostovaný na GitHub Pages. Pridajte ho vedľa google() a 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")
        }
    }
}

Potom deklarujte závislosť v module aplikácie:

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

Viacmodulové projekty

Konfigurácia implementation v Gradle je nie je tranzitívna: ak v knižničnom module, napríklad v :core_domain, deklarujete implementation("io.kixo:kixo-android-sdk:0.1.20"), Kixo sa tým NESPRÍSTUPNÍ pre :app ani pre žiadneho iného konzumenta. Fungujú dva prístupy — vyberte si jeden.

Pattern A — každý modul, ktorý volá Kixo, si ho deklaruje sám (odporúčané). Udrží classpath každého modulu čo najmenší a zabráni reťazovým rebuildom. Použite version catalog (libs.kixo.sdk), aby ste verziu menili len na jednom mieste.

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

Pattern B — re-export cez api(...). Jedna deklarácia, ale verejné ABI knižničného modulu tým začne obsahovať typy Kixo — každá zmena verzie potom vyvolá rebuild všetkých nadväzujúcich modulov. Použite to len vtedy, keď knižnica používa typy Kixo aj vo vlastných verejných signatúrach, napríklad ak funkcia vracia 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
}

Inicializácia

Kixo nakonfigurujte vo svojej podtriede Application — onCreate sa spustí ešte pred prvou activity, takže každé zobrazenie obrazovky, ťuknutie aj udalosť životného cyklu sa zachytí od prvého frameu. Application zaregistrujte v manifeste cez 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",
        )
    }
}

Ak potrebujete jemnejšie nastavenie — príznaky automatického sledovania, interval flushovania, vzorkovanie replayu alebo vlastný API host — vytvorte KixoConfiguration explicitne:

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)

Sledovanie udalostí

Väčšinu instrumentácie pokrývajú tri základné primitíva: track pre udalosti, markGoal pre konverzné signály a addBreadcrumb pre kontext mimo udalostí.

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

Štandardné udalosti

Pohodlná vrstva nad Kixo.track pre udalosti, ktoré Kixo rozpoznáva podľa názvu — teda presné reťazcové kľúče, na ktoré sa zhoduje backendový detektor štandardných udalostí. Získate kontrolu tvaru vlastností pri kompilácii a jeden zdroj pravdy pre názvy.

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)

Identifikácia používateľov

Naviažte ďalšie udalosti na stabilné ID používateľa a sadu traits. Prepojenie anonymného a známeho používateľa prebieha v Kixo — udalosti zachytené pred identify sa spätne priradia tomu istému používateľovi.

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

⚠️ Pasca so znakom dolára v Kotline. Štandardné identifikačné kľúče majú prefix $ ($email, $name, $first_name) — a v literáli v Kotline musíte znak dolára escapovať ako "\$email". Ak napíšete "$email", vykoná sa interpolácia vašej premennej email, takže hodnota sa potichu uloží ako trait vlastné a nikdy nevyplní stĺpce e-mail / meno v Audience. Najjednoduchšia oprava je použiť typované preťaženie (SDK 0.1.13+), pri ktorom sa to nedá pokaziť: Kixo.setUserProperty(StandardProperty.EMAIL, email).

Označte používateľa na segmentáciu

Použite setUserProperty s hodnotou boolean, ak chcete používateľovi priradiť jednoduchý príznak áno/nie. Tento príznak zostane zachovaný aj po ďalších spusteniach a môžete ho hneď použiť v segmentoch, e-mailových kampaniach aj dopytoch v chate — bez ďalšieho nastavovania, stačí volanie 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",
))

Vlastnosti uložené cez SharedPreferences zostávajú zachované aj po ďalších spusteniach a automaticky sa pripájajú ku každej odoslanej udalosti. V chate môžete napísať napríklad "pošli uvítací e-mail používateľom, pre ktorých subscribe je true" — Kixo za vás vytvorí segment aj návrh šablóny. Vymažú sa pri Kixo.reset().

Katalóg štandardných vlastností

Vyhradené kľúče vlastností majú prefix $, takže sú oddelené od vašich vlastných traits. Katalóg Kixo obsahuje 37 kľúčov v 3 univerzálnych balíkoch (identita, geo, životný cyklus) a 5 B2B vertikálnych balíkoch (predplatné, e-commerce, médiá, trhovisko, vernosť). Nastavte tie, ktoré sa hodia pre váš produkt — dashboard sa prispôsobí a zobrazí len balíky, ktoré vyplníte.

Identita

Vždy relevantné. Nastavuje stĺpce v hlavičke profilu.

Geo

Geografický kontext.

Životný cyklus

Kedy sme ho videli.

Predplatné

Nastavte, ak má váš produkt plány.

E-commerce

Nastavte, ak predávate produkty.

Médiá

Nastavte, ak publikujete obsah.

Trhovisko

Nastavte, ak je váš produkt obojstranná platforma.

Vernosť

Nastavte, ak používate vernostné alebo odmeňovacie programy.

Super-properties

Páry kľúč/hodnota viazané na reláciu, ktoré sa automaticky pripájajú ku každej odchádzajúcej udalosti. Na rozdiel od traits identify, ktoré opisujú identitu, super-properties opisujú kontext relácie — napríklad aktívny A/B variant, build flavor alebo zapnuté feature flagy. Pretrvávajú aj medzi spusteniami aplikácie; vymažú sa pri reset(). Ak dôjde ku kolízii, vždy majú prednosť per-event properties v track.

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 notifikácie

Máte dve možnosti integrácie. Zvoľte A, ak používate FCM a chcete čo najkratšie funkčné nastavenie. Zvoľte B, ak už máte vlastnú FirebaseMessagingService, ktorú nemôžete prerobiť, alebo chcete mať presnú kontrolu nad tým, ktoré doručenia cez FCM Kixo uvidí.

Možnosť A — rozšírte KixoFirebaseMessagingService (automatické sledovanie)

Rozšírte KixoFirebaseMessagingService a vo svojej implementácii zavolajte super.onMessageReceived(...) — Kixo automaticky odošle push_received (viditeľný payload) alebo push_silent (iba dátový payload). Základná trieda spracuje aj registráciu onNewToken, ak ju neprepíšete. Registrácia AndroidManifest.xml zostáva rovnaká ako pri bežnej FCM službe.

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žnosť B — volajte manuálne API z vlastnej FCM služby

Zaregistrujte svoj FCM token v Kixo cez FirebaseMessagingService.onNewToken a potom každé doručenie zaznamenajte explicitne. Tento postup použite, ak má Kixo vidieť len vybranú časť doručení cez FCM. Doručovanie na Android momentálne podporuje iba 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 neposkytuje univerzálny hook životného cyklu pre otvorenia notifikácií, ich zavretia ani akčné tlačidlá. Tieto signály preto prepošlite z notification intentov alebo receiverov, ktoré vytvára vaša aplikácia:

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

Replay relácií

Prehrajte si verný vizuálny záznam toho, čo používateľ videl. Pri každom zachytení SDK zakóduje komprimovaný snímok obrazovky (obrázok JPEG) spolu so štruktúrnym snímkom hierarchie zobrazení a odošle oboje — prehrávač v dashboarde tak dokáže vykresliť pixelovo presný záznam popri časovej osi interakcií. Replay pre projekt nastavíte v Prehľad → Nastavenia → Prehrávanie relácií. SDK si túto projektovú politiku automaticky načítava aj obnovuje vrátane maskovania, režimov zachytávania a povolenia odosielania cez mobilnú sieť.

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)

Ak je odosielanie cez mobilnú sieť vypnuté, replay zostane vo fronte, kým nebude dostupná povolená sieť.

Zber dát

SDK zachytáva údaje, ktoré máte v projekte povolené, aj udalosti a vlastnosti, ktoré odosiela vaša aplikácia.

Ladenie

Kixo.diagnostics() vráti snapshot stavu SDK len na čítanie — hodí sa do skrytej debug obrazovky aj do smoke testu. Bez debuggera vám povie, prečo udalosti netečú.

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

Vynúťte flush z test harnessu — počas sieťového round-tripu blokuje až na 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

Trasy Activity / Fragment okamžite vytvoria udalosti screen_view a zároveň aj štruktúrované záznamy screen_visit s metadátami o dĺžke zobrazenia a pohybe medzi obrazovkami. Pri Jetpack Compose Navigation volajte Kixo.screen z LaunchedEffect naviazaného na route — SDK potom uvidí jednu udalosť pre každú destináciu bez ohľadu na počet rekompozícií.

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 asistenti na písanie kódu

Verejné API SDK je malé a navrhnuté tak, aby sa s ním dobre pracovalo cez našeptávanie v editore — všetky metódy sú na singletone Kixo, každá ukážka v Kotlin v tomto návode začína import io.kixo.sdk.Kixo a náš README obsahuje blok „AI agent quick reference“, ktorý si nástroje ako Claude Code, Cursor a Codex vedia vložiť priamo do kontextu. Ak sa agent zasekne, začnite týmto overeným základom:

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