Android SDK

Il-Kixo Android SDK jappoġġja Kotlin 2.0+ u Java, jeħtieġ minSdk 24 (Android 7.0), u huwa mibni kontra compileSdk 35. L-app host tiegħek tibqa’ responsabbli għall-targetSdk tagħha stess. Sejħa waħda ta’ Kixo.configure fil-Application.onCreate tiegħek tittraċċa awtomatikament screens, taps, sessions, crashes u lifecycle events. It-traċċar tal-push jeħtieġ il-bridge FCM deskritt hawn taħt. In-network request auto-tracking mhuwiex parti mir-release Android attwali. L-SDK jappoġġja wkoll session replay, identità u goals.

Bidu malajr

Tliet files. Żid il-Maven repo, żid id-dependency, imbagħad daħħal żewġ linji fis-subclass Application tiegħek.

Rekwiżiti tal-build: compileSdk 35, minSdk 24, Kotlin 2.0+ jew Java, u 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")
        }
    }
}

Żidha mal-app tiegħek

Il-Maven repo ta’ Kixo huwa ospitat fuq GitHub Pages. Żidu flimkien ma’ google() u mavenCentral() f’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")
        }
    }
}

Imbagħad iddikjara d-dependency fil-module tal-app tiegħek:

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

Projects b’ħafna modules

Il-konfigurazzjoni implementation ta’ Gradle hija mhux transitive: jekk tiddikjara implementation("io.kixo:kixo-android-sdk:0.1.20") f’library module (eż. :core_domain), dan MA jagħmilx lil Kixo viżibbli għal :app jew għal konsumatur ieħor. Hemm żewġ patterns li jaħdmu — agħżel wieħed.

Pattern A — kull module li jsejjaħ Kixo jiddikjarah hu stess (rakkomandat). Iżomm il-classpath ta’ kull module ħafif kemm jista’ jkun u jevita rebuilds li jinxterdu. Uża version catalog (libs.kixo.sdk) biex tbiddel il-verżjoni f’post wieħed biss.

// :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 — erġa’ esporta permezz ta’ api(...). Dikjarazzjoni waħda, imma l-ABI pubblika tal-library module issa tinkludi tipi ta’ Kixo — kull version bump iġiegħel rebuild ta’ kull module downstream. Uża dan biss meta l-library terġa’ tuża tipi ta’ Kixo fil-firem pubbliċi tagħha stess (eż. tirritorna KixoDiagnostics minn function).

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

Inizjalizza

Ikkonfigura Kixo mis-subclass Application tiegħek — onCreate jaħdem qabel kull activity, għalhekk kull screen view, tap u lifecycle event jinqabad mill-ewwel frame. Irreġistra l-Application fil-manifest b’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",
        )
    }
}

Għal settings aktar fini (auto-track flags, flush cadence, replay sampling, custom API host) ibni KixoConfiguration b’mod espliċitu:

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)

Ittraċċa events

Tliet primitives iġorru l-parti l-kbira tal-instrumentation tiegħek: track għall-events, markGoal għas-sinjali ta’ conversion, u addBreadcrumb għal kuntest li mhux event.

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

Avvenimenti standard

Sugar fuq Kixo.track għall-events li Kixo jagħraf bl-isem — string keys verbatim li jaqblu mad-detector tal-backend għall-standard events. Validazzjoni fil-ħin tal-compile tal-forma tal-properties, u sors wieħed tal-verità għall-ismijiet.

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)

Identifika l-utenti

Qabbad l-events li jiġu wara ma’ user id stabbli u ma’ sett ta’ traits. L-għaqda bejn anonymous u known users issir f’Kixo — events maqbuda qabel identify jiġu attribwiti retroattivament lill-istess utent.

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

⚠️ In-nassa tas-sinjal tad-dollar f’Kotlin. Iċ-ċwievet standard tal-identità għandhom prefiss $ ($email, $name, $first_name) — u f’Kotlin literal trid taħrab is-sinjal tad-dollar bħala "\$email". Jekk tikteb "$email", tkun qed tagħmel string interpolation tal-varjabbli email tiegħek, u għalhekk il-valur jinżel fis-skiet bħala trait custom u qatt ma jimla l-kolonni Audience email / name. L-eħfef soluzzjoni hija li tuża l-overload typed (SDK 0.1.13+), li ma tistax tiżbalja fih: Kixo.setUserProperty(StandardProperty.EMAIL, email).

Ittikketta utent għas-segmentazzjoni

Uża setUserProperty b’valur ta’ boolean biex iżżid tikketta sempliċi iva/le mal-utent. It-tikketta tibqa’ bejn il-launches u tintuża għas-segments, email campaigns u chat queries — bla setup ieħor barra s-sejħa tal-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",
))

Il-properties jinżammu permezz ta’ SharedPreferences bejn launches u jitwaħħlu awtomatikament ma’ kull event li joħroġ. Fiċ-chat għid affarijiet bħal "ibgħat email ta’ merħba lill-utenti fejn subscribe huwa true" — Kixo jibni s-segment u jħejjilek l-ewwel abbozz tat-template. Jitnaddfu fuq Kixo.reset().

Katalgu standard tal-properties

Iċ-ċwievet riservati tal-properties iġorru prefiss $ biex jinżammu separati mit-traits personalizzati tiegħek. Il-katalgu ta’ Kixo jkopri 37 ċavetta f’3 pakketti universali (identity, geo, lifecycle) u 5 pakketti vertikali B2B (subscription, e-commerce, media, marketplace, loyalty). Issettja biss dawk li japplikaw għall-prodott tiegħek — id-dashboard jadatta u juri biss il-pakketti li timla.

Identità

Dejjem rilevanti. Tissettja l-kolonni tal-header tal-profil.

Geo

Kuntest ġeografiku.

Ċiklu tal-ħajja

Meta rajniehom.

Abbonament

Issettja dan jekk il-prodott tiegħek għandu plans.

E-commerce

Issettja dan jekk tbigħ prodotti.

Midja

Issettja dan jekk tippubblika kontenut.

Suq

Issettja dan jekk inti pjattaforma b’żewġ naħat.

Lealtà

Issettja dan għal programmi ta’ involviment u rewards.

Super-properties

Key/value pairs għal kull session li jitwaħħlu awtomatikament ma’ kull event li joħroġ. Differenti minn traits ta’ identify (li jiddeskrivu l-identità); is-super-properties jiddeskrivu l-kuntest tas-session — A/B variant attiv, build flavor, feature flags attivati. Jinżammu bejn launches; jitnaddfu fuq reset(). Meta jkun hemm collision, dejjem jirbaħ il-properties għal kull event fuq 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()

Notifiki push

Żewġ toroq ta’ integrazzjoni. Agħżel A jekk qed tuża FCM u trid l-iqsar setup li jaħdem; agħżel B jekk diġà għandek FirebaseMessagingService custom li ma tistax terġa’ tistrutturah jew trid kontroll espliċitu fuq liema deliveries ta’ FCM jara Kixo.

Għażla A — estendi KixoFirebaseMessagingService (auto-tracking)

Agħmel subclass ta’ KixoFirebaseMessagingService u sejjaħ super.onMessageReceived(...) mill-override tiegħek — Kixo joħroġ awtomatikament push_received (visible payload) jew push_silent (data-only). Il-base class tieħu ħsieb ukoll ir-reġistrazzjoni ta’ onNewToken jekk ma tagħmilhiex override. Ir-reġistrazzjoni ta’ AndroidManifest.xml tibqa’ kif inhi f’servizz FCM normali.

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

Għażla B — sejjaħ API manwali mis-servizz FCM tiegħek stess

Irreġistra t-token FCM tiegħek ma’ Kixo permezz ta’ FirebaseMessagingService.onNewToken, imbagħad illoggja kull delivery b’mod espliċitu. Uża din it-triq jekk trid li Kixo jara biss parti mid-deliveries ta’ FCM. Android delivery bħalissa jappoġġja FCM biss.

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 ma jipprovdix lifecycle hook universali għal opens, dismissals jew action buttons tan-notifications. Għaddi dawn is-sinjali mill-intents jew receivers tan-notifications li toħloq l-app tiegħek:

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

Ripetizzjoni tas-sessjoni

Erġa’ ara rikostruzzjoni viżwali reali ta’ dak li ra l-utent. F’kull capture, l-SDK jikkodifika frame ikkompressat tal-iskrin (immaġni JPEG) flimkien ma’ structural snapshot tal-view hierarchy, u jtella’ t-tnejn — biex il-player fid-dashboard ikun jista’ jirrendi playback preċiż sal-livell tal-pixels flimkien mal-linja taż-żmien tal-interazzjonijiet. Ikkonfigura r-replay għall-project f’Dashboard → Settings → Ripetizzjoni tas-sessjoni. L-SDK jaqra u jġedded awtomatikament dik il-policy tal-project, inklużi masking, capture modes u permess għall-upload fuq cellular.

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)

Meta l-upload fuq cellular ikun diżattivat, ir-replay fil-kju jistenna network permess.

Ġbir tad-data

L-SDK jaqbad id-data attivata fil-project tiegħek, kif ukoll l-events u l-properties li tibgħat l-applikazzjoni tiegħek.

Debugging

Kixo.diagnostics() jirritorna stampa read-only tal-istat tal-SDK — utli f’screen moħbija ta’ debug jew fi smoke test. Iwieġeb “għaliex l-events tiegħi mhumiex għaddejjin?” mingħajr debugger.

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

Forza flush mill-harness tat-test tiegħek — jista’ jimblokka sa timeoutMs fuq round-trip tan-network:

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

Ir-rotot ta’ Activity / Fragment jipproduċu minnufih events ta’ screen_view u records strutturati ta’ screen_visit, bid-data tad-dwell u tal-flow inkluża. Għal Jetpack Compose Navigation, qabbad Kixo.screen minn LaunchedEffect imqabbad mar-rotta — l-SDK imbagħad jara event wieħed għal kull destinazzjoni, irrispettivament minn kemm isiru recompositions.

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

Aġenti tal-coding bl-AI

Il-wiċċ pubbliku tal-SDK huwa żgħir u mfassal għall-code completion — kull method tinsab fuq is-singleton Kixo, kull sample Kotlin f’din il-gwida tibda b’import io.kixo.sdk.Kixo, u r-README tagħna jinkludi blokka “AI agent quick reference” li għodod bħal Claude Code, Cursor u Codex jistgħu jwaħħlu direttament fil-kuntest tagħhom. Jekk l-agent tiegħek jeħel, dan hu l-bidu kanoniku:

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