Feature Flags on Mobile: Ship Safely and Roll Back Fast

Quickstart

If you only do a few things this week, do these. They’re the highest leverage steps to ship safely and roll back fast without turning your app into a nest of if(flag) statements.

Overview

Mobile releases are uniquely stressful: once an app build is in the store (and installed), you can’t “hotfix” the binary for everyone instantly. Review delays, staged rollout delays, and user update behavior mean bugs can linger longer than on the web. Feature flags on mobile solve this by separating shipping code from exposing behavior.

Core concepts

The fastest way to get feature flags wrong is to treat them as “a boolean from the cloud.” On mobile, flags are a configuration system with strict constraints: startup performance, offline behavior, privacy, and cross-platform consistency.

1) The four flag types you should name explicitly

2) Mobile constraints that change the design

3) The flag lifecycle: ship, ramp, graduate, delete

Feature flags become “flag debt” when they never leave. The clean mental model is a lifecycle: you introduce a flag for a purpose, run it, then remove it when it’s no longer needed.

4) “Fail open” vs “fail closed” (choose per flag)

The most important policy decision is what happens when the flag service is unreachable. There is no universal answer, but there is a universal requirement: it must be deliberate and documented.

5) A tiny flag catalog example (keeps teams aligned)

Whether you use a third-party tool or a custom service, the idea is the same: treat flags as product artifacts with owners, defaults, and rules. Here’s a minimal catalog shape.

flags:
  checkout_v2:
    type: release_toggle
    owner: payments-team
    default: false
    expires_on: "2026-03-31"
    fail_policy: fail_closed
    rules:
      - if_app_version_gte: "3.12.0"
        rollout_percent: 5
      - if_app_version_gte: "3.12.0"
        user_bucket_percent: 25
        segments: ["beta_testers"]
  search_ranker_variant:
    type: experiment
    owner: growth-team
    default: "control"
    expires_on: "2026-02-28"
    fail_policy: fail_open
    variants: ["control", "v2"]
    rules:
      - if_app_version_gte: "3.11.0"
        rollout_percent: 50
  disable_image_uploads:
    type: kill_switch
    owner: mobile-oncall
    default: false
    expires_on: "never"
    fail_policy: fail_closed
    rules:
      - rollout_percent: 0  # set to 100 during incident
metadata:
  schema_version: 1
  updated_at: "2026-01-09T14:21:53+01:00"

The key is not the format—it’s the discipline: every flag has a default, an owner, and a plan for removal.

Step-by-step

This is a pragmatic implementation path that works for native iOS/Android and most cross-platform stacks. The goal is a feature flag system that is fast, offline-safe, and operationally sane.

Step 1 — Decide what should be flaggable

Step 2 — Define a cross-platform contract (keys + types)

Before you write code, align on the contract shared by iOS and Android: stable keys, types, defaults, and how targeting works. This prevents “Android shipped it, iOS didn’t” drift.

Step 3 — Choose a delivery model (and make it cache-first)

Mobile flag delivery is typically either: (1) a dedicated remote config service, (2) flags embedded in your API responses, or (3) a lightweight custom endpoint (JSON) with caching. Whatever you choose, the client rule is the same: read from disk, refresh in background.

Step 4 — Implement the mobile client: typed, cached, and testable

Treat the flag reader as a small local SDK: it loads cached config synchronously, exposes typed getters, and refreshes asynchronously. Keep it behind an interface so UI/business code never cares where flags come from.

Example: a lightweight Android/Kotlin implementation (cache-first, background refresh). Adapt the networking layer and storage to your stack.

import android.content.SharedPreferences
import kotlinx.coroutines.CoroutineScope
import kotlinx.coroutines.Dispatchers
import kotlinx.coroutines.launch
import org.json.JSONObject
import java.util.concurrent.TimeUnit

class FeatureFlags(
  private val prefs: SharedPreferences,
  private val http: SimpleHttpClient,
  private val endpointUrl: String,
  private val scope: CoroutineScope
) {
  private val cacheKeyJson = "ff_cache_json"
  private val cacheKeyEtag = "ff_cache_etag"
  private val cacheKeyFetchedAt = "ff_cache_fetched_at"

  private val ttlMs = TimeUnit.MINUTES.toMillis(15)

  /** Read is synchronous and safe. */
  fun isEnabled(key: String, defaultValue: Boolean = false): Boolean {
    val json = loadCachedJson() ?: return defaultValue
    return json.optBoolean(key, defaultValue)
  }

  fun getString(key: String, defaultValue: String): String {
    val json = loadCachedJson() ?: return defaultValue
    val v = json.optString(key, defaultValue)
    return v.ifEmpty { defaultValue }
  }

  /** Refresh in the background; do NOT block UI. */
  fun refreshAsync() {
    scope.launch(Dispatchers.IO) {
      val now = System.currentTimeMillis()
      val last = prefs.getLong(cacheKeyFetchedAt, 0L)
      if (now - last < ttlMs) return@launch

      val etag = prefs.getString(cacheKeyEtag, null)
      val resp = http.get(url = endpointUrl, ifNoneMatch = etag, timeoutMs = 1500)

      when (resp.code) {
        200 -> {
          // Persist atomically.
          prefs.edit()
            .putString(cacheKeyJson, resp.body)
            .putString(cacheKeyEtag, resp.etag)
            .putLong(cacheKeyFetchedAt, now)
            .apply()
        }
        304 -> {
          // Not modified; extend freshness window.
          prefs.edit().putLong(cacheKeyFetchedAt, now).apply()
        }
        else -> {
          // Network failed or server error; keep last-known-good cache.
        }
      }
    }
  }

  private fun loadCachedJson(): JSONObject? {
    val raw = prefs.getString(cacheKeyJson, null) ?: return null
    return try { JSONObject(raw) } catch (_: Exception) { null }
  }
}

data class HttpResponse(val code: Int, val body: String, val etag: String?)
interface SimpleHttpClient {
  fun get(url: String, ifNoneMatch: String?, timeoutMs: Int): HttpResponse
}

Step 5 — Rollout + targeting that won’t surprise you

Start simple. The most reliable rollout strategies are deterministic and explainable: percent rollout + version guard + (optional) allowlist. Save fancy segmentation for later unless you truly need it.

Step 6 — Observability: know when the flag hurts you

A rollout without observability is gambling. You don’t need a complex dashboard, but you do need a few signals tied to exposure:

Step 7 — Prepare the rollback drill (so it’s actually fast)

“Roll back fast” is a promise you can only keep if you’ve practiced. Make the rollback path boring: a button in your config UI, a Slack/on-call runbook, and a predictable app-side fallback.

Step 8 — iOS implementation pattern (same principles)

iOS should follow the same contract: sync reads from cache, async refresh, typed getters, and exposure hooks. Here’s a compact Swift pattern you can drop into a project and expand.

import Foundation

final class FeatureFlagProvider {
  private let defaults: UserDefaults
  private let endpoint: URL
  private let session: URLSession

  private let cacheKey = "ff_cache_json"
  private let fetchedAtKey = "ff_cache_fetched_at"
  private let ttl: TimeInterval = 15 * 60

  init(defaults: UserDefaults = .standard,
       endpoint: URL,
       session: URLSession = .shared) {
    self.defaults = defaults
    self.endpoint = endpoint
    self.session = session
  }

  // Synchronous read: safe for UI decisions.
  func isEnabled(_ key: String, default defaultValue: Bool = false) -> Bool {
    guard let json = cachedJSON() else { return defaultValue }
    return (json[key] as? Bool) ?? defaultValue
  }

  func string(_ key: String, default defaultValue: String) -> String {
    guard let json = cachedJSON() else { return defaultValue }
    let v = (json[key] as? String) ?? defaultValue
    return v.isEmpty ? defaultValue : v
  }

  // Async refresh: do not block app start.
  func refreshIfStale() {
    let now = Date().timeIntervalSince1970
    let last = defaults.double(forKey: fetchedAtKey)
    if now - last < ttl { return }

    var req = URLRequest(url: endpoint)
    req.timeoutInterval = 1.5

    session.dataTask(with: req) { [weak self] data, response, _ in
      guard let self = self else { return }
      guard let data = data,
            let obj = try? JSONSerialization.jsonObject(with: data) as? [String: Any] else {
        return // keep last-known-good cache
      }
      self.defaults.set(obj, forKey: self.cacheKey)
      self.defaults.set(Date().timeIntervalSince1970, forKey: self.fetchedAtKey)
    }.resume()
  }

  private func cachedJSON() -> [String: Any]? {
    return defaults.dictionary(forKey: cacheKey)
  }
}

Step 9 — Delete flags on purpose (the part everyone skips)

Once a release toggle reaches 100% and is stable, it should stop existing. Otherwise you accumulate dead branches, unreachable code paths, and “why is this off for some users?” mysteries.

Common mistakes

Feature flags are deceptively simple. Most failures are not about “how to fetch a boolean,” but about lifecycle, defaults, and cross-platform consistency. Here are the mistakes that repeatedly cause mobile pain—and how to fix them.

FAQ

Do feature flags on mobile work offline?

Yes—if you design for it. Mobile feature flags should use offline-safe defaults and a cached last-known-good config. When the network is unavailable, the app should continue using cached values (within a TTL) or fall back to safe defaults.

Will feature flags slow down my app startup?

They shouldn’t. The key is to make flag reads synchronous from local storage and refresh asynchronously. If you’re waiting on a network call before rendering, you’ve turned flags into a startup dependency—avoid that unless it’s a deliberate architecture choice.

How do I keep iOS and Android flag behavior consistent?

Use a shared contract. Define flag keys, types, defaults, and targeting rules in one catalog, and implement typed accessors on both platforms. Also add app-version guardrails so you never enable a feature on a build that lacks the code.

Are feature flags secure?

They’re not a security boundary. A client can be modified, and cached configs can persist. Use feature flags to gate UX and behavior, but enforce permissions and sensitive operations server-side.

What’s the difference between app store staged rollout and feature flags?

Staged rollout controls distribution of the binary; flags control behavior inside the binary. In practice you use both: staged rollout reduces exposure to a risky build, and flags let you turn specific features on/off without waiting for another release.

How should I test flagged code paths?

Test both sides of the gate. Add unit tests for feature-gate decisions, include UI tests for “on” and “off” states, and provide a safe debug-only override mechanism for QA. Make sure your CI runs at least one suite with the flag enabled.

When should I keep a flag permanently?

Only for true kill switches or long-lived configuration parameters. Release toggles and experiments should expire and be deleted. Keeping everything permanently is how you accumulate flag debt and unpredictable behavior.

Cheatsheet

A scan-fast checklist for building and running feature flags on mobile without surprises. Use this as a pre-launch and post-launch routine.

Wrap-up

Feature flags on mobile are a superpower when they’re treated as an engineering system, not a quick hack: cached reads, safe defaults, deterministic rollouts, and a clear lifecycle that ends with deletion. Done right, you ship code confidently, ramp features without drama, and roll back in minutes instead of waiting for store review.

Related posts

• CI for Mobile Apps: Fast Builds, Signing, and Release Automation
• Flutter vs React Native vs Native: A Real Decision Guide
• Offline-First Apps: Sync Conflicts Without User Tears
• Push Notifications Done Right: Tokens, Topics, and UX
• Mobile Testing Strategy: Unit, UI, Snapshot, and E2E
• App Store Optimization (ASO) for Developers: What Actually Matters