Android SDK

Kixo Android SDK-k Kotlin 2.0+ eta Java onartzen ditu, minSdk 24 behar du (Android 7.0), eta compileSdk 35-ren gainean eraikita dago. Zure host aplikazioak bere targetSdk propioaren ardura izaten jarraitzen du. Application.onCreate barruan egindako Kixo.configure dei bakar batek automatikoki erregistratzen ditu pantailak, ukituak, saioak, kraskadurak eta bizi-zikloaren gertaerak. Push jarraipenak behean azaltzen den FCM zubia behar du. Sareko eskaeren jarraipen automatikoa ez dago egungo Android bertsioan. SDK-k saioaren erreprodukzioa, identitatea eta helburuak ere onartzen ditu.

Hasiera azkarra

Hiru fitxategi. Gehitu Maven biltegia, gehitu mendekotasuna, eta gero sartu bi lerro zure Application azpiklasean.

Eraikitzeko eskakizunak: compileSdk 35, minSdk 24, Kotlin 2.0+ edo Java, eta Java 17 bytecode-a.

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

Gehitu zure aplikazioan

Kixo Maven biltegia GitHub Pages-en dago ostatatuta. Gehitu google() eta mavenCentral() biltegien ondoan, settings.gradle.kts fitxategian:

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

Ondoren, deklaratu mendekotasuna zure app moduluan:

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

Modulu anitzeko proiektuak

Gradle-ko implementation konfigurazioa ez da transitiboa da: liburutegi-modulu batean implementation("io.kixo:kixo-android-sdk:0.1.20") deklaratzeak (adibidez, :core_domain) EZ du Kixo ikusgai jartzen :app-rentzat edo beste edozein kontsumitzailerentzat. Bi eredu hauek funtzionatzen dute; aukeratu bat.

A eredua — Kixo deitzen duen modulu bakoitzak bere mendekotasuna deklaratzen du (gomendatua). erabilita, modulu bakoitzaren classpath-a ahalik eta txikiena izaten da eta kateko berreraikuntzak saihesten dira. Erabili bertsio-katalogo bat (libs.kixo.sdk) bertsioa toki bakarrean eguneratzeko.

// :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 eredua — berriz esportatu api(...) bidez. Adierazpen bakarra da, baina liburutegi-moduluaren ABI publikoak orain Kixo motak ere barne hartzen ditu; bertsio-aldaketa orok beherako modulu guztiak berreraikitzea eragiten du. Erabili hau bakarrik liburutegiak Kixo motak bere sinadura publikoetan berrerabiltzen baditu (adibidez, funtzio batek KixoDiagnostics itzultzen badu).

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

Hasieratu

Konfiguratu Kixo zure Application azpiklasean. onCreate edozein activity baino lehen exekutatzen da; horri esker, lehen fotogramatik bertatik kapturatzen dira pantaila-ikustaldiak, ukituak eta bizi-zikloaren gertaerak. Erregistratu Application zure manifestuan android:name=".MyApp" erabilita.

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

Doikuntza xeheagoak behar badituzu — auto-track banderak, hustutze-maiztasuna, replay laginketa edo API ostalari pertsonalizatua — eraiki KixoConfiguration esplizituki:

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)

Erregistratu gertaerak

Hiru primitibok eramaten dute zure instrumentazioaren zatirik handiena: track gertaeretarako, markGoal bihurketa-seinaleetarako, eta addBreadcrumb gertaera ez den testuingururako.

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

Gertaera estandarrak

Kixo.track gaineko azukre-geruza da, Kixo-k izenaren arabera ezagutzen dituen gertaeretarako: backendeko gertaera estandarren detektagailuak hitzez hitz parekatzen dituen string gakoak. Propietateen egituraren balidazioa konpilazioan ematen du, eta izendapenerako egia-iturburu bakarra eskaintzen du.

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)

Identifikatu erabiltzaileak

Lotu ondorengo gertaerak erabiltzaile-id egonkor bati eta trait multzo bati. Ezezagunetik ezagunerako lotura Kixo-n egiten da: identify baino lehen kapturatutako gertaerak atzeraeraginez erabiltzaile berari esleitzen zaizkio.

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-en dolarraren tranpa. Identitate-gako estandarrak $ aurrizkiarekin doaz ($email, $name, $first_name); eta Kotlin literal batean behar du behar duzu dolarraren ikurra "\$email" gisa ihes egiteko. "$email" idazten baduzu, zure email aldagaia string interpolation bidez txertatzen da; ondorioz, balioa isilean pertsonalizatua trait gisa gordetzen da eta ez ditu inoiz Audience ataleko email edo name zutabeak betetzen. Konponbiderik errazena typed overload-a erabiltzea da (SDK 0.1.13+); hori gaizki erabiltzea ezinezkoa da: Kixo.setUserProperty(StandardProperty.EMAIL, email).

Etiketatu erabiltzailea segmentatzeko

Erabili setUserProperty boolean balioarekin, erabiltzaileari bai/ez etiketa sinple bat eransteeko. Etiketak aplikazioaren abiarazte batetik bestera irauten du, eta segmentuak, email kanpainak eta chat kontsultak elikatzen ditu; ez da beste ezer konfiguratu behar, SDK-ko deia egitea besterik ez.

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

Propietateak SharedPreferences bidez gordetzen dira aplikazioaren abiarazte batetik bestera, eta kanpora bidalitako gertaera guztiei automatikoki eransten zaizkie. Chat-ean honelakoak esan ditzakezu: "bidali ongietorriko mezu elektroniko bat subscribe true duten erabiltzaileei"; Kixo-k segmentua sortu eta txantiloia prestatuko dizu. Kixo.reset() egitean garbitzen dira.

Propietate estandarren katalogoa

Erreserbatutako property key-ek $ aurrizkia daramate, zure trait pertsonalizatuetatik bereizteko. Kixo-ren katalogoak 37 gako biltzen ditu: 3 pakete unibertsaletan (identity, geo, lifecycle) eta 5 B2B pakete bertikaletan (subscription, e-commerce, media, marketplace, loyalty). Ezarri zure produktuari dagozkionak; dashboardak automatikoki egokitzen du ikuspegia, eta bete dituzun paketeak bakarrik erakusten ditu.

Identitatea

Beti da garrantzitsua. Profile header-eko zutabeak ezartzen ditu.

Geo

Testuinguru geografikoa.

Bizi-zikloa

Noiz ikusi genuen.

Subscription

Ezarri zure produktuak planak baditu.

E-commerce

Ezarri produktuak saltzen badituzu.

Media

Ezarri edukia argitaratzen baduzu.

Marketplace

Ezarri bi aldeko plataforma bazara.

Leialtasuna

Engagement eta sari programetarako.

Super-properties

Saioko gako/balio bikoteak dira, kanpora bidaltzen den gertaera bakoitzari automatikoki eransten zaizkionak. Ez dira identify trait-en berdinak — haiek identitatea deskribatzen dute; super-properties-ek, berriz, saioko testuingurua deskribatzen dute: A/B aldaera aktiboa, build flavor-a edo gaitutako feature flag-ak. Aplikazioa berrabiarazi arren mantentzen dira; reset() egitean garbitzen dira. track deiko gertaera bakoitzeko properties balioek beti dute lehentasuna gatazkan.

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 jakinarazpenak

Bi integrazio-bide daude. Aukeratu A, FCM erabiltzen baduzu eta ahalik eta konfigurazio laburrena nahi baduzu; aukeratu B, lehendik berrantolatu ezin duzun FirebaseMessagingService pertsonalizatua baduzu edo Kixo-k zein FCM bidalketa ikusten dituen zehazki kontrolatu nahi baduzu.

A aukera — zabaldu KixoFirebaseMessagingService (jarraipen automatikoa)

Sortu KixoFirebaseMessagingService-ren azpiklase bat eta deitu super.onMessageReceived(...) zure override barrutik; Kixo-k automatikoki bidaltzen du push_received (payload ikusgaia) edo push_silent (datu hutsekoa). Oinarrizko klaseak onNewToken erregistroa ere kudeatzen du, override egiten ez baduzu. AndroidManifest.xml erregistroak ez du aldaketarik FCM service arrunt batekin alderatuta.

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 aukera — deitu eskuzko APIari zure FCM service propioan

Erregistratu zure FCM token-a Kixo-n FirebaseMessagingService.onNewToken bidez, eta ondoren erregistratu bidalketa bakoitza esplizituki. Erabili bide hau Kixo-k FCM bidalketen azpimultzo bat bakarrik ikustea nahi baduzu. Android-eko bidalketek gaur egun FCM bakarrik onartzen dute.

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-ek ez du bizi-zikloaren hook unibertsalik eskaintzen jakinarazpenen irekierak, baztertzeak edo ekintza-botoiak jasotzeko. Bidali seinale horiek zure aplikazioak sortzen dituen jakinarazpen-intent edo receiver-etatik:

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

Saioen erreprodukzioa

Erreproduzitu erabiltzaileak ikusi zuenaren berreraikuntza bisual erreal bat. Kaptura bakoitzean, SDK-k pantailaren fotograma konprimitu bat kodetzen du (JPEG irudi bat), ikuspegi-hierarkiaren egiturazko argazkiarekin batera, eta biak igotzen ditu. Horrela, dashboardeko erreproduzigailuak pixel-mailako erreprodukzio zehatza eman dezake elkarreraginen kronologiarekin batera. Konfiguratu replay proiektu-mailan Aginte-panela → Ezarpenak → Saioaren berrerreprodukzioa atalean. SDK-k automatikoki irakurri eta freskatzen du proiektuaren politika hori, maskaratzea, kaptura moduak eta sare mugikorraren bidez igotzeko baimena barne.

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)

Sare mugikorraren bidez igotzea desgaituta badago, ilaran dagoen replay-a baimendutako sare baten zain geratzen da.

Datu-bilketa

SDK-k zure proiektuan gaituta dauden datuak eta zure aplikazioak bidaltzen dituen gertaerak eta propietateak kapturatzen ditu.

Arazketa

Kixo.diagnostics() funtzioak SDK-ren osasunaren irakurtzeko soilik den argazki bat itzultzen du. Oso erabilgarria da ezkutuko debug pantaila batean edo smoke test batean. Araztaile bat erabili gabe erantzuten du: "zergatik ez dira nire gertaerak iristen?"

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

Behartu hustuketa bat zure test harness-etik; sareko joan-etorri bat amaitu arte gehienez timeoutMs blokeatuko du:

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 ibilbideek berehala sortzen dituzte screen_view gertaerak eta screen_visit erregistro egituratuak, dwell eta flow metadatuekin, konfigurazio gehigarririk gabe. Jetpack Compose Navigation erabiltzen baduzu, jaurti Kixo.screen ibilbideari lotutako LaunchedEffect batetik; horrela SDK-k helmuga bakoitzeko gertaera bakarra ikusiko du, berronposaketa kopurua edozein dela ere.

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 kode-agenteak

SDK-ren azalera publikoa txikia da eta autobetetzean ondo ibiltzeko diseinatuta dago: metodo guztiak Kixo singleton-ean daude, gida honetako Kotlin adibide guztiak import io.kixo.sdk.Kixorekin hasten dira, eta gure README fitxategiak "AI agent quick reference" blokea dakar, Claude Code, Cursor eta Codex bezalako tresnek zuzenean testuinguruan itsats dezaketena. Zure agentea trabatzen bada, hasierako erreferentzia kanonikoa hau da:

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