Android SDK

Kixo Android SDK atbalsta Kotlin 2.0+ un Java, prasa minSdk 24 (Android 7.0) un ir būvēts pret compileSdk 35. Par savu targetSdk joprojām atbild pati host lietotne. Viens Kixo.configure izsaukums jūsu Application.onCreate automātiski izseko ekrānus, pieskārienus, sesijas, avārijas un dzīvescikla notikumus. Push izsekošanai vajadzīgs zemāk aprakstītais FCM tilts. Tīkla pieprasījumu automātiskā izsekošana pašreizējā Android laidienā nav pieejama. SDK atbalsta arī sesiju atkārtošanu, identitāti un mērķus.

Ātrais sākums

Trīs faili. Pievienojiet Maven repozitoriju, pievienojiet atkarību un tad ielieciet divas rindas savā Application apakšklasē.

Build prasības: compileSdk 35, minSdk 24, Kotlin 2.0+ vai Java, kā arī Java 17 baitkods.

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

Pievienojiet savai lietotnei

Kixo Maven repozitorijs ir publicēts GitHub Pages. Pievienojiet to līdzās google() un mavenCentral() failā 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")
        }
    }
}

Pēc tam deklarējiet atkarību savā lietotnes modulī:

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

Vairāku moduļu projekti

Gradle konfigurācija implementation ir nav transitīva: ja bibliotēkas modulī (piemēram, :core_domain) deklarējat implementation("io.kixo:kixo-android-sdk:0.1.20"), tas NEpadara Kixo pieejamu :app vai jebkuram citam patērētājam. Darbojas divi varianti — izvēlieties vienu.

A modelis — katrs modulis, kas izsauc Kixo, deklarē to pats (ieteicams). Uztur katra moduļa classpath pēc iespējas mazāku un novērš ķēdes veida pārbūves. Izmantojiet version catalog (libs.kixo.sdk), lai versiju mainītu tikai vienā vietā.

// :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 modelis — reeksportējiet caur api(...). Viena deklarācija, taču bibliotēkas moduļa publiskajā ABI tagad parādās Kixo tipi — jebkura versijas maiņa izraisa visu pakārtoto moduļu pārbūvi. Lietojiet to tikai tad, ja bibliotēka savās publiskajās signatūrās izmanto Kixo tipus atkārtoti (piemēram, funkcija atgriež 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ēšana

Konfigurējiet Kixo savā Application apakšklasē — onCreate tiek izpildīts pirms jebkuras activity, tāpēc katrs ekrāna skatījums, pieskāriens un dzīvescikla notikums tiek uztverts jau no pirmā kadra. Reģistrējiet Application savā manifestā ar 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",
        )
    }
}

Ja vajag precīzākus iestatījumus (automātiskās izsekošanas karogus, nosūtīšanas intervālu, replay paraugošanu, pielāgotu API resursdatoru), izveidojiet KixoConfiguration tieši:

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)

Izsekojiet notikumus

Lielāko daļu instrumentācijas nosegs trīs primitīvi: track notikumiem, markGoal konversijas signāliem un addBreadcrumb kontekstam, kas nav notikums.

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

Standarta notikumi

Ērts apvalks virs Kixo.track notikumiem, kurus Kixo atpazīst pēc nosaukuma — burtiskām virkņu atslēgām, ko backend standarta notikumu detektors salīdzina tieši. Īpašību formas pārbaude kompilēšanas laikā un viens patiesības avots nosaukumiem.

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)

Identificēt lietotājus

Piesaistiet turpmākos notikumus stabilam lietotāja ID un pazīmju kopai. Pāreju no anonīma uz zināmu lietotāju apstrādā Kixo — notikumi, kas uztverti pirms identify, pēc tam tiek piesaistīti tam pašam lietotājam.

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 dolāra zīmes slazds. Standarta identitātes atslēgām ir prefikss $ ($email, $name, $first_name) — un Kotlin literālī dolāra zīme must jāaizvieto kā "\$email". Ja rakstāt "$email", tiek interpolēts jūsu email mainīgais, tāpēc vērtība klusi nonāk kā pielāgots pazīme un nekad neaizpilda Audience e-pasta vai vārda kolonnas. Vienkāršākais risinājums — izmantot tipizēto overload (SDK 0.1.13+), kuru nevar sajaukt: Kixo.setUserProperty(StandardProperty.EMAIL, email).

Atzīmēt lietotāju segmentēšanai

Izmantojiet setUserProperty ar boolean vērtību, lai lietotājam pievienotu vienkāršu jā/nē atzīmi. Tā saglabājas starp lietotnes palaišanām un tiek izmantota segmentos, e-pasta kampaņās un čata vaicājumos — nekas nav jākonfigurē ārpus SDK izsaukuma.

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

Īpašības tiek saglabātas ar SharedPreferences starp lietotnes palaišanām un automātiski pievienotas katram izejošajam notikumam. Čatā varat rakstīt, piemēram, "nosūti sagaidīšanas e-pastu lietotājiem, kuriem subscribe ir true" — Kixo pats izveidos segmentu un sagatavos veidni. Tās tiek notīrītas ar Kixo.reset().

Standarta īpašību katalogs

Rezervētajām īpašību atslēgām ir prefikss $, lai tās nepārklātos ar jūsu pielāgotajām pazīmēm. Kixo katalogā ir 37 atslēgas 3 universālās pakās (identitāte, ģeogrāfija, dzīves cikls) un 5 B2B vertikālajās pakās (abonementi, e-komercija, mediji, tirdzniecības platformas, lojalitāte). Norādiet tikai tās, kas attiecas uz jūsu produktu — panelis pielāgosies un rādīs tikai aizpildītās pakas.

Identitāte

Vienmēr aktuāli. Nosaka profila galvenes kolonnas.

Geo

Ģeogrāfiskais konteksts.

Dzīves cikls

Kad mēs viņu redzējām.

Abonementi

Iestatiet, ja jūsu produktam ir plāni.

E-komercija

Iestatiet, ja pārdodat preces.

Mediji

Iestatiet, ja publicējat saturu.

Tirdzniecības platforma

Iestatiet, ja jūsu produkts ir divpusēja platforma.

Lojalitāte

Iestatiet, ja izmantojat iesaistes vai atlīdzību programmas.

Super-properties

Sesijas līmeņa atslēgu/vērtību pāri, kas automātiski tiek pievienoti katram izejošajam notikumam. Tie atšķiras no identify pazīmēm (kas raksturo identitāti); super-properties raksturo sesijas kontekstu — aktīvo A/B variantu, build flavor, ieslēgtos feature flags. Tie saglabājas starp lietotnes palaišanām un tiek notīrīti ar reset(). Ja sakrīt atslēgas, priekšroka vienmēr ir notikuma līmeņa properties uz 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 paziņojumi

Ir divi integrācijas ceļi. Izvēlieties A, ja izmantojat FCM un gribat īsāko strādājošo iestatījumu; izvēlieties B, ja jums jau ir pielāgots FirebaseMessagingService, ko nevarat pārstrukturēt, vai gribat skaidri kontrolēt, kuras FCM piegādes redz Kixo.

A variants — paplašiniet KixoFirebaseMessagingService (automātiskā izsekošana)

Paplašiniet KixoFirebaseMessagingService un savā override izsauciet super.onMessageReceived(...) — Kixo automātiski izsūta push_received (redzams payload) vai push_silent (tikai dati). Bāzes klase apstrādā arī onNewToken reģistrāciju, ja to nepārrakstāt. AndroidManifest.xml reģistrācija paliek tāda pati kā parastam FCM servisam.

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 variants — izsauciet manuālo API no sava FCM servisa

Reģistrējiet savu FCM tokenu Kixo ar FirebaseMessagingService.onNewToken, pēc tam katru piegādi ierakstiet skaidri. Izmantojiet šo ceļu, ja vēlaties, lai Kixo redz tikai daļu no FCM piegādēm. Android piegādes pašlaik atbalsta tikai 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 nepiedāvā universālu dzīvescikla piesaisti paziņojumu atvēršanai, noraidīšanai vai darbību pogām. Pārsūtiet šos signālus no notification intents vai receivers, ko izveido jūsu lietotne:

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

Sesiju ieraksts

Atspēlējiet reālu, vizuālu rekonstrukciju tam, ko lietotājs redzēja. Katrā tveršanas reizē SDK kodē saspiestu ekrāna kadru (JPEG attēlu) kopā ar skatu hierarhijas strukturālu momentuzņēmumu un augšupielādē abus — lai paneļa atskaņotājs varētu parādīt pikseļu precīzu atskaņojumu līdzās mijiedarbības laika skalai. Konfigurējiet replay projektam sadaļā Pārskats → Iestatījumi → Sesiju atkārtojums. SDK šo projekta politiku automātiski nolasa un atjaunina, tostarp maskēšanu, tveršanas režīmus un atļauju augšupielādei mobilajā tīklā.

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)

Ja augšupielāde mobilajā tīklā ir atspējota, rindā gaidošais replay tiek aizturēts līdz atļautam tīklam.

Datu vākšana

SDK tver jūsu projektā ieslēgtos datus, kā arī notikumus un īpašības, ko nosūta lietotne.

Atkļūdošana

Kixo.diagnostics() atgriež tikai lasāmu SDK stāvokļa momentuzņēmumu — noder slēptā atkļūdošanas ekrānā vai smoke testā. Palīdz saprast: “kāpēc mani notikumi netiek nosūtīti?” bez atkļūdotāja.

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

Piespiediet flush no testa ietvara — tas bloķē līdz timeoutMs, kamēr notiek tīkla round-trip:

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 maršruti uzreiz rada screen_view notikumus un strukturētus screen_visit ierakstus ar uzturēšanās laika un plūsmas metadatiem. Jetpack Compose Navigation gadījumā izsauciet Kixo.screen no LaunchedEffect, kas piesaistīts maršrutam — tad SDK redz vienu notikumu uz katru galamērķi neatkarīgi no recomposition skaita.

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 kodēšanas aģenti

SDK publiskā virsma ir maza un veidota darbam ar koda pabeigšanu — visas metodes ir uz singletona Kixo, katrs Kotlin piemērs šajā ceļvedī sākas ar import io.kixo.sdk.Kixo, un mūsu README ir iekļauts "AI agent quick reference" bloks, ko tādi rīki kā Claude Code, Cursor un Codex var uzreiz ielīmēt savā kontekstā. Ja aģents iestrēgst, drošākais sākuma punkts ir:

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