Android SDK

Kixo Android SDK tukee Kotlinia versiosta 2.0 alkaen sekä Javaa, vaatii vähintään minSdk 24:n (Android 7.0) ja on rakennettu versiota compileSdk 35 vasten. Isäntäsovellus vastaa edelleen itse omasta targetSdk:staan. Yksi Kixo.configure-kutsu tiedostossa Application.onCreate ottaa automaattisesti käyttöön näyttöjen, napautusten, istuntojen, kaatumisten ja elinkaaritapahtumien seurannan. Push-seuranta vaatii alla kuvatun FCM-sillan. Verkkopyyntöjen automaattiseuranta ei kuulu nykyiseen Android-julkaisuun. SDK tukee myös istuntotoistoa, identiteettiä ja tavoitteita.

Pika-aloitus

Kolme tiedostoa. Lisää Maven-repo, lisää riippuvuus ja pudota sitten kaksi riviä Application-aliluokkaasi.

Koontivaatimukset: compileSdk 35, minSdk 24, Kotlin 2.0+ tai Java sekä Java 17 -tavukoodi.

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

Lisää sovellukseen

Kixo Maven -repo on GitHub Pagesissa. Lisää se google():n ja mavenCentral():n rinnalle tiedostoon 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")
        }
    }
}

Määritä sitten riippuvuus sovellusmoduulissa:

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

Monimoduuliprojektit

Gradlen implementation-konfiguraatio on ei transitiivinen: jos määrität implementation("io.kixo:kixo-android-sdk:0.1.20"):n kirjastomoduulissa (esimerkiksi :core_domain:ssa), Kixo EI tule näkyviin :app:lle eikä millekään muulle kuluttajalle. Toimivia malleja on kaksi — valitse niistä toinen.

Malli A — jokainen Kixoa kutsuva moduuli määrittää riippuvuuden itse (suositus). pitää kunkin moduulin classpathin mahdollisimman pienenä ja välttää ketjurebuildit. Käytä version catalogia (libs.kixo.sdk), niin päivität version vain yhdessä paikassa.

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

Malli B — vie uudelleen api(...):n kautta. Määritys on yksinkertainen, mutta kirjastomoduulin julkinen ABI sisältää nyt Kixo-tyyppejä — mikä tahansa versionvaihto pakottaa kaikki alavirran moduulit uudelleenkääntymään. Käytä tätä vain, jos kirjasto käyttää Kixo-tyyppejä myös omissa julkisissa rajapinnoissaan, esimerkiksi palauttaa KixoDiagnostics-arvon funktiosta.

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

Alusta

Määritä Kixo omassa Application-aliluokassasi — onCreate suoritetaan ennen ensimmäistäkään activityä, joten jokainen näyttönäkymä, napautus ja elinkaaritapahtuma tallentuu ensimmäisestä ruudusta alkaen. Rekisteröi Application manifestiin arvolla 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",
        )
    }
}

Jos tarvitset tarkempia säätöjä — kuten automaattiseurannan valitsimia, flush-väliä, replay-otantaa tai mukautettua API-hostia — rakenna KixoConfiguration suoraan:

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)

Kirjaa tapahtumat

Kolme perusrakennetta kattaa suurimman osan instrumentoinnista: track tapahtumille, markGoal konversiosignaaleille ja addBreadcrumb muulle kuin tapahtumakohtaiselle kontekstille.

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

Vakiotapahtumat

Kevyt kerros Kixo.track:n päällä niille tapahtumille, jotka Kixo tunnistaa nimen perusteella — täsmällisille merkkijonoavaimille, jotka taustajärjestelmän vakiotapahtumatunnistin osaa tunnistaa. Ominaisuuksien rakenne tarkistetaan käännösaikana, ja nimeämiselle on yksi yhteinen lähde.

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)

Tunnista käyttäjät

Sido seuraavat tapahtumat pysyvään käyttäjätunnukseen ja trait-joukkoon. Anonyymin ja tunnetun käyttäjän yhdistäminen tapahtuu Kixo:ssa, joten ennen identify:aa tallennetut tapahtumat liitetään takautuvasti samaan käyttäjään.

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

⚠️ Kotlinin dollarimerkin sudenkuoppa. Vakiomuotoiset identiteettiavaimet alkavat etuliitteellä $ ($email, $name, $first_name) — ja Kotlin-merkkijonoliteraalissa dollarimerkki täytyy täytyy kirjoittaa muodossa "\$email". Jos kirjoitat "$email", Kotlin interpoloi email-muuttujan arvon merkkijonoon, jolloin tieto tallentuu huomaamatta oma-traitiksi eikä täytä Audience-näkymän sähköposti- tai nimisarakkeita. Helpoin korjaus on käyttää tyypitettyä overloadia (SDK 0.1.13+), jota ei käytännössä voi käyttää väärin: Kixo.setUserProperty(StandardProperty.EMAIL, email).

Merkitse käyttäjä segmentointia varten

Käytä setUserProperty-kutsua totuusarvo-arvolla, kun haluat liittää käyttäjään yksinkertaisen kyllä/ei-tunnisteen. Tunniste säilyy käynnistysten yli ja toimii segmentoinnin, sähköpostikampanjoiden ja chat-kyselyiden pohjana — muuta kuin SDK-kutsu ei tarvita.

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

Ominaisuudet säilyvät SharedPreferences:n kautta sovelluksen käynnistysten yli ja liitetään automaattisesti jokaiseen lähtevään tapahtumaan. Chatissa voit sanoa esimerkiksi "lähetä tervetulosähköposti käyttäjille, joilla subscribe on true" — Kixo muodostaa segmentin ja luonnostelee viestipohjan puolestasi. Ne tyhjennetään komennolla Kixo.reset().

Vakio-ominaisuuksien luettelo

Varatut ominaisuusavaimet saavat etuliitteen $, jotta ne pysyvät erillään omista mukautetuista ominaisuuksistasi. Kixon luettelossa on 37 avainta 3 yleisessä paketissa (identiteetti, sijainti, elinkaari) ja 5 B2B-vertikaalipaketissa (tilaus, verkkokauppa, media, markkinapaikka, kanta-asiakkuus). Ota käyttöön tuotteellesi olennaiset paketit — dashboard mukautuu ja näyttää vain ne, joihin tuot dataa.

Identiteetti

Aina relevantti. Määrittää profiiliotsikon sarakkeet.

Sijainti

Maantieteellinen konteksti.

Elinkaari

Milloin näimme hänet.

Tilaus

Aseta tämä, jos tuotteessasi on palvelupaketteja.

Verkkokauppa

Aseta tämä, jos myyt tuotteita.

Media

Aseta tämä, jos julkaiset sisältöä.

Markkinapaikka

Aseta tämä, jos tuotteesi on kaksipuolinen alusta.

Kanta-asiakkuus

Aseta tämä, jos käytössäsi on sitouttamis- tai palkitsemisohjelmia.

Super-properties

Istuntokohtaiset avain–arvo-parit liitetään automaattisesti jokaiseen lähtevään tapahtumaan. Ne eroavat identify-traiteista, jotka kuvaavat identiteettiä: super-properties kuvaavat istunnon kontekstia, kuten aktiivista A/B-varianttia, build flavoria ja käyttöön otettuja feature flageja. Ne säilyvät sovelluksen käynnistysten yli ja tyhjennetään komennolla reset(). Jos sama avain esiintyy useassa paikassa, track:n tapahtumakohtaiset properties-arvot voittavat aina.

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

Integrointiin on kaksi tapaa. Valitse A, jos käytät FCM:ää ja haluat nopeimman toimivan käyttöönoton. Valitse B, jos sinulla on jo oma FirebaseMessagingService, jota et voi järjestää uudelleen, tai jos haluat itse päättää, mitkä FCM-toimitukset Kixo näkee.

Vaihtoehto A — peri KixoFirebaseMessagingService (automaattiseuranta)

Peri KixoFirebaseMessagingService ja kutsu ylikirjoituksessasi super.onMessageReceived(...) — Kixo lähettää automaattisesti push_received:n (näkyvä payload) tai push_silent:n (vain data). Perusluokka hoitaa myös onNewToken-rekisteröinnin, jos et ylikirjoita sitä. AndroidManifest.xml-rekisteröinti tehdään muuten samaan tapaan kuin tavallisessa FCM-palvelussa.

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

Vaihtoehto B — kutsu manuaalista APIa omasta FCM-palvelustasi

Rekisteröi FCM-token Kixoon kutsulla FirebaseMessagingService.onNewToken ja kirjaa sitten jokainen toimitus erikseen. Käytä tätä tapaa, jos haluat, että Kixo näkee vain osan FCM-toimituksista. Androidin toimitusseuranta tukee tällä hetkellä vain 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 ei tarjoa yleiskäyttöistä elinkaarikoukkua ilmoitusten avauksille, sulkemisille tai toimintopainikkeille. Välitä nämä signaalit niistä notification intent- tai receiver-komponenteista, jotka sovelluksesi luo:

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

Istunnon toisto

Toista käyttäjän näkemä näkymä aidosti ja visuaalisesti. Jokaisella tallennuskerralla SDK koodaa näytöstä pakatun kuvan (JPEG) sekä näkymähierarkian rakenteellisen tilannekuvan ja lataa molemmat, jotta dashboardin soitin voi näyttää pikselintarkan toiston vuorovaikutuksen aikajanan rinnalla. Määritä replay projektille kohdassa Hallintapaneeli → Asetukset → Istunnon tallenne. SDK lukee ja päivittää tämän projektitason käytännön automaattisesti, mukaan lukien peittämisen, tallennustilat ja luvan lähettää dataa mobiiliverkossa.

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)

Jos lähetys mobiiliverkossa ei ole sallittu, jonossa oleva replay odottaa sallittua verkkoyhteyttä.

Tiedonkeruu

SDK kerää projektissasi käyttöön otetut tiedot sekä sovelluksesi lähettämät tapahtumat ja ominaisuudet.

Vianmääritys

Kixo.diagnostics() palauttaa vain luku -tilannekuvan SDK:n tilasta. Se sopii hyvin piilotettuun debug-näkymään tai smoke-testiin ja kertoo ilman debuggeria, miksi tapahtumat eivät kulje.

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

Pakota flush testiharnessista — odottaa enintään timeoutMs yhden verkkokierroksen ajan:

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- ja Fragment-reitit tuottavat heti screen_view-tapahtumat sekä valmiiksi jäsennetyt screen_visit-tietueet, joissa on viipymä- ja kulkutiedot. Jetpack Compose Navigationissa kutsu Kixo.screen LaunchedEffect:sta, jonka avain on route — silloin SDK näkee yhden tapahtuman per kohde riippumatta uudelleenkoostojen määrästä.

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

SDK:n julkinen rajapinta on pieni ja suunniteltu koodintäydennykselle: kaikki metodit ovat Kixo-singletonissa, kaikki tämän oppaan Kotlin-esimerkit alkavat import io.kixo.sdk.Kixo:llä, ja README:ssa on "AI agent quick reference" -lohko, jonka Claude Code, Cursor ja Codex voivat liittää suoraan kontekstiinsa. Jos agentti jää jumiin, käytä lähtökohtana tätä:

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