Skip to content
NanoFlags
Start free

SDKs

Android and Kotlin SDK

The Android SDK evaluates flags on the device, kept current by a live WebSocket, verified with Ed25519 signatures and stored for an offline-first start. The core is pure Kotlin/JVM; the Android module adds the app lifecycle, connectivity (offline, metered networks, Data Saver), on-device storage and Jetpack Compose helpers.

Install

build.gradle.kts
dependencies {
    implementation("io.nanoflags:nanoflags-android:0.1.0")
    // implementation("io.nanoflags:nanoflags-openfeature:0.1.0")   // OpenFeature provider
}

The artifacts are on Maven Central; mavenCentral() in your repositories is all you need.

ArtifactWhat it is
io.nanoflags:nanoflags-corePure Kotlin/JVM: the evaluation engine, signature verification, transport (live WebSocket, SSE, polling with ETag) and the client. Runs on Android and any JVM.
io.nanoflags:nanoflags-androidAndroid wiring: ProcessLifecycleOwner, ConnectivityManager (offline, metered networks, Data Saver), storage in noBackupFilesDir, Jetpack Compose helpers. minSdk 21.
io.nanoflags:nanoflags-openfeatureProvider for the official OpenFeature Kotlin SDK (dev.openfeature:kotlin-sdk 0.9).
  • The engine is tested against the shared parity fixtures (21,998 cases, plus murmur3, bucket and browser-view vectors) on the JVM and on an Android emulator, with results identical to every other NanoFlags SDK.
  • Apache-2.0. Source in the nanoflags-sdk repository.

Client keys

Apps use browser/client keys (nf_pub_…) only: they receive the client view of the environment (client-exposed flags and only the segments those flags reference). Server keys (nf_srv_…) are refused by the constructor.

Quickstart

App.kt
class App : Application() {
    lateinit var flags: NanoFlags

    override fun onCreate() {
        super.onCreate()
        flags = NanoFlagsAndroid.create(this, "nf_pub_…") {
            context = NanoFlagsContext("anonymous", mapOf("platform" to "android"))
        }
    }
}

// Anywhere: local and synchronous (no I/O). On any problem the default is returned.
if (flags.boolVariation("new-checkout", false)) showNewCheckout()
val accent = flags.stringVariation("accent", "blue")

// After sign-in: changes every evaluation at once, no network round trip.
flags.identify(NanoFlagsContext(user.id, mapOf("plan" to user.plan, "country" to user.country)))

Wait for the first configuration, for example behind a splash screen:

kotlin
lifecycleScope.launch {
    val ready = flags.waitUntilReady(timeoutMs = 3_000) // true when a configuration is in use (network, storage or bootstrap)
}

Jetpack Compose and Flows

kotlin
setContent {
    ProvideNanoFlags(flags) {
        val newCheckout by rememberFlag("new-checkout", false) // recomposes on every new configuration or identify()
        if (newCheckout) NewCheckout() else OldCheckout()
    }
}
// or with any Flow API:
flags.boolFlow("new-checkout", false).collectAsState(initial = false)

API

MemberWhat it does
boolVariation, stringVariation, doubleVariation, intVariation, jsonVariationTyped values; a value of another type returns the default with reason error. Each has a …Detail variant returning an EvaluationDetail (value, reason, ruleIndex, ruleId, inRollout, bucket, revision, trace). An optional last parameter evaluates for another context.
evaluate(key, default) · allFlags() · allFlagsDetail()Untyped evaluation · every flag of the configuration.
identify(context) · setContext(context) · context: StateFlowThe client's evaluation context. NanoFlagsContext(key, attributes); key is the bucketing identity for percentage rollouts.
boolFlow, stringFlow, … allFlagsFlowCold flows of a value for the current context, distinct, re-evaluated on every new configuration or context.
changes: SharedFlow<ChangeEvent>Every adopted configuration (revision, previousRevision, source, transport, latencyMs from commit to device for pushed revisions).
status: StateFlow<Status>NOT_READY, READY (known current), STALE (in use but not confirmed: offline, restored from storage, environment deleted).
transport: StateFlow<Transport>LIVE, STREAM, POLL, PAUSED (background, offline or the network policy).
errors: SharedFlow<NanoFlagsException>Background problems (code: network, http, unauthorized, invalid_bundle, signature, engine, store, environment_deleted). They never change the configuration in use.
waitUntilReady · refresh · flush · closeSuspending helpers and shutdown.
addChangeListener, addStatusListener, addErrorListenerCallback alternatives for Java (close the returned handle to unregister).

Options

NanoFlagsOptions: baseUrl (default https://edge.nanoflags.io), service (Android: the application id), context, bootstrap (bundle JSON shipped in the app), store (Android: a file in noBackupFilesDir; null disables persistence), verify, live (WebSocket, default on), streaming, pollIntervalMs (30 s without a socket), livePollIntervalMs (5 min safety poll), meteredPolicy (default LIVE), dataSaverPolicy (default POLL: no socket while Data Saver restricts background data), events { enabled, sampleRate, flushIntervalMs, reportIntervalMs, redact }, httpClient (an OkHttpClient to build on: proxies, pinning, interceptors), requestTimeoutMs, dispatcher and logger.

Live updates and lifecycle

  1. Live WebSocket GET /v1/live (key in the Authorization header, never in a URL). The edge pushes each revision with its signed bundle; the client verifies it, swaps it in atomically and emits a ChangeEvent. Ping about every 30 seconds, the socket is replaced about every 50 minutes, and reconnects use jittered backoff (1 s · 2ⁿ, up to 5 minutes). Close code 4004: no reconnect, the last configuration stays in use as STALE.
  2. SSE /v1/stream while no socket can be opened, then polling of /v1/bundle with If-None-Match.

Mobile lifecycle (nanoflags-android): in the background the socket is closed and polling stops (queued telemetry is sent first); on return to the foreground the client reconnects and revalidates at once if the configuration may be out of date. Without a network nothing is attempted; when the network returns, the client revalidates. The bundle is persisted after every update and verified again when loaded.

Signature verification

Every bundle from the official edge must carry a valid Ed25519 signature (by key id); unsigned or tampered bundles are refused and the configuration in use is unchanged. The production keys are embedded; an unknown key id (a rotation) loads GET /v1/keys once, at most once a minute. The first verified environment id is pinned, so a bundle signed for another environment is refused. The verifier is BouncyCastle's lightweight Ed25519Signer, which works from API 21. Bundles that need a newer engine are refused. See Security.

OpenFeature provider

kotlin
implementation("io.nanoflags:nanoflags-openfeature:0.1.0")

OpenFeatureAPI.setProviderAndWait(NanoFlagsProvider(flags), initialContext = ImmutableContext("user-42"))
val on = OpenFeatureAPI.getClient().getBooleanValue("new-checkout", false)

targetingKey becomes key; reasons DISABLED (off), DEFAULT, TARGETING_MATCH (fixed rule) and SPLIT (rollout); the variant is the rule id; setEvaluationContext calls identify; configuration and status changes are provider events.

Telemetry

Like the other SDKs: a service report and sampled evaluation events (10 %), reported as android/0.1.0 (or kotlin/0.1.0 on the JVM). Events carry the names of the attributes the flag's rules use and the type of their values, never values. They are sent only while the app is in the foreground and online. Opt out with events { enabled = false }.

Troubleshooting

  1. The constructor refuses the key. Use a browser/client key (nf_pub_…).
  2. A flag always returns its default. Mark it client-exposed and publish.
  3. Code signature. A bundle did not verify and was not used. With a custom baseUrl, pin that edge's keys in verify.
  4. Transport stays PAUSED. The app is in the background, offline, or Data Saver restricts background data (dataSaverPolicy).
Other mobile platforms
Native SDKs exist for iOS (Swift), Flutter and React Native, with the same engine and the same results.