Skip to content
Featureflip Docs

Android Feature Flags Quickstart

This guide gets you from zero to evaluating a feature flag in an Android application. The SDK is a client-side SDK — flags are evaluated server-side and only values are returned.

Prerequisites

Section titled “Prerequisites”
  • A Featureflip account with at least one feature flag created
  • A client SDK key from your environment settings
  • Flags you want to use must have Client-side visible enabled
  • Android API 26+ / Kotlin 2.3+ (if your app uses Kotlin) / Java 17+

Install

Section titled “Install”

Add the dependency to your build.gradle.kts:

dependencies {
    implementation("io.featureflip:featureflip-android:3.4.0")
}

Or with Groovy DSL (build.gradle):

dependencies {
    implementation 'io.featureflip:featureflip-android:3.4.0'
}

Initialize the client

Section titled “Initialize the client”
import dev.featureflip.android.FeatureflipClient
import dev.featureflip.android.FeatureflipConfig


val config = FeatureflipConfig(
    clientKey = "your-client-sdk-key",
    context = mapOf("user_id" to "user-123"),
)


val client = FeatureflipClient.get(config)
client.initialize()

FeatureflipClient.get() is the only way to obtain a client — the public constructor was removed in v2.0. The factory dedupes by client key, so calling get() multiple times with the same key returns handles pointing at one shared underlying client. This makes the SDK safe to call from per-Activity or per-ViewModel constructors without leaking SSE connections. See Lifetime in the reference for details.

initialize() loads cached flags from disk, fetches fresh values from the evaluation API, and starts SSE streaming for real-time updates. Call from a background thread to avoid blocking the UI.

Evaluate a flag

Section titled “Evaluate a flag”
val showBanner = client.boolVariation("new-banner", false)


if (showBanner) {
    println("Showing the new banner")
} else {
    println("Using the default experience")
}

The second parameter is the default value, returned when the flag is missing or has an unexpected type.

Other variation methods are available for different value types:

val color = client.stringVariation("banner-color", "blue")
val limit = client.numberVariation("rate-limit", 100.0)

Clean up

Section titled “Clean up”

Close the client when your app is shutting down:

client.close()

If androidx.lifecycle:lifecycle-process is on your classpath, the SDK pauses streaming when the app goes to the background and resumes when it returns.

How it works

Section titled “How it works”

The Android SDK is a client-side SDK — flags are evaluated on the Featureflip server, not locally in your app. On initialization, the SDK sends the user context to the evaluation API and receives pre-evaluated flag values. It then opens an SSE (Server-Sent Events) connection that pushes updates in real-time whenever flags change in the dashboard.

Flag values are cached to disk, so your app has working values immediately on launch while the SDK fetches fresh data in the background. With androidx.lifecycle:lifecycle-process on the classpath, the SDK also closes the SSE connection while the app is in the background and reopens it when the app returns, which saves battery.

Troubleshooting

Section titled “Troubleshooting”

initialize() blocks the UI thread

initialize() performs network requests and should be called from a background thread or coroutine. Use kotlinx.coroutines to call it from an IO dispatcher: withContext(Dispatchers.IO) { client.initialize() }. On the main thread, it can cause ANR (Application Not Responding) errors.

Flag values are always defaults

Verify you are using a client SDK key (not a server SDK key). Client and server keys are different — using the wrong type results in authentication errors or empty responses. Also confirm that the flags you want to access have Client-side visible enabled in the dashboard.

Gradle sync fails after adding the dependency

The SDK requires Android API 26+ and Java 17+, and Kotlin 2.3+ if your app is written in Kotlin. Check your build.gradle.kts has minSdk = 26 and your JDK version is 17 or later. If using an older JDK, update it in Android Studio’s settings under Build → Build Tools → Gradle → Gradle JDK.

Next steps

Section titled “Next steps”