Flagship - Kotlin Multiplatform Feature Flags

Quick Start Examples

Android Application Setup

dependencies {
    implementation("io.maxluxs.flagship:flagship-core:0.1.1")
    implementation("io.maxluxs.flagship:flagship-provider-firebase:0.1.1")
}

import android.app.Application
import io.maxluxs.flagship.core.Flagship
import io.maxluxs.flagship.core.FlagsConfig
import io.maxluxs.flagship.core.manager.DefaultFlagsManager
import io.maxluxs.flagship.core.platform.AndroidFlagsInitializer
import io.maxluxs.flagship.provider.firebase.FirebaseProviderFactory
import kotlinx.coroutines.CoroutineScope
import kotlinx.coroutines.Dispatchers
import kotlinx.coroutines.launch

class MyApp : Application() {
    override fun onCreate() {
        super.onCreate()
        
        val firebaseDefaults = mapOf(
            "new_ui" to false,
            "api_timeout" to 5000,
            "welcome_message" to "Hello"
        )
        
        val config = FlagsConfig(
            appKey = "my-app",
            environment = "production",
            providers = listOf(
                FirebaseProviderFactory.create(
                    application = this,
                    defaults = firebaseDefaults
                )
            ),
            cache = AndroidFlagsInitializer.createPersistentCache(this)
        )
        
        Flagship.configure(config)
        
        val manager = Flagship.manager() as DefaultFlagsManager
        val defaultContext = AndroidFlagsInitializer.createDefaultContext(this)
        manager.setDefaultContext(defaultContext)
        
        CoroutineScope(Dispatchers.Default).launch {
            manager.ensureBootstrap(timeoutMs = 3000)
        }
    }
}

import androidx.lifecycle.lifecycleScope
import kotlinx.coroutines.launch

class MainActivity : AppCompatActivity() {
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        
        lifecycleScope.launch {
            if (Flagship.isEnabled("new_ui")) {
                showNewUI()
            }
            
            val timeout: Int = Flagship.get("api_timeout", default = 5000)
            
            val assignment = Flagship.assign("checkout_exp")
            when (assignment?.variant) {
                "control" -> showLegacyCheckout()
                "variant_a" -> showNewCheckout()
            }
        }
    }
}

iOS SwiftUI Setup

import SwiftUI
import Flagship

@main
struct MyApp: App {
    init() {
        initializeFlagship()
    }
    
    var body: some Scene {
        WindowGroup {
            ContentView()
        }
    }
    
    private func initializeFlagship() {
        let defaults: [String: Any] = [
            "new_ui": false,
            "api_timeout": 5000,
            "welcome_message": "Hello"
        ]
        
        FlagshipSwift.shared.quickConfigure(
            appKey: "my-ios-app",
            environment: "production",
            providers: []
        )
        
        Task {
            await FlagshipSwift.shared.manager().ensureBootstrap(timeoutMs: 3000)
        }
    }
}

struct ContentView: View {
    @State private var showNewUI = false
    
    var body: some View {
        Task {
            let enabled = await FlagshipSwift.shared.manager.isEnabled(
                key: "new_ui",
                default: false
            )
            showNewUI = enabled
        }
        
        if showNewUI {
            NewUIView()
        } else {
            LegacyUIView()
        }
    }
}

Kotlin Multiplatform Setup

kotlin {
    android()
    ios()
    
    sourceSets {
        commonMain.dependencies {
            implementation("io.maxluxs.flagship:flagship-core:0.1.1")
            implementation("io.maxluxs.flagship:flagship-provider-rest:0.1.1")
        }
        
        androidMain.dependencies {
            implementation("io.maxluxs.flagship:flagship-provider-firebase:0.1.1")
        }
    }
}

import io.maxluxs.flagship.core.Flagship
import io.maxluxs.flagship.core.FlagsConfig
import io.maxluxs.flagship.core.cache.PersistentCache
import io.maxluxs.flagship.core.manager.DefaultFlagsManager
import io.maxluxs.flagship.core.platform.AndroidFlagsInitializer
import io.maxluxs.flagship.core.platform.IOSFlagsInitializer
import io.maxluxs.flagship.provider.firebase.FirebaseProviderFactory
import kotlinx.coroutines.CoroutineScope
import kotlinx.coroutines.Dispatchers
import kotlinx.coroutines.launch

expect class PlatformContext

expect fun createPersistentCache(context: PlatformContext): PersistentCache

object FlagshipInitializer {
    fun initialize(platformContext: PlatformContext) {
        val firebaseDefaults = mapOf(
            "new_feature" to false,
            "api_timeout" to 5000
        )
        
        val config = FlagsConfig(
            appKey = "my-kmp-app",
            environment = "production",
            providers = createProviders(platformContext, firebaseDefaults),
            cache = createPersistentCache(platformContext)
        )
        
        Flagship.configure(config)
        
        val manager = Flagship.manager() as DefaultFlagsManager
        setDefaultContext(manager, platformContext)
        
        CoroutineScope(Dispatchers.Default).launch {
            manager.ensureBootstrap(timeoutMs = 3000)
        }
    }
    
    expect fun createProviders(context: PlatformContext, defaults: Map<String, Any>): List<FlagsProvider>
    expect fun setDefaultContext(manager: DefaultFlagsManager, context: PlatformContext)
}

class FeatureRepository {
    suspend fun shouldShowNewFeature(): Boolean {
        return Flagship.isEnabled("new_feature", default = false)
    }
    
    suspend fun getExperimentVariant(): String? {
        val assignment = Flagship.assign("checkout_exp")
        return assignment?.variant
    }
}

Android: androidMain source set
import android.app.Application
import android.content.Context
import io.maxluxs.flagship.core.provider.FlagsProvider

actual class PlatformContext(val androidContext: Context)

actual fun createPersistentCache(context: PlatformContext): PersistentCache {
    return AndroidFlagsInitializer.createPersistentCache(context.androidContext)
}

actual fun FlagshipInitializer.createProviders(
    context: PlatformContext,
    defaults: Map<String, Any>
): List<FlagsProvider> {
    return listOf(
        FirebaseProviderFactory.create(
            application = context.androidContext as Application,
            defaults = defaults
        )
    )
}

actual fun FlagshipInitializer.setDefaultContext(
    manager: DefaultFlagsManager,
    context: PlatformContext
) {
    val defaultContext = AndroidFlagsInitializer.createDefaultContext(context.androidContext)
    manager.setDefaultContext(defaultContext)
}

iOS: iosMain source set
import io.ktor.client.*
import io.ktor.client.engine.darwin.*
import io.ktor.client.plugins.contentnegotiation.*
import io.ktor.serialization.kotlinx.json.*
import io.maxluxs.flagship.provider.rest.RestFlagsProvider
import kotlinx.serialization.json.Json

actual class PlatformContext

actual fun createPersistentCache(context: PlatformContext): PersistentCache {
    return IOSFlagsInitializer.createPersistentCache()
}

actual fun FlagshipInitializer.createProviders(
    context: PlatformContext,
    defaults: Map<String, Any>
): List<FlagsProvider> {
    val httpClient = HttpClient(Darwin) {
        install(ContentNegotiation) {
            json(Json { ignoreUnknownKeys = true })
        }
    }
    return listOf(
        RestFlagsProvider(
            client = httpClient,
            baseUrl = "https://api.example.com/flags"
        )
    )
}

actual fun FlagshipInitializer.setDefaultContext(
    manager: DefaultFlagsManager,
    context: PlatformContext
) {
    val defaultContext = IOSFlagsInitializer.createDefaultContext()
    manager.setDefaultContext(defaultContext)
}

Usage Examples

Simplified API (Suspend Functions)

// Boolean flags
lifecycleScope.launch {
    if (Flagship.isEnabled("new_ui")) {
        showNewUI()
    }
}

// Typed values - type inferred from default
lifecycleScope.launch {
    val timeout: Int = Flagship.get("api_timeout", default = 5000)
    val message: String = Flagship.get("welcome_msg", default = "Hello")
    val threshold: Double = Flagship.get("score_threshold", default = 0.75)
}

// Experiments
lifecycleScope.launch {
    val assignment = Flagship.assign("checkout_exp")
    when (assignment?.variant) {
        "control" -> showLegacyCheckout()
        "variant_a" -> showNewCheckout()
        else -> showLegacyCheckout()
    }
}

// With custom context
lifecycleScope.launch {
    val ctx = EvalContext(
        userId = "user123",
        region = "US",
        attributes = mapOf("tier" to "premium")
    )
    val assignment = Flagship.assign("checkout_exp", context = ctx)
}

Sync API (After Bootstrap)

// 1. Bootstrap first (during app initialization)
class MyApp : Application() {
    override fun onCreate() {
        super.onCreate()
        Flagship.configure(config)
        
        // Bootstrap in background
        lifecycleScope.launch {
            Flagship.manager().ensureBootstrap(timeoutMs = 3000)
        }
    }
}

// 2. Use sync methods after bootstrap (no suspend needed!)
class MainActivity : AppCompatActivity() {
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        
        // Sync methods - instant access, no coroutines needed
        if (Flagship.isEnabledSync("new_ui")) {
            showNewUI()
        }
        
        val timeout: Int = Flagship.getSync("api_timeout", default = 5000)
        val message: String = Flagship.getSync("welcome_msg", default = "Hello")
        
        // Sync experiment assignment
        val assignment = Flagship.assignSync("checkout_exp")
        when (assignment?.variant) {
            "control" -> showLegacyCheckout()
            "variant_a" -> showNewCheckout()
            else -> showLegacyCheckout()
        }
    }
}

// Note: Sync methods throw IllegalStateException if bootstrap not completed
// Always call ensureBootstrap() first or use suspend methods

Full Manager API

// Get manager for advanced operations
val flags = Flagship.manager()

// Suspend methods with context
lifecycleScope.launch {
    val ctx = EvalContext(
        userId = "user123",
        region = "US"
    )
    
    val enabled = flags.isEnabled("new_feature", default = false, ctx = ctx)
    val value: Int = flags.value("timeout", default = 30, ctx = ctx)
    val assignment = flags.assign("exp", ctx = ctx)
}

// Sync methods (after bootstrap)
val enabledSync = flags.isEnabledSync("new_feature")
val valueSync: Int = flags.valueSync("timeout", default = 30)
val assignmentSync = flags.assignSync("exp")

// Refresh flags
flags.refresh(force = true) { providerName, success ->
    println("$providerName: $success")
}

// Overrides (debug/testing)
flags.setOverride("new_feature", FlagValue.Bool(true))
flags.clearOverride("new_feature")

// List all flags
lifecycleScope.launch {
    val allFlags = flags.listAllFlags()
    val overrides = flags.listOverrides()
}

// Bootstrap control
lifecycleScope.launch {
    val success = flags.ensureBootstrap(timeoutMs = 3000)
    if (!success) {
        log("Bootstrap timeout")
    }
}

Batch Evaluation

// Evaluate multiple flags in one call
lifecycleScope.launch {
    val flags = Flagship.evaluateFlags(
        keys = listOf("new_ui", "dark_mode", "premium_features"),
        defaults = mapOf(
            "new_ui" to FlagValue.Bool(false),
            "dark_mode" to FlagValue.Bool(true),
            "premium_features" to FlagValue.Bool(false)
        )
    )
    
    // All flags evaluated in one operation
    val newUiEnabled = flags["new_ui"]?.asBoolean() ?: false
    val darkMode = flags["dark_mode"]?.asBoolean() ?: true
}

// Batch experiment evaluation
lifecycleScope.launch {
    val experiments = Flagship.evaluateExperiments(
        keys = listOf("checkout_exp", "pricing_exp", "ui_exp"),
        ctx = EvalContext(userId = "user123")
    )
    
    // All experiments assigned in one call
    experiments["checkout_exp"]?.variant?.let { variant ->
        showCheckoutVariant(variant)
    }
}

Code Generation

// 1. Define flags in flags.json
{
  "flags": [
    {
      "key": "new_payment_flow",
      "type": "BOOL",
      "defaultValue": "false"
    },
    {
      "key": "api_timeout",
      "type": "INT",
      "defaultValue": "5000"
    }
  ]
}

// 2. Generated code (auto-generated by Gradle plugin)
object Flags {
    object NewPaymentFlow {
        suspend fun enabled(): Boolean {
            return Flagship.isEnabled("new_payment_flow", default = false)
        }
    }
    
    object ApiTimeout {
        suspend fun value(): Int {
            return Flagship.get("api_timeout", default = 5000)
        }
    }
}

// 3. Use generated flags
lifecycleScope.launch {
    if (Flags.NewPaymentFlow.enabled()) {
        showNewPayment()
    }
    
    val timeout: Int = Flags.ApiTimeout.value()
}

Preloading

// Preload flags before user needs them
lifecycleScope.launch {
    // Preload flags for checkout screen
    Flagship.preload(
        keys = listOf(
            "checkout_enabled",
            "payment_methods",
            "shipping_options",
            "discount_codes"
        )
    )
}

// Preload for specific user
fun onUserLogin(userId: String) {
    lifecycleScope.launch {
        Flagship.preloadForUser(
            userId = userId,
            keys = listOf(
                "personalized_ui",
                "recommendations",
                "pricing_tier"
            )
        )
    }
}

// Preload on app startup
class MyApp : Application() {
    override fun onCreate() {
        super.onCreate()
        Flagship.configure(config)
        
        // Preload critical flags on startup
        lifecycleScope.launch {
            Flagship.preload(listOf("app_config", "feature_gates"))
        }
    }
}

Feature Flags & A/B Testing
for Kotlin Multiplatformv0.1.1

Quick Start Examples

Usage Examples

Documentation

Feature Flags & A/B Testingfor Kotlin Multiplatformv0.1.1

Quick Start Examples

Usage Examples

Documentation

Feature Flags & A/B Testing
for Kotlin Multiplatformv0.1.1