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 21+ / Kotlin 1.9+ / Java 17+

Install

Section titled “Install”

Add the dependency to your build.gradle.kts:

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

Or with Groovy DSL (build.gradle):

dependencies {
    implementation 'io.featureflip:featureflip-android:1.0.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()

The SDK automatically pauses streaming when the app enters the background and resumes on foreground.

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. When the app moves to the background, the SDK pauses the SSE connection to conserve battery and resumes it when the app returns to the foreground.

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 21+ and Java 17+. Check your build.gradle.kts has minSdk = 21 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”