Quickstart

Android Quickstart

Get the Convert Android SDK running and serving your first experiment. This page is the fast path; for the conceptual background read Quickstart Overview and How Convert Works first.

You need an SDK Key from your Convert dashboard and an Android project on minSdk 24 or higher.

1. Add the dependency

Declare Maven Central in settings.gradle.kts, then add the SDK to your app module:

// settings.gradle.kts
dependencyResolutionManagement {
    repositories {
        mavenCentral()
        google()
    }
}

// app/build.gradle.kts
dependencies {
    implementation("com.convert:sdk-android:+") // pin a specific version in production
}

See Installation for JDK and SDK-level requirements, R8 notes, and permissions.

2. Initialize once in Application.onCreate()

ConvertSDK owns a coroutine scope, an offline queue, and background workers, so create exactly one instance per process.

import android.app.Application
import com.convert.sdk.android.ConvertSDK
import com.convert.sdk.core.model.LogLevel

class MyApp : Application() {
    lateinit var convertSdk: ConvertSDK

    override fun onCreate() {
        super.onCreate()
        convertSdk = ConvertSDK.builder(this)
            .sdkKey("YOUR_SDK_KEY")  // from your Convert dashboard
            .logLevel(LogLevel.INFO) // DEBUG while integrating
            .build()
    }
}

Register the class in AndroidManifest.xml:

<application android:name=".MyApp" ... />

3. Wait for config, then run an experience

The SDK fetches its bucketing config in the background. onReady { ... } fires once decisions are available; calls made before that return null.

val sdk = (application as MyApp).convertSdk

sdk.onReady {
    val ctx = sdk.createContext() // auto-persisted UUID visitor id
    val variation = ctx.runExperience("homepage-redesign")
    when (variation?.key) {
        "control" -> renderControl()
        "treatment" -> renderTreatment()
        null -> renderControl() // not ready / visitor not bucketed
    }
}

onReady dispatches on Dispatchers.Default. Marshal back to the main thread before touching UI.

4. Track a conversion

import com.convert.sdk.core.model.GoalData
import com.convert.sdk.core.model.GoalDataKey
import kotlinx.serialization.json.JsonPrimitive

val ctx = sdk.createContext()

// Bare conversion.
ctx.trackConversion("signup-completed")

// With transactional goal data.
ctx.trackConversion(
    goalKey = "purchase-completed",
    goalData = listOf(
        GoalData(key = GoalDataKey.AMOUNT, value = JsonPrimitive(49.99)),
        GoalData(key = GoalDataKey.TRANSACTION_ID, value = JsonPrimitive("tx-42")),
    ),
)

trackConversion is fire-and-forget. Events are batched, persisted to disk, and flushed in the background — they survive an offline device and an app restart. See Offline Behavior.

Next steps

• Initialization — onReady, direct-data mode, event subscription
• Configuration Options — every builder option
• Code Examples — complete Kotlin and Java snippets for every method
• Running Experiences — the cross-SDK guide