Android SDK

Kixo Android SDK, Kotlin 2.0+ ve Java’yı destekler; en az minSdk 24 (Android 7.0) gerektirir ve compileSdk 35 karşısında derlenmiştir. Ana uygulamanız kendi targetSdk yapılandırmasından yine kendisi sorumludur. Application.onCreate içinde yapacağınız tek bir Kixo.configure çağrısı; ekranları, dokunuşları, oturumları, çökmeleri ve yaşam döngüsü olaylarını otomatik olarak izler. Push takibi için aşağıda açıklanan FCM köprüsü gerekir. Ağ isteği otomatik takibi, mevcut Android sürümünün bir parçası değildir. SDK ayrıca oturum yeniden oynatma, kimlik ve hedefleri de destekler.

Hızlı başlangıç

Üç dosya yeterli. Maven deposunu ekleyin, bağımlılığı ekleyin, ardından Application alt sınıfınıza iki satır bırakın.

Derleme gereksinimleri: compileSdk 35, minSdk 24, Kotlin 2.0+ veya Java ve 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")
        }
    }
}

Uygulamanıza ekleyin

Kixo Maven deposu GitHub Pages üzerinde barındırılır. settings.gradle.kts içinde bunu google() ve mavenCentral() ile birlikte ekleyin:

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

Ardından bağımlılığı uygulama modülünüzde tanımlayın:

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

Çok modüllü projeler

Gradle’ın implementation yapılandırması transitif değil niteliktedir: bir kütüphane modülünde (ör. :core_domain) implementation("io.kixo:kixo-android-sdk:0.1.20") tanımlamanız, Kixo öğesini :app veya başka bir tüketici için görünür kılmaz. İşe yarayan iki yaklaşım var — birini seçin.

Desen A — Kixo çağıran her modül bunu kendisi bildirir (önerilir)., her modülün classpath’ini olabildiğince küçük tutar ve zincirleme yeniden derlemeleri önler. Sürümü tek yerden yönetmek için sürüm kataloğu (libs.kixo.sdk) kullanın.

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

Desen B — api(...) üzerinden yeniden dışa aktarın. Tek bir bildirim yeterlidir; ancak kütüphane modülünün herkese açık ABI’si artık Kixo türlerini de içerir. Bu da her sürüm artışında aşağı akıştaki tüm modüllerin yeniden derlenmesine yol açar. Bunu yalnızca kütüphane, kendi herkese açık imzalarında Kixo türlerini yeniden kullanıyorsa tercih edin (örneğin bir fonksiyon KixoDiagnostics döndürüyorsa).

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

Başlatma

Kixo’yu Application alt sınıfınızda yapılandırın — onCreate, herhangi bir activity’den önce çalışır; böylece her ekran görüntülemesi, dokunuş ve yaşam döngüsü olayı ilk kareden itibaren yakalanır. Application öğesini manifest’inize android:name=".MyApp" ile kaydedin.

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

Daha ayrıntılı ayarlar için (otomatik izleme bayrakları, gönderim sıklığı, yeniden oynatma örneklemesi, özel API ana makinesi) KixoConfiguration nesnesini açıkça oluşturun:

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)

Olayları izleyin

Enstrümantasyonunuzun büyük kısmını üç temel yapı taşır: olaylar için track, dönüşüm sinyalleri için markGoal ve olay dışı bağlam için addBreadcrumb.

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

Standart olaylar

Kixo’nun ada göre tanıdığı olaylar için Kixo.track üzerinde bir kolaylık katmanı — arka uçtaki standart olay algılayıcısının bire bir eşleştirdiği düz string anahtarlar. Özellik yapısını derleme zamanında doğrular ve adlandırma için tek bir kaynak sağlar.

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)

Kullanıcıları tanımlayın

Sonraki olayları kalıcı bir kullanıcı kimliğine ve trait kümesine bağlayın. Anonimden bilinene eşleme Kixo içinde yapılır; identify öncesinde yakalanan olaylar geriye dönük olarak aynı kullanıcıya atanır.

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’de dolar işareti tuzağı. Standart kimlik anahtarları $ önekini kullanır ($email, $name, $first_name) — Kotlin sabit dizelerinde dolar işaretini "\$email" yazarak gerekir kaçırmanız gerekir. "$email" yazarsanız email değişkeniniz dize içine yerleştirilir; değer de fark edilmeden bir özel trait’i olarak kaydolur ve Audience içindeki e-posta / ad sütunlarını doldurmaz. En pratik çözüm, tür güvenli overload’ı kullanmaktır (SDK 0.1.13+): Kixo.setUserProperty(StandardProperty.EMAIL, email).

Segmentasyon için kullanıcı etiketleyin

Kullanıcıya basit bir evet/hayır etiketi eklemek için setUserProperty metodunu boolean değerle kullanın. Bu etiket uygulama yeniden açıldığında da korunur ve segmentler, e-posta kampanyaları ve sohbet sorgularında kullanılır — SDK çağrısının dışında ek kurulum gerekmez.

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

Özellikler SharedPreferences üzerinden uygulama yeniden başlatmaları arasında korunur ve her giden olaya otomatik eklenir. Sohbette "subscribe değeri true olan kullanıcılara hoş geldin e-postası gönder" gibi şeyler yazın — Kixo sizin için segmenti oluşturur ve şablon taslağını hazırlar. Kixo.reset() ile temizlenir.

Standart özellik kataloğu

Ayrılmış özellik anahtarları, özel trait'lerinizle çakışmaması için $ öneki taşır. Kixo kataloğunda 3 evrensel paket (kimlik, coğrafya, yaşam döngüsü) ve 5 B2B dikey paketinde (abonelik, e-ticaret, medya, pazaryeri, sadakat) toplam 37 anahtar bulunur. Ürününüz için geçerli olanları ayarlayın; pano buna uyum sağlar ve yalnızca doldurduğunuz paketleri gösterir.

Kimlik

Her zaman anlamlıdır. Profil başlığındaki sütunları belirler.

Coğrafi

Coğrafi bağlam.

Yaşam döngüsü

Onu ne zaman gördük?

Abonelik

Ürününüzde planlar varsa ayarlayın.

E-ticaret

Ürün satıyorsanız ayarlayın.

Medya

İçerik yayımlıyorsanız ayarlayın.

Pazaryeri

İki taraflı bir platformsanız ayarlayın.

Sadakat

Etkileşim ve ödül programları için ayarlayın.

Super-properties

Her giden olaya otomatik eklenen, oturum düzeyindeki anahtar/değer çiftleri. identify trait’lerinden farklıdırlar; trait’ler kimliği tanımlar, super-property’ler ise oturum bağlamını tanımlar — etkin A/B varyantı, build flavor, izin verilmiş özellik bayrakları gibi. Uygulama yeniden açıldığında da korunur; reset() ile temizlenir. Aynı anahtar çakıştığında, track üzerindeki olay bazlı properties her zaman önceliklidir.

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 bildirimleri

İki entegrasyon yolu var. FCM kullanıyor ve en kısa çalışan kurulumu istiyorsanız A’yı seçin; yeniden yapılandıramayacağınız özel bir FirebaseMessagingService yapınız varsa ya da Kixo’nun hangi FCM teslimatlarını göreceğini açıkça denetlemek istiyorsanız B’yi seçin.

Seçenek A — KixoFirebaseMessagingService sınıfını genişletin (otomatik izleme)

KixoFirebaseMessagingService sınıfından türeyin ve override ettiğiniz metodun içinden super.onMessageReceived(...) çağrın — Kixo, push_received (görünür payload) veya push_silent (yalnızca veri) olayını otomatik olarak gönderir. Override etmezseniz taban sınıf onNewToken kaydını da yönetir. AndroidManifest.xml kaydı ise normal bir FCM servisindekiyle aynıdır.

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

Seçenek B — kendi FCM servisinizden API’yi elle çağırın

FCM token’ınızı FirebaseMessagingService.onNewToken üzerinden Kixo’ya kaydedin, ardından her teslimatı açıkça loglayın. Kixo’nun yalnızca FCM teslimatlarının bir bölümünü görmesini istiyorsanız bu yolu kullanın. Android teslimat takibi şu anda yalnızca FCM’yi destekler.

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, bildirim açılmaları, kapatılmaları veya işlem düğmeleri için evrensel bir yaşam döngüsü kancası sağlamaz. Bu sinyalleri, uygulamanızın oluşturduğu bildirim intent’lerinden veya receiver’lardan iletin:

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

Oturum yeniden oynatma

Kullanıcının gördüğünü gerçek, görsel bir yeniden kurulumla oynatın. SDK, her yakalamada ekranın sıkıştırılmış bir karesini (bir JPEG görseli) görünüm hiyerarşisinin yapısal anlık görüntüsüyle birlikte kodlayıp yükler; böylece panodaki oynatıcı, etkileşim zaman çizelgesinin yanında piksel düzeyinde doğru bir oynatma sunabilir. Proje için yeniden oynatmayı Kontrol Paneli → Ayarlar → Oturum tekrarı içinde yapılandırın. SDK, maskeleme, yakalama modları ve hücresel ağ üzerinden yükleme izni dâhil bu proje politikasını otomatik olarak okuyup yeniler.

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)

Hücresel ağ üzerinden yükleme kapalıysa kuyruğa alınan yeniden oynatmalar izin verilen bir ağı bekler.

Veri toplama

SDK, projenizde etkin olan verileri ve uygulamanızın gönderdiği olaylarla özellikleri yakalar.

Hata ayıklama

Kixo.diagnostics(), SDK’nin durumuna dair salt okunur bir anlık görüntü döndürür. Gizli bir hata ayıklama ekranında veya smoke test’te özellikle işe yarar. “Olaylarım neden akmıyor?” sorusunu debugger açmadan yanıtlar.

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

Test altyapınızdan zorla gönderim başlatın — ağ gidiş dönüşü için en fazla timeoutMs boyunca bloklar:

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 rotaları, ek kurulum gerektirmeden anında screen_view olayları ve kalma süresiyle akış metaverisini içeren yapılandırılmış screen_visit kayıtları üretir. Jetpack Compose Navigation kullanıyorsanız, rotaya göre anahtarlanmış bir LaunchedEffect içinden Kixo.screen çağırın; böylece SDK, yeniden bileşim sayısı ne olursa olsun her hedef için tek bir olay görür.

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 kodlama ajanları

SDK’nin herkese açık yüzeyi küçüktür ve kod tamamlama için tasarlanmıştır — tüm metodlar Kixo singleton’ındadır, bu kılavuzdaki tüm Kotlin örnekleri import io.kixo.sdk.Kixo ile başlar ve README içinde Claude Code, Cursor ve Codex gibi araçların bağlamına doğrudan yapıştırabileceği bir "AI agent quick reference" bloğu bulunur. Ajanınız takılırsa temel başlangıç örneği şudur:

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