Kotlin / Android SDK | Documentation

The Kotlin SDK integrates directly with the Android Activity and Application lifecycle. Initialize it once from your Application class and it handles everything automatically — no manual screen calls needed for Activity-based screens.

Prerequisites

Min SDKAndroid API 21 (Android 5.0+)

LanguageKotlin 1.9+ recommended

Build toolGradle (Kotlin DSL or Groovy)

Installation

Add the dependency

app/build.gradle.ktsKotlin

dependencies {
    implementation("app.flashanalytics:flashanalytics-kotlin:1.1.4")
}

Sync your Gradle project after adding the dependency.

Initialize in Application.onCreate()

Initialize exactly once from your Application class so the SDK is ready before any Activity starts.

MyApp.ktKotlin

import android.app.Application
import app.flashanalytics.sdk.CaptureVariantsOptions
import app.flashanalytics.sdk.FlashAnalyticsOptions
import app.flashanalytics.sdk.android.FlashAnalyticsAndroid

class MyApp : Application() {
    override fun onCreate() {
        super.onCreate()

        FlashAnalyticsAndroid.init(
            application = this,
            options = FlashAnalyticsOptions(
                appId = BuildConfig.FLASH_APP_ID, // UUID from your dashboard
                captureAppLifecycle = true,
                captureScreenViews = true,
                captureDeepLinks = true,
                captureInstallAttribution = true,
                captureSessionOnInit = true,
                captureNativeCrashes = true,
                captureVariants = CaptureVariantsOptions(),
                batchEnable = true,
                batchSize = 10,
                batchTimeoutMs = 5_000L,
            )
        )
    }
}

Don't forget to register your Application class: android:name=".MyApp" in the <application> tag.

Identify users and track events

Kotlin

val analytics = FlashAnalyticsAndroid.getInstance()

// After login
analytics.identify(
    IdentifyPayload(
        profileId = "user_123",
        email = "user@example.com",
    )
)

// Track a product event
analytics.track("purchase_completed", mapOf(
    "orderId" to "order_123",
    "amount" to 49.99,
))

Auto-capture flags

captureAppLifecycle

app_opened, app_foregrounded, app_backgrounded

captureSessionOnInit

sdk_initialized session warm-up before lifecycle events

captureScreenViews

screen_view on every Activity resume

captureDeepLinks

deep_link_opened for intent URLs

captureInstallAttribution

Install / update attribution

captureNativeCrashes

native_crash report on next launch

captureViewTags

Android View tag auto-tracking helpers

capturePushLifecycle

Push notification lifecycle helpers

captureVariants

A/B experiment auto-assignment

Error tracking

Kotlin

try {
    riskyOperation()
} catch (e: Exception) {
    FlashAnalyticsAndroid.getInstance().trackError(
        throwable = e,
        eventName = "payment_failed",
        properties = mapOf("orderId" to orderId),
    )
}

Deep links (warm start)

For warm-start deep links, forward the new intent from your main activity.

MainActivity.ktKotlin

override fun onNewIntent(intent: Intent) {
    super.onNewIntent(intent)
    setIntent(intent)
    FlashAnalyticsAndroid.getInstance().onNewIntent(intent)
}

Experiments

Kotlin

val analytics = FlashAnalyticsAndroid.getInstance()

// All cached assignments — no API call
val all = analytics.getAllExperiments()

// Cache first, API fallback (suspend)
CoroutineScope(Dispatchers.Main).launch {
    val assignment = analytics.getExperimentById("checkout-cta")
    println(assignment?.variantName)
}

// Callback wrapper for non-coroutine code
analytics.getExperimentByIdAsync("checkout-cta") { result ->
    println(result?.variantName)
}

Global properties

Kotlin

analytics.setGlobalProperties(mapOf(
    "appVersion" to "1.2.0",
    "plan" to "pro",
))

Session updates

The Android SDK sends sdk_initialized on startup by default so the backend can return a session before install, update, and lifecycle events. Use onSessionUpdatedwhen native code needs the current session ID immediately after it is received or restored.

Kotlin

FlashAnalyticsAndroid.init(
    application = this,
    options = FlashAnalyticsOptions(
        appId = BuildConfig.FLASH_APP_ID,
        captureSessionOnInit = true,
        onSessionUpdated = { session ->
            Log.d("FlashAnalytics", session.id)
            Log.d("FlashAnalytics", session.estimatedExpiresAt.toString())
            Log.d("FlashAnalytics", session.estimatedTtlMs.toString())
        },
    )
)

Push notifications

Kotlin

analytics.trackNotificationEvent(
    event = FlashNotificationEvent.OPENED,
    intent = intent,
    source = "android_intent",
    appState = "terminated",
    coldStart = true,
)

Android push tracking requires additional receiver registration, notification intents, and payload forwarding. Map your provider's custom keys to Flash fields: notificationId, messageId, campaignId, provider.

Manual batch flush

Kotlin

// Call when the app goes to background if you manage lifecycle manually
FlashAnalyticsAndroid.getInstance().flushBatch()