Android SDK

Tacaíonn SDK Kixo do Android le Kotlin 2.0+ agus le Java, éilíonn sé minSdk 24 (Android 7.0), agus tógadh é in aghaidh compileSdk 35. Fanann d’aip óstach freagrach as a targetSdk féin. Le glao amháin ar Kixo.configure i do Application.onCreate, déantar scáileáin, sconnaí, seisiúin, tuairteanna agus imeachtaí saolré a rianú go huathoibríoch. Teastaíonn an droichead FCM atá mínithe thíos chun brúfhógraí a rianú. Níl uathrianú iarratas líonra san eisiúint Android reatha. Tacaíonn an SDK freisin le hathsheinm seisiún, aitheantas agus spriocanna.

Tús tapa

Trí chomhad. Cuir repo Maven leis, cuir an spleáchas leis, ansin cuir dhá líne i do fho-aicme Application.

Riachtanais tógála: compileSdk 35, minSdk 24, Kotlin 2.0+ nó Java, agus bytecode 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")
        }
    }
}

Cuir le d’aip é

Tá repo Maven Kixo óstáilte ar GitHub Pages. Cuir leis é taobh le google() agus mavenCentral() in 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")
        }
    }
}

Ansin dearbhaigh an spleáchas i modúl d’aip:

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

Tionscadail ilmhódúil

Tá cumraíocht implementation de chuid Gradle neamh-aistritheach: má dhearbhaíonn tú implementation("io.kixo:kixo-android-sdk:0.1.20") i modúl leabharlainne (m.sh. :core_domain), NÍ bheidh Kixo infheicthe do :app ná d’aon tomhaltóir eile. Oibríonn dhá phatrún anseo — roghnaigh ceann amháin.

Patrún A — dearbhaíonn gach modúl a ghlaonn ar Kixo é féin é (molta). Coinníonn sé seo classpath gach modúil chomh beag agus is féidir agus seachnaíonn sé atógálacha slabhracha. Úsáid catalóg leaganacha (libs.kixo.sdk) ionas nach gá duit an leagan a athrú ach in aon áit amháin.

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

Patrún B — athonnmhairigh trí api(...). Ní gá ach dearbhú amháin, ach cuimsíonn ABI poiblí an mhodúil leabharlainne cineálacha Kixo anois — agus cuirfidh aon ardú leagain atógáil ar gach modúl iartheachtach. Ná húsáid é seo ach nuair a úsáideann an leabharlann cineálacha Kixo ina sínithe poiblí féin (m.sh. nuair a fhilleann feidhm 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
}

Túsú

Cumraigh Kixo i do fho-aicme Application — ritheann onCreate roimh aon activity, mar sin gabhtar gach amharc scáileáin, sconna agus imeacht saolré ón gcéad fhráma. Cláraigh an Application i do manifest le 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",
        )
    }
}

Le haghaidh socruithe mionsonraithe inoiriúnaithe (bratacha uathrianta, minicíocht sruthlaithe, sampláil athsheinm, óstach saincheaptha API), tóg KixoConfiguration go sainráite:

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)

Rianaigh imeachtaí

Iompraíonn trí phríomhthógáil an chuid is mó de d’ionstraimiú: track d’imeachtaí, markGoal do chomharthaí comhshó, agus addBreadcrumb do chomhthéacs nach imeacht é.

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

Imeachtaí caighdeánacha

Sraith áise thar Kixo.track do na himeachtaí a aithníonn Kixo de réir ainm — eochracha teaghráin díreach mar atá a mheaitseálann braiteoir imeachtaí caighdeánacha an chúlchórais. Bailíochtú ar chruth na n-airíonna ag am tiomsaithe, agus foinse amháin fhírinne don ainmniú.

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)

Aithin úsáideoirí

Ceangail imeachtaí ina dhiaidh sin le haitheantas úsáideora seasmhach agus le tacar tréithe. Déantar an fuáil idir úsáideoir anaithnid agus úsáideoir aitheanta in Kixo — cuirtear imeachtaí a gabhadh roimh identify i leith an úsáideora chéanna go haisghníomhach.

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

⚠️ Gaiste an chomhartha dollar i Kotlin. Tá na gnátheochracha aitheantais réimírithe le $ ($email, $name, $first_name) — agus i litriú Kotlin, ní mór an comhartha dollar a éalú mar "\$email". Má scríobhann tú "$email", cuirfear idirshuíomh teaghráin i bhfeidhm ar d’athróg email, agus rachaidh an luach i dtír go ciúin mar thréith saincheaptha gan na colúin ríomhphoist ná ainm san Audience a líonadh. An réiteach is simplí: úsáid an t-overload clóscríofa (SDK 0.1.13+), rud nach féidir a chur amú: Kixo.setUserProperty(StandardProperty.EMAIL, email).

Clibeáil úsáideoir le haghaidh deighilte

Úsáid setUserProperty le luach boole chun clib shimplí tá/níl a cheangal leis an úsáideoir. Fanann an chlib sin i bhfeidhm thar sheoltaí agus cumhachtaíonn sí deighleoga, feachtais ríomhphoist agus cuardaigh sa chomhrá — gan aon socrú eile seachas an glao 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",
))

Stóráiltear airíonna trí SharedPreferences thar sheoltaí agus ceanglaítear iad go huathoibríoch le gach imeacht amach. Sa chomhrá, abair rudaí cosúil le "seol ríomhphost fáilte chuig úsáideoirí a bhfuil subscribe fíor acu" — tógann Kixo an deighleog agus dréachtaíonn sé an teimpléad duit. Glantar iad ar Kixo.reset().

Catalóg chaighdeánach na n-airíonna

Bíonn réimír $ ar eochracha airíonna forchoimeádta ionas go bhfanann siad i spás ainmneacha ar leithligh ó do thréithe saincheaptha. Clúdaíonn catalóg Kixo 37 eochair thar 3 phacáiste uilíocha (aitheantas, geo, saolré) agus 5 phacáiste ingearacha B2B (síntiús, ríomhthráchtáil, meáin, margadh, dílseacht). Socraigh na cinn a bhaineann le do tháirge — oiriúnaíonn an painéal agus ní thaispeánann sé ach na pacáistí a líonann tú.

Aitheantas

Baineann sé i gcónaí. Socraíonn sé colúin cheanntásc an phróifíle.

Geo

Comhthéacs geografach.

Saolré

Cathain a chonaiceamar iad.

Síntiús

Socraigh é seo má tá pleananna ag do tháirge.

Ríomhthráchtáil

Socraigh é seo má dhíolann tú táirgí.

Meáin

Socraigh é seo má fhoilsíonn tú ábhar.

Margadh

Socraigh é seo más ardán déthaobhach thú.

Dílseacht

Socraigh é seo do chláir rannpháirtíochta agus luaíochtaí.

Sár-airíonna

Péirí eochair/luacha in aghaidh an tseisiúin a cheanglaítear go huathoibríoch le gach imeacht amach. Tá siad éagsúil ó thréithe identify (a chuireann síos ar fhéiniúlacht); cuireann super-properties síos ar chomhthéacs an tseisiúin — malairt ghníomhach A/B, blas tógála, bratacha gné a roghnaíodh isteach. Fanann siad i bhfeidhm thar sheoltaí; glantar iad ar reset(). Má bhíonn coimhlint ann, bíonn tosaíocht i gcónaí ag properties in aghaidh an imeachta ar 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()

Fógraí push

Dhá bhealach comhtháthaithe. Roghnaigh A má úsáideann tú FCM agus más mian leat an socrú is giorra a oibríonn; roghnaigh B má tá FirebaseMessagingService saincheaptha agat cheana nach féidir leat a atheagrú, nó más mian leat smacht sainráite ar na seachadtaí FCM a fheiceann Kixo.

Rogha A — leathnaigh KixoFirebaseMessagingService (uathrianú)

Déan fo-aicme de KixoFirebaseMessagingService agus glaoigh ar super.onMessageReceived(...) i do shárú — astaíonn Kixo push_received go huathoibríoch (ualach infheicthe) nó push_silent (sonraí amháin). Láimhseálann an bunrang clárú onNewToken freisin mura sáraíonn tú é. Tá clárú AndroidManifest.xml mar a bheadh i ngnáthsheirbhís 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
    }
}

Rogha B — glaoigh ar an API de láimh ó do sheirbhís FCM féin

Cláraigh do token FCM le Kixo trí FirebaseMessagingService.onNewToken, ansin logáil gach seachadadh go sainráite. Úsáid an bealach seo más mian leat nach bhfeicfeadh Kixo ach fo-thacar de sheachadtaí FCM. Faoi láthair, ní thacaíonn seachadadh ar Android ach le 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")
    }
}

Ní chuireann Android duán uilíoch saolré ar fáil do oscailtí, díbheanna ná cnaipí gnímh fógraí. Cuir na comharthaí sin ar aghaidh ó na intents fógraí nó na receivers a chruthaíonn d’aip:

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

Athsheinm seisiúin

Athsheinn atógáil amhairc fhíor den mhéid a chonaic an t-úsáideoir. Ag gach gabháil, ionchódaíonn an SDK fráma comhbhrúite den scáileán (íomhá JPEG) mar aon le léargas struchtúrtha ar ordlathas na radharc, agus uaslódálann sé an dá cheann — ionas gur féidir leis an seinnteoir sa deais athsheinm picteilínchruinn a thaispeáint taobh leis an amlínte idirghníomhaíochta. Cumraigh an athsheinm don tionscadal in Deais → Socruithe → Athsheinm seisiúin. Léann agus athnuachann an SDK an beartas tionscadail sin go huathoibríoch, lena n-áirítear cumhdach, modhanna gabhála agus cead uaslódála ar líonraí ceallacha.

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)

Má tá uaslódáil ar líonraí ceallacha díchumasaithe, fanann athsheinm atá i scuaine go mbeidh líonra ceadaithe ar fáil.

Bailiú sonraí

Gabhann an SDK na sonraí atá cumasaithe i do thionscadal, chomh maith leis na himeachtaí agus na hairíonna a sheolann d’aip.

Dífhabhtú

Tugann Kixo.diagnostics() léargas inléite amháin ar staid an SDK ar ais — úsáideach ar scáileán dífhabhtaithe i bhfolach nó i dtástáil deataigh. Freagraíonn sé “cén fáth nach bhfuil mo chuid imeachtaí ag teacht tríd?” gan dífhabhtóir.

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

Cuir iallach ar shruthlú ó do chreatlach tástála — blocálann sé ar feadh suas le timeoutMs fad is a bhíonn turas líonra ar siúl:

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)

Nascleanúint Compose

Cruthaíonn bealaí Activity / Fragment imeachtaí screen_view láithreach agus taifid struchtúrtha screen_visit le meiteashonraí ama fanachta agus sreafa gan aon socrú breise. Le Jetpack Compose Navigation, seol Kixo.screen ó LaunchedEffect atá eochraithe ar an mbealach — feicfidh an SDK imeacht amháin in aghaidh gach ceann scríbe, is cuma cé mhéad uair a athchumtar é.

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

Gníomhairí códaithe AI

Tá dromchla poiblí an SDK beag agus deartha don uathchríochnú cód — tá gach modh ar an singleton Kixo, tosaíonn gach sampla Kotlin sa treoir seo le import io.kixo.sdk.Kixo, agus tá bloc “tagairt thapa do ghníomhairí AI” inár README ar féidir le huirlisí ar nós Claude Code, Cursor agus Codex a ghreamú díreach ina gcomhthéacs. Má théann do ghníomhaire i bhfostú, seo an tús canónach:

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