Android SDK

Kixo Android SDK styður Kotlin 2.0+ og Java, krefst minSdk 24 (Android 7.0) og er byggt gegn compileSdk 35. Host-forritið þitt ber áfram sjálft ábyrgð á sínu eigin targetSdk. Eitt Kixo.configure kall í Application.onCreate rekur sjálfkrafa skjái, snertingar, lotur, hrun og lífsferilsatvik. Push-rakning krefst FCM-brúarinnar sem lýst er hér að neðan. Sjálfvirk rakning netbeiðna er ekki hluti af núverandi Android-útgáfu. SDK styður líka endurspilun lota, auðkenningu og markmið.

Flýtiræsing

Þrjár skrár. Bættu við Maven-geymslunni, bættu við háðinni og settu síðan tvær línur í Application undirklasann þinn.

Build-kröfur: compileSdk 35, minSdk 24, Kotlin 2.0+ eða Java, og 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")
        }
    }
}

Bættu við í forritið þitt

Kixo Maven-geymslan er hýst á GitHub Pages. Bættu henni við samhliða google() og mavenCentral() í 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")
        }
    }
}

Skilgreindu síðan háðina í app-módúlnum:

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

Verkefni með marga módúla

implementation stilling Gradle er ekki transitíft: ef þú skilgreinir implementation("io.kixo:kixo-android-sdk:0.1.20") í bókasafnsmódúl (t.d. :core_domain) verður Kixo EKKI sýnilegt fyrir :app eða aðra neytendur. Tvö mynstur virka — veldu annað þeirra.

Mynstur A — hver módúl sem kallar á Kixo skilgreinir það sjálft (ráðlagt). heldur classpath hvers módúls í lágmarki og kemur í veg fyrir keðjuverkandi endurbyggingar. Notaðu version catalog (libs.kixo.sdk) svo þú þurfir aðeins að breyta útgáfunni á einum stað.

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

Mynstur B — endurútflutningur í gegnum api(...). Ein skilgreining, en public ABI bókasafnsmódúlsins inniheldur þá Kixo-gerðir — hver útgáfubreyting kallar því á endurbyggingu í öllum neðri módúlum. Notaðu þetta aðeins þegar bókasafnið endurnýtir Kixo-gerðir í eigin public signatures (t.d. skilar KixoDiagnostics úr falli).

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

Frumstilla

Stilltu Kixo í Application undirklasanum þínum — onCreate keyrir áður en nokkur activity fer af stað, þannig að allar skjáskoðanir, snertingar og lífsferilsatvik eru skráð frá fyrsta ramma. Skráðu Application í manifestinu með 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",
        )
    }
}

Ef þú þarft nákvæmari stillingar (sjálfvirkar rakningarflögg, sendingartakta, sýnatöku fyrir endurspilun, sérsniðinn API hýsill) skaltu smíða KixoConfiguration sérstaklega:

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)

Rekja atvik

Þrjár grunnaðgerðir bera uppi megnið af instrumenteringunni: track fyrir atvik, markGoal fyrir umbreytingarmerki og addBreadcrumb fyrir samhengi sem er ekki atvik.

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

Stöðluð atvik

Þægindalag yfir Kixo.track fyrir þau atvik sem Kixo þekkir af nafni — nákvæmir strengjalyklar sem staðlað atvikagreining á bakendanum passar við. Lögun eiginda er staðfest við þýðingu og nafngiftir eru á einum stað.

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)

Auðkenna notendur

Tengdu næstu atvik við stöðugt user id og safn traits. Tenging úr nafnlausum notanda yfir í þekktan notanda fer fram í Kixo — atvik sem voru skráð fyrir identify eru síðan rakin afturvirkt á sama notanda.

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

⚠️ Dollaramerkisgildra í Kotlin. Staðlaðir identity-lyklar hafa $-forskeyti ($email, $name, $first_name) — og í Kotlin strengjalíteral verður þú að verður að sleppa dollaramerkinu sem "\$email". Skrifirðu "$email" þá setur strengurinn gildi breytunnar email inn, svo það lendir hljóðlega sem sérsniðið trait og fyllir aldrei dálkana Audience email / name. Einfaldasta leiðréttingin er að nota typed overload (SDK 0.1.13+), sem er ómögulegt að misnota: Kixo.setUserProperty(StandardProperty.EMAIL, email).

Merkja notanda fyrir hlutun

Notaðu setUserProperty með boolean gildi til að festa einfalt já/nei-merki við notandann. Merkið helst milli ræsinga og nýtist í hlutun, tölvupóstsherferðum og fyrirspurnum í spjalli — ekkert þarf að stilla umfram þetta SDK-kall.

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

Eigindir eru varðveittar með SharedPreferences milli ræsingar og festast sjálfkrafa við hvert atvik sem er sent út. Í spjalli geturðu sagt hluti eins og „send a welcome email to users where subscribe is true“ — Kixo býr til hlutann og semur drög að sniðmáti fyrir þig. Hreinsast með Kixo.reset().

Katalogur staðlaðra eiginleika

Fráteknir eiginleikalyklar bera $-forskeyti svo þeir rekist ekki á sérsniðin traits hjá þér. Katalogur Kixo nær yfir 37 lykla í 3 almennum pökkum (identity, geo, lifecycle) og 5 sértækum B2B-pökkum (subscription, e-commerce, media, marketplace, loyalty). Stilltu þá pakka sem eiga við um vöruna þína — mælaborðið aðlagast og sýnir aðeins þá sem þú fyllir út.

Auðkenni

Alltaf viðeigandi. Stillir dálkana í haus prófílsins.

Landfræði

Landfræðilegt samhengi.

Lífsferill

Hvenær sáum við þau.

Áskrift

Stilltu þetta ef varan þín er með áskriftarleiðir.

Netverslun

Stilltu þetta ef þú selur vörur.

Miðlar

Stilltu þetta ef þú birtir efni.

Markaðstorg

Stilltu þetta ef þú rekur tvíhliða vettvang.

Vild

Stillt fyrir vildar- og umbunarkerfi.

Super-properties

Lykil/gildi-pör á lotu sem festast sjálfkrafa við hvert atvik sem er sent út. Þetta er annað en identify traits (sem lýsa auðkenni); super-properties lýsa samhengi lotunnar — virkt A/B-afbrigði, build flavor, feature flags sem hefur verið optað inn á. Halda sér milli ræsingar; hreinsast með reset(). properties á einstökum atvikum á track hafa alltaf forgang ef árekstur verður.

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

Tvær innleiðingarleiðir. Veldu A ef þú ert á FCM og vilt stystu leiðina að virku uppsetningu; veldu B ef þú ert þegar með sérsniðna FirebaseMessagingService sem þú getur ekki endurskipulagt eða vilt stjórna nákvæmlega hvaða FCM-afhendingar Kixo sér.

Valkostur A — erfa frá KixoFirebaseMessagingService (sjálfvirk rakning)

Erfðu frá KixoFirebaseMessagingService og kallaðu super.onMessageReceived(...) í override-inu þínu — Kixo sendir sjálfkrafa push_received (sýnilegt payload) eða push_silent (aðeins gögn). Grunnklassinn sér líka um skráningu á onNewToken ef þú yfirskrifar hana ekki. Skráning á AndroidManifest.xml er óbreytt frá venjulegri FCM service.

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

Valkostur B — kalla á handvirkt API úr eigin FCM service

Skráðu FCM-tokenið þitt hjá Kixo með FirebaseMessagingService.onNewToken og skráðu síðan hverja afhendingu sérstaklega. Veldu þessa leið ef þú vilt að Kixo sjái aðeins hluta af FCM-afhendingum. Á Android er stuðningur við afhendingu sem stendur aðeins fyrir 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 býður ekki upp á almenna lífsferilskrók fyrir opnanir, frávísanir eða aðgerðahnappa í tilkynningum. Sendu þau merki áfram úr notification intents eða receivers sem forritið þitt býr til:

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

Lotuendursýning

Spilaðu upp raunverulega sjónræna endurgerð af því sem notandinn sá. Við hverja upptöku kóðar SDK þjappaðan skjáramma (JPEG-mynd) ásamt byggingaryfirliti af view-hirarkíinu og hleður hvoru tveggja upp — þannig getur spilarinn í mælaborðinu birt pixlanákvæma afspilun samhliða tímalínu samskipta. Stilltu endurspilun fyrir verkefnið í Stjórnborð → Stillingar → Lotuendursýning. SDK les þá verkefnastefnu sjálfkrafa og endurnýjar hana, þar á meðal hylmingu, upptökustillingar og heimild til upphleðslu yfir farsímanet.

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)

Þegar upphleðsla yfir farsímanet er óvirk bíður endurspilun í biðröð þar til tengst er leyfðu neti.

Gagnasöfnun

SDK safnar þeim gögnum sem eru virkjuð í verkefninu þínu, ásamt þeim atvikum og eigindum sem forritið sendir.

Villuleit

Kixo.diagnostics() skilar lesanlegu stöðuyfirliti um heilsu SDK — gagnlegt á falinni villuleitarsíðu eða í smoke test. Svarar spurningunni „af hverju skila atvikin mín sér ekki?“ án þess að opna 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

Þvingaðu fram flush úr test harness-inu — blokkar í allt að timeoutMs á meðan beðið er eftir netferð fram og til baka:

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-leiðir skila strax screen_viewatvikum og skipulögðum screen_visit færslum með lýsigögnum um dvalartíma og flæði. Fyrir Jetpack Compose Navigation skaltu senda Kixo.screen úr LaunchedEffect sem er lyklað á route — þá sér SDK eitt atvik fyrir hvern áfangastað, óháð því hve oft er endursamsett.

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óðunaraðstoðarmenn

Opinbert yfirborð SDK er lítið og mótað fyrir code-completion — allar aðferðir eru á Kixo singletoninu, hvert Kotlin-dæmi í þessum leiðarvísi byrjar á import io.kixo.sdk.Kixo, og README okkar inniheldur reitinn „AI agent quick reference“ sem tól eins og Claude Code, Cursor og Codex geta límt beint inn í context. Ef agentinn festist er þetta rétta byrjunarsniðið:

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