Feature Flag SDK

• ✓Evaluate typed flags via getBoolean / getString / getInt / getJson from any thread
• ✓Apply targeting rules against developer-supplied user attributes
• ✓Compute sticky percentage rollouts deterministically from user ID + flag key
• ✓Pick up a flag change within seconds when the server can reach the device, and within minutes when it can't
• ✓Honor a global kill switch that disables a flag regardless of targeting
• ✓Buffer and upload exposure events for A/B analysis
• ✓Persist last-known-good flag set across kill, reboot, and reinstall on user data

• Evaluation costgetBoolean() <10 µs amortised; no I/O, no locks on the hot path
• Fail-openAny internal exception returns the developer-supplied default; SDK never throws
• Init costflags.initialize() <3 ms wall-clock; first eval succeeds before first frame
• Push latency<5 s from console to client while the device is reachable
• Fallback cadence15 min default; configurable; respects battery constraints
• Binary sizeCore <300 KB shrunk; no kotlin-reflect

Flags.initialize(context, sdkKey = "client-abc123") {
    user("u_123") {                                       // immutable User snapshot
        attribute("plan", "premium")
        attribute("country", "DE")
        attribute("install_age_days", 42)
    }
    bundledDefaults(R.raw.flags_defaults_json)            // R.raw = Android build-time resource bundle; see dd1
    streaming(true)                                       // SSE on; falls back to polling
    pollInterval(15.minutes)
    onUpdate { changed ->                                 // optional callback for live UI refresh
        if ("checkout_v2" in changed) refreshCheckoutScreen()
    }
}
 
// Evaluation - typed, default-required, fail-open.
val newCheckout = Flags.getBoolean("checkout_v2", default = false)
val theme       = Flags.getString("ui_theme", default = "system")
val limit       = Flags.getInt("rate_limit_rpm", default = 60)
val config      = Flags.getJson<PricingConfig>("pricing_config", default = PricingConfig.SAFE)
 
Flags.identify(newUser)                                   // attribute change; re-evaluates locally
Flags.refresh()                                           // force a sync; fire-and-forget

The default argument is also the type witness and the fail-open value - if the SDK can't evaluate (no cache, exception, kill switch), the default is what flows. See the fail-open and bootstrap deep dives below.

The core axis is execution context, one lane per context: init at the top seeds the snapshot, the lock-free eval-time read sits under it, the background refresh lane below that updates it, and the server sits at the bottom. Read and refresh run concurrently around two pieces of shared state - the on-disk cache (the lifetime handoff that lets a cold start evaluate flags before any network call returns) and the in-memory @Volatile snapshot (the cross-thread handoff that lets any thread read without a lock). Both straddle the Eval/Refresh boundary rather than sitting inside either lane, because the contexts that write them are never the context that reads them. Arrows are data flow: flag values move from their source to the eval call site, which passes the user ID on to the bucketer.

The evaluation path reads a single @Volatile FlagSnapshot reference - no locks, no I/O. The refresh path pulls flag sets from the server (SSE push, poller backstop), merges them, and publishes atomically by swapping the reference and persisting to the cache. The cache sits between refresh and eval-time because it is the contract between execution contexts that don't share a process lifetime: refresh rewrites it on every flag change, and a cold-start eval reads it before the network has answered. Bundled defaults seed the snapshot directly at init, never via the cache; the cache restores the last-known-good set on cold start before any network call returns. Each evaluation also records to an ExposureBuffer that is drained by an UploadWorker to /v1/exposures:batch - the same drain pattern as the analytics pipeline, not shown here because it is a side-output, not part of the flag data flow.

1. Flags.initialize() registers the user snapshot, sets a @Volatile reference to a FlagSnapshot built from R.raw.flags_defaults_json, and returns within ~2 ms. The app is free to render.
2. On the SDK's background thread, the cache loader reads the last-known-good flag set from DataStore (Jetpack's on-disk key-value store). If present and not expired, it replaces the snapshot reference atomically (AtomicReference.set).
3. Flags.getBoolean("checkout_v2", false) reads the current snapshot, finds the flag rule, evaluates against the user attributes, applies sticky bucketing if the rule is a percentage rollout, and returns the variant. Total time: ~5 µs.
4. The evaluation also calls exposureBuffer.record("checkout_v2", "variant_A", user.id); the buffer is drained by an UploadWorker like the analytics pipeline.
5. The SSE client connects to /v1/flags/stream; the server sends a full eval-set (the server-delivered bundle of flag rules) on connect, then a delta whenever a flag changes.
6. On delta, FlagSetMerger builds a new immutable FlagSnapshot from the previous + delta, persists it to DataStore, then publishes it via AtomicReference.set.
7. The onUpdate callback fires with the set of changed keys so UI code can refresh affected screens.
8. If SSE disconnects, the periodic WorkManager (deferred background scheduler) poller runs every 15 minutes and pulls the full eval-set as a backstop - no flag change is lost for more than the poll interval.