Android SDK

Το Kixo Android SDK υποστηρίζει Kotlin 2.0+ και Java, απαιτεί minSdk 24 (Android 7.0) και είναι χτισμένο πάνω στο compileSdk 35. Η host app παραμένει υπεύθυνη για το δικό της targetSdk. Μία μόνο κλήση του Kixo.configure στο Application.onCreate σας καταγράφει αυτόματα οθόνες, πατήματα, συνεδρίες, crashes και συμβάντα κύκλου ζωής. Η παρακολούθηση push απαιτεί το bridge FCM που περιγράφεται παρακάτω. Η αυτόματη καταγραφή αιτημάτων δικτύου δεν περιλαμβάνεται στην τρέχουσα έκδοση Android. Το SDK υποστηρίζει επίσης αναπαραγωγή συνεδριών, ταυτότητα και goals.

Γρήγορη εκκίνηση

Τρία αρχεία. Προσθέστε το Maven repo, προσθέστε την εξάρτηση και μετά βάλτε δύο γραμμές στην υποκλάση Application.

Απαιτήσεις build: compileSdk 35, minSdk 24, Kotlin 2.0+ ή Java, και 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")
        }
    }
}

Προσθήκη στην εφαρμογή σας

Το Maven repo του Kixo φιλοξενείται στο GitHub Pages. Προσθέστε το δίπλα στα google() και 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")
        }
    }
}

Έπειτα δηλώστε την εξάρτηση στο app module σας:

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

Έργα με πολλά modules

Η διάταξη implementation του Gradle είναι μη μεταβατικό: αν δηλώσετε το implementation("io.kixo:kixo-android-sdk:0.1.20") σε module βιβλιοθήκης (π.χ. :core_domain), το Kixo ΔΕΝ γίνεται ορατό στο :app ούτε σε οποιονδήποτε άλλο καταναλωτή. Υπάρχουν δύο σωστοί τρόποι — διαλέξτε έναν.

Pattern A — κάθε module που καλεί το Kixo το δηλώνει μόνο του (προτείνεται). Κρατά το classpath κάθε module όσο γίνεται μικρό και αποφεύγει διαδοχικά rebuilds. Χρησιμοποιήστε version catalog (libs.kixo.sdk) ώστε να αλλάζετε την έκδοση σε ένα μόνο σημείο.

// :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 — επανεξαγωγή μέσω του api(...). Μία μόνο δήλωση, αλλά το δημόσιο ABI του module βιβλιοθήκης περιλαμβάνει πλέον τύπους του Kixo — κάθε αλλαγή έκδοσης προκαλεί rebuild σε όλα τα downstream modules. Χρησιμοποιήστε το μόνο όταν η βιβλιοθήκη επαναχρησιμοποιεί τύπους του Kixo στα δικά της δημόσια signatures (π.χ. επιστρέφει 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
}

Αρχικοποίηση

Ρυθμίστε το Kixo από την υποκλάση Application της εφαρμογής σας — το onCreate εκτελείται πριν από οποιοδήποτε activity, ώστε κάθε προβολή οθόνης, πάτημα και συμβάν κύκλου ζωής να καταγράφεται από το πρώτο καρέ. Δηλώστε το Application στο manifest με το 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",
        )
    }
}

Για πιο λεπτομερείς ρυθμίσεις (σημαίες αυτόματης καταγραφής, ρυθμό flush, δειγματοληψία αναπαραγωγής συνεδριών, προσαρμοσμένο API host), δημιουργήστε ρητά ένα KixoConfiguration:

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)

Καταγραφή events

Τρία primitives καλύπτουν το μεγαλύτερο μέρος του instrumentation σας: track για events, markGoal για σήματα μετατροπής και addBreadcrumb για συμφραζόμενα εκτός 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",
)

Τυπικά events

Λεπτό wrapper πάνω από το Kixo.track για τα events που το Kixo αναγνωρίζει από το όνομα — ακριβή string keys που ταιριάζουν με τον ανιχνευτή τυπικών events του backend. Έλεγχος του σχήματος των properties στη μεταγλώττιση, μία ενιαία πηγή αλήθειας για την ονοματοδοσία.

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)

Ταυτοποίηση χρηστών

Συνδέστε τα επόμενα events με ένα σταθερό user id και ένα σύνολο traits. Το anonymous-to-known stitching γίνεται στο Kixo — τα events που καταγράφηκαν πριν από το identify αποδίδονται αναδρομικά στον ίδιο χρήστη.

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

⚠️ Παγίδα με το σύμβολο dollar στην Kotlin. Τα τυπικά κλειδιά ταυτότητας έχουν πρόθεμα $ ($email, $name, $first_name) — και σε string literal της Kotlin πρέπει να κάνετε escape το dollar ως "\$email". Αν γράψετε "$email", γίνεται string interpolation της μεταβλητής email, οπότε η τιμή καταλήγει αθόρυβα ως trait προσαρμοσμένο και δεν συμπληρώνει ποτέ τις στήλες email / name του Audience. Η πιο απλή λύση είναι να χρησιμοποιήσετε το typed overload (SDK 0.1.13+), που δεν μπορεί να γραφτεί λάθος: Kixo.setUserProperty(StandardProperty.EMAIL, email).

Προσθήκη ετικέτας σε χρήστη για τμηματοποίηση

Χρησιμοποιήστε το setUserProperty με τιμή boolean για να προσθέσετε στον χρήστη μια απλή ετικέτα ναι/όχι. Η ετικέτα παραμένει ενεργή και μετά από επανεκκίνηση της εφαρμογής και χρησιμοποιείται σε τμήματα κοινού, email καμπάνιες και ερωτήματα chat — χωρίς καμία άλλη ρύθμιση πέρα από την κλήση του 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",
))

Οι ιδιότητες αποθηκεύονται μέσω του SharedPreferences, παραμένουν διαθέσιμες και μετά από επανεκκίνηση της εφαρμογής και επισυνάπτονται αυτόματα σε κάθε εξερχόμενο event. Στο chat μπορείτε να πείτε πράγματα όπως "στείλε email καλωσορίσματος στους χρήστες όπου το subscribe είναι true" — το Kixo δημιουργεί για εσάς το segment και το πρώτο προσχέδιο του template. Καθαρίζονται στο Kixo.reset().

Τυπικός κατάλογος ιδιοτήτων

Τα δεσμευμένα κλειδιά ιδιοτήτων έχουν πρόθεμα $, ώστε να ξεχωρίζουν από τα δικά σας custom traits. Ο κατάλογος του Kixo καλύπτει 37 κλειδιά σε 3 οριζόντια πακέτα (identity, geo, lifecycle) και 5 κάθετα πακέτα για B2B (subscription, e-commerce, media, marketplace, loyalty). Ορίστε όσα ταιριάζουν στο προϊόν σας — το dashboard προσαρμόζεται και εμφανίζει μόνο τα πακέτα που έχετε συμπληρώσει.

Ταυτότητα

Πάντα σχετικό. Ορίζει τις στήλες στην κεφαλίδα του προφίλ.

Γεωγραφικά στοιχεία

Γεωγραφικό πλαίσιο.

Κύκλος ζωής

Πότε τον είδαμε.

Συνδρομή

Ορίστε το αν το προϊόν σας έχει συνδρομητικά πλάνα.

Ηλεκτρονικό εμπόριο

Ορίστε το αν πουλάτε προϊόντα.

Μέσα

Ορίστε το αν δημοσιεύετε περιεχόμενο.

Marketplace

Ορίστε το αν το προϊόν σας είναι πλατφόρμα δύο πλευρών.

Πιστότητα

Ορίστε το αν έχετε προγράμματα αφοσίωσης και επιβράβευσης.

Super-properties

Ζεύγη κλειδιού/τιμής ανά συνεδρία, που επισυνάπτονται αυτόματα σε κάθε εξερχόμενο event. Διαφέρουν από τα traits identify (που περιγράφουν την ταυτότητα)· τα super-properties περιγράφουν το πλαίσιο της συνεδρίας — ενεργή παραλλαγή A/B, build flavor, feature flags με συγκατάθεση. Παραμένουν αποθηκευμένα και μετά από επανεκκίνηση της εφαρμογής· καθαρίζονται στο reset(). Σε σύγκρουση, τα properties ανά event στο 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

Δύο διαδρομές ενσωμάτωσης. Επιλέξτε την A αν χρησιμοποιείτε FCM και θέλετε το συντομότερο λειτουργικό setup· επιλέξτε την B αν έχετε ήδη custom FirebaseMessagingService που δεν μπορείτε να αναδομήσετε ή αν θέλετε ρητό έλεγχο στο ποιες παραδόσεις FCM βλέπει το Kixo.

Επιλογή A — κάντε extend το KixoFirebaseMessagingService (αυτόματη καταγραφή)

Κάντε subclass το KixoFirebaseMessagingService και καλέστε το super.onMessageReceived(...) μέσα στο override σας — το Kixo εκπέμπει αυτόματα το push_received (ορατό payload) ή το push_silent (μόνο data). Η βασική κλάση χειρίζεται επίσης την καταχώριση onNewToken, αν δεν την κάνετε override. Η καταχώριση AndroidManifest.xml παραμένει ίδια με ενός κανονικού service 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
    }
}

Επιλογή B — καλέστε το χειροκίνητο API από τη δική σας υπηρεσία FCM

Καταχωρίστε το FCM token σας στο Kixo μέσω του FirebaseMessagingService.onNewToken και έπειτα καταγράψτε ρητά κάθε παράδοση. Χρησιμοποιήστε αυτή τη διαδρομή όταν θέλετε το Kixo να βλέπει μόνο ένα υποσύνολο από τις παραδόσεις FCM. Η παρακολούθηση παραδόσεων στο Android υποστηρίζει προς το παρόν μόνο 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 δεν παρέχει καθολικό lifecycle hook για ανοίγματα, απορρίψεις ή κουμπιά ενεργειών ειδοποιήσεων. Προωθήστε αυτά τα σήματα από τα notification intents ή τους receivers που δημιουργεί η εφαρμογή σας:

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

Αναπαραγωγή συνεδρίας

Αναπαράγετε μια πραγματική οπτική ανασύνθεση όσων είδε ο χρήστης. Σε κάθε λήψη, το SDK κωδικοποιεί ένα συμπιεσμένο καρέ της οθόνης (εικόνα JPEG) μαζί με ένα δομικό στιγμιότυπο της ιεραρχίας προβολών και μεταφορτώνει και τα δύο — ώστε το πρόγραμμα αναπαραγωγής στο dashboard να αποδίδει αναπαραγωγή με ακρίβεια pixel δίπλα στο χρονολόγιο αλληλεπιδράσεων. Ρυθμίστε την αναπαραγωγή συνεδριών για το project στο Πίνακας ελέγχου → Ρυθμίσεις → Αναπαραγωγή συνεδρίας. Το SDK διαβάζει και ανανεώνει αυτόματα αυτή την πολιτική του project, μαζί με τις ρυθμίσεις απόκρυψης, τις λειτουργίες λήψης και την άδεια μεταφόρτωσης μέσω κινητού δικτύου.

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)

Όταν η μεταφόρτωση μέσω κινητού δικτύου είναι απενεργοποιημένη, η αναπαραγωγή συνεδριών που βρίσκεται στην ουρά περιμένει μέχρι να υπάρξει επιτρεπόμενο δίκτυο.

Συλλογή δεδομένων

Το SDK καταγράφει τα δεδομένα που έχετε ενεργοποιήσει στο project σας, καθώς και τα συμβάντα και τις ιδιότητες που στέλνει η εφαρμογή σας.

Αποσφαλμάτωση

Το Kixo.diagnostics() επιστρέφει ένα στιγμιότυπο μόνο για ανάγνωση της κατάστασης του SDK — χρήσιμο σε κρυφή οθόνη αποσφαλμάτωσης ή σε smoke test. Απαντά στο «γιατί δεν φεύγουν τα events μου;» χωρίς 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

Επιβάλετε flush από το test harness σας — μπλοκάρει έως timeoutMs για μία διαδρομή δικτύου με επιστροφή:

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 παράγουν άμεσα screen_viewevents και δομημένες εγγραφές screen_visit με μεταδεδομένα διάρκειας παραμονής και ροής, χωρίς επιπλέον ρύθμιση. Για Jetpack Compose Navigation, καλέστε το Kixo.screen από ένα LaunchedEffect με κλειδί τη διαδρομή — έτσι το SDK βλέπει ένα event ανά προορισμό, ανεξάρτητα από τον αριθμό των 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()
        }
    }
}

πράκτορες προγραμματισμού AI

Το δημόσιο API του SDK είναι μικρό και φτιαγμένο για code completion — κάθε μέθοδος βρίσκεται στο singleton Kixo, κάθε παράδειγμα Kotlin σε αυτόν τον οδηγό ξεκινά με import io.kixo.sdk.Kixo, και το README μας περιλαμβάνει ένα block «AI agent quick reference» που εργαλεία όπως Claude Code, Cursor και Codex μπορούν να επικολλήσουν απευθείας στο context τους. Αν ο agent σας κολλήσει, η ενδεδειγμένη αφετηρία είναι:

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