Android SDK

A Kixo Android SDK támogatja a Kotlin 2.0+ és a Java használatát, legalább minSdk 24-t igényel (Android 7.0), és compileSdk 35 ellen épül. A hostalkalmazás továbbra is maga felel a saját targetSdk értékéért. Egyetlen Kixo.configure hívás a(z) Application.onCreate osztályban automatikusan követi a képernyőket, koppintásokat, munkameneteket, összeomlásokat és életciklus-eseményeket. A push követéshez az alább ismertetett FCM-híd szükséges. A hálózati kérések automatikus követése nem része a jelenlegi Android kiadásnak. Az SDK a session replayt, az azonosítást és a célokat is támogatja.

Gyors kezdés

Három fájl. Add hozzá a Maven-tárat, vedd fel a függőséget, majd illessz be két sort a(z) Application leszármazottadba.

Buildkövetelmények: compileSdk 35, minSdk 24, Kotlin 2.0+ vagy Java, valamint Java 17-es bájtkód.

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

Hozzáadás az alkalmazáshoz

A Kixo Maven-tára GitHub Pagesen érhető el. Add hozzá a(z) google() és mavenCentral() mellé itt: 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")
        }
    }
}

Ezután deklaráld a függőséget az appmodulban:

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

Többmodulos projektek

A Gradle implementation konfigurációja nem tranzitív: ha a(z) implementation("io.kixo:kixo-android-sdk:0.1.20") függőséget egy könyvtármodulban, például a(z) :core_domain-ban deklarálod, attól a(z) Kixo NEM lesz látható a(z) :app vagy más fogyasztó számára. Két működő minta van — válassz egyet.

A minta — minden modul, amely Kixo-t hív, maga deklarálja (ajánlott). Alacsonyan tartja az egyes modulok classpathját, és elkerüli a láncreakciós újrafordításokat. Használj verziókatalógust (libs.kixo.sdk), így a verziót csak egy helyen kell módosítanod.

// :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 minta — újraexportálás api(...) segítségével. Egyetlen deklaráció elég, viszont a könyvtármodul publikus ABI-ja innentől Kixo-típusokat is tartalmaz — így minden verzióváltás újrafordítja az összes ráépülő modult. Csak akkor használd, ha a könyvtár a saját publikus szignatúráiban is Kixo-típusokat használ (például egy függvény KixoDiagnostics értéket ad vissza).

// :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álás

A Kixo konfigurálását a(z) Application leszármazottadban végezd el — a(z) onCreate minden activity előtt lefut, így már az első képkockától rögzül minden képernyőmegtekintés, koppintás és életciklus-esemény. A(z) Application elemet a manifestben a(z) android:name=".MyApp" használatával regisztráld.

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

Ha finomhangolható beállításokra van szükséged — például automatikus követési kapcsolókra, ürítési ütemre, replay mintavételezésre vagy egyéni API hostra — hozd létre külön a(z) KixoConfiguration példányt:

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)

Események követése

Az instrumentáció gerincét három alapelem adja: track az eseményekhez, markGoal a konverziós jelzésekhez, és addBreadcrumb a nem esemény jellegű kontextushoz.

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

Szabványos események

Kényelmi réteg a(z) Kixo.track fölött azokhoz az eseményekhez, amelyeket a Kixo név alapján felismer — pontos sztringkulcsokkal, amelyeket a backend szabványosesemény-felismerője egyeztet. Fordításkori ellenőrzés a tulajdonságok szerkezetére, és egyetlen névforrás az elnevezésekhez.

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)

Felhasználók azonosítása

A további eseményeket kösd egy stabil felhasználóazonosítóhoz és egy tulajdonságcsomaghoz. Az anonim és ismert felhasználó összefűzését a Kixo végzi — a(z) identify előtt rögzített események utólag ugyanahhoz a felhasználóhoz lesznek hozzárendelve.

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

⚠️ Kotlinos dollárjel-csapda. A szabványos azonosítókulcsok $ előtagot kapnak ($email, $name, $first_name) — Kotlin-literálban pedig kötelező escape-elned kell a dollárjelet így: "\$email". Ha "$email" kerül a kódba, az interpolálja a(z) email változót, ezért az érték észrevétlenül egyéni tulajdonságként landol, és sosem tölti ki az Audience e-mail- és névoszlopait. A legegyszerűbb megoldás: használd a tipizált overloadot (SDK 0.1.13+), ezt nem lehet elrontani: Kixo.setUserProperty(StandardProperty.EMAIL, email).

Felhasználó megjelölése szegmentáláshoz

A(z) setUserProperty hívást logikai érték értékkel használd, ha egy egyszerű igen/nem jelölést szeretnél a felhasználóhoz adni. A jelölés újraindítás után is megmarad, és használható szegmensekhez, e-mail-kampányokhoz és chatlekérdezésekhez — az SDK-híváson kívül nincs szükség további beállításra.

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

A tulajdonságok a(z) SharedPreferences használatával újraindítás után is megmaradnak, és automatikusan rákerülnek minden kimenő eseményre. Chatben mondhatsz például ilyet: "küldj üdvözlő e-mailt azoknak a felhasználóknak, akiknél a subscribe értéke true" — a Kixo elkészíti hozzá a szegmenst és megírja a sablon első változatát. A(z) Kixo.reset() törli őket.

Standard propertykatalógus

A fenntartott propertykulcsok $ előtagot kapnak, így elkülönülnek az egyedi traitjeidtől. A Kixo katalógusa 37 kulcsot tartalmaz: 3 univerzális csomagban (identity, geo, lifecycle) és 5 B2B vertikális csomagban (subscription, e-commerce, media, marketplace, loyalty). Azokat állítsd be, amelyek a termékedre vonatkoznak — a dashboard ehhez igazodik, és csak a kitöltött csomagokat jeleníti meg.

Azonosítás

Mindig releváns. A profilfejléc oszlopait állítja be.

Földrajzi adatok

Földrajzi kontextus.

Életciklus

Mikor láttuk.

Előfizetés

Állítsd be, ha a terméked csomagokat használ.

E-kereskedelem

Állítsd be, ha termékeket értékesítetek.

Média

Állítsd be, ha tartalmat publikáltok.

Piactér

Állítsd be, ha a terméked kétoldalú platform.

Hűségprogram

Állítsd be, ha elköteleződési vagy jutalmazási programot használtok.

Super-properties

Munkamenetenkénti kulcs-érték párok, amelyek automatikusan rákerülnek minden kimenő eseményre. Nem azonosak a(z) identify tulajdonságokkal, amelyek az identitást írják le; a super propertyk a munkamenet kontextusát adják meg — például az aktív A/B variánst, a build flavo(u)rt vagy az engedélyezett feature flageket. Az alkalmazás újraindítása után is megmaradnak; a(z) reset() törli őket. Ütközés esetén a(z) track hívásban megadott eseményszintű properties mindig elsőbbséget élvez.

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értesítések

Két integrációs út van. Válaszd az A-t, ha FCM-et használsz, és a lehető legrövidebb működő beállítást szeretnéd; válaszd a B-t, ha már van saját FirebaseMessagingService osztályod, amit nem tudsz átalakítani, vagy ha pontosan szabályoznád, mely FCM-kézbesítéseket lássa a Kixo.

A lehetőség — a(z) KixoFirebaseMessagingService kiterjesztése (automatikus követés)

Származtasd a(z) KixoFirebaseMessagingService osztályt, és a felülírásból hívd meg a(z) super.onMessageReceived(...) függvényt — a Kixo automatikusan elküldi a(z) push_received eseményt látható payload esetén, illetve a(z) push_silent eseményt csak adatot tartalmazó üzenetnél. Az alaposztály a(z) onNewToken regisztrációt is kezeli, ha ezt nem írod felül. A(z) AndroidManifest.xml regisztráció ugyanaz, mint egy szokásos FCM service esetén.

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 lehetőség — manuális API-hívás a saját FCM service-ből

Regisztráld az FCM-tokenedet a Kixo-nál a(z) FirebaseMessagingService.onNewToken használatával, majd minden kézbesítést külön naplózz. Ezt az utat akkor válaszd, ha azt szeretnéd, hogy a Kixo csak az FCM-kézbesítések egy részét lássa. Androidon a kézbesítéskövetés jelenleg csak FCM-mel támogatott.

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

Androidon nincs általános életciklus-hook az értesítések megnyitásához, elutasításához vagy műveletgombjaihoz. Ezeket a jeleket az alkalmazásod által létrehozott értesítési intentekből vagy receiverekből kell továbbítanod:

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

Munkamenet-visszajátszás

Játssz vissza egy valós, vizuális rekonstrukciót arról, mit látott a felhasználó. Minden rögzítéskor az SDK a képernyőről egy tömörített képkockát kódol (JPEG képként), a nézethierarchiáról pedig egy strukturális pillanatképet készít, majd mindkettőt feltölti — így a dashboard lejátszója képponthű visszajátszást tud megjeleníteni az interakciós idővonal mellett. A replay projektszintű beállításait itt adhatod meg: Vezérlőpult → Beállítások → Munkamenet-visszajátszás. Az SDK ezt a projektszabályzatot automatikusan beolvassa és frissíti, beleértve a maszkolást, a rögzítési módokat és a mobilhálózatos feltöltés engedélyét is.

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)

Ha a mobilhálózatos feltöltés ki van kapcsolva, a sorban álló replay megvárja az engedélyezett hálózatot.

Adatgyűjtés

Az SDK a projektben engedélyezett adatokat, valamint az alkalmazás által küldött eseményeket és tulajdonságokat rögzíti.

Hibakeresés

A(z) Kixo.diagnostics() az SDK állapotáról ad egy csak olvasható pillanatképet — hasznos rejtett hibakereső képernyőn vagy smoke tesztben. Debugger nélkül is megmondja, miért nem érkeznek az események.

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

Kényszeríts ürítést a tesztkörnyezetből — egy hálózati oda-vissza út idejére, legfeljebb timeoutMs-ig blokkol:

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

Az Activity- és Fragment-útvonalak azonnal létrehozzák a(z) screen_view eseményeket és a strukturált screen_visit rekordokat, a tartózkodási időre és a folyamatra vonatkozó metaadatokkal együtt. Jetpack Compose Navigation használatakor a(z) Kixo.screen hívást egy útvonalhoz kötött LaunchedEffect blokkból indítsd — így az SDK célállomásonként egy eseményt lát, függetlenül a recompositionök számától.

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 kódolási ügynökök

Az SDK publikus felülete kicsi, és kódkiegészítésre van hangolva: minden metódus a(z) Kixo singletonon érhető el, ebben az útmutatóban minden Kotlin-példa ezzel kezdődik: import io.kixo.sdk.Kixo, a(z) README pedig tartalmaz egy „AI agent quick reference” blokkot, amelyet az olyan eszközök, mint a Claude Code, a Cursor és a Codex közvetlenül beilleszthetnek a saját kontextusukba. Ha az ügynök elakad, ez a kanonikus kiindulópont:

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