capacitor-launchdarkly 0.0.0-stage → 0.1.0

package/android/build.gradle

@@ -0,0 +1,68 @@
+ext {
+    junitVersion = project.hasProperty('junitVersion') ? rootProject.ext.junitVersion : '4.13.2'
+    androidxAppCompatVersion = project.hasProperty('androidxAppCompatVersion') ? rootProject.ext.androidxAppCompatVersion : '1.7.1'
+    androidxJunitVersion = project.hasProperty('androidxJunitVersion') ? rootProject.ext.androidxJunitVersion : '1.3.0'
+    androidxEspressoCoreVersion = project.hasProperty('androidxEspressoCoreVersion') ? rootProject.ext.androidxEspressoCoreVersion : '3.7.0'
+    // The LaunchDarkly Android client SDK, pinned. An app can move it with `launchDarklyAndroidVersion` in its variables.gradle.
+    launchDarklyAndroidVersion = project.hasProperty('launchDarklyAndroidVersion') ? rootProject.ext.launchDarklyAndroidVersion : '5.18.0'
+}
+
+buildscript {
+    ext.kotlin_version = project.hasProperty("kotlin_version") ? rootProject.ext.kotlin_version : '2.4.21'
+    repositories {
+        google()
+        mavenCentral()
+    }
+    dependencies {
+        // The version Capacitor 8's own Android library builds with: an app loads one Android Gradle plugin for every module.
+        classpath 'com.android.tools.build:gradle:8.13.2'
+        classpath "org.jetbrains.kotlin:kotlin-gradle-plugin:$kotlin_version"
+    }
+}
+
+apply plugin: 'com.android.library'
+apply plugin: 'kotlin-android'
+
+android {
+    namespace = "io.github.maximbelov.launchdarkly"
+    compileSdk = project.hasProperty('compileSdkVersion') ? rootProject.ext.compileSdkVersion : 36
+    defaultConfig {
+        minSdkVersion project.hasProperty('minSdkVersion') ? rootProject.ext.minSdkVersion : 24
+        targetSdkVersion project.hasProperty('targetSdkVersion') ? rootProject.ext.targetSdkVersion : 36
+        versionCode 1
+        versionName "1.0"
+    }
+    buildTypes {
+        release {
+            minifyEnabled false
+            proguardFiles getDefaultProguardFile('proguard-android-optimize.txt'), 'proguard-rules.pro'
+        }
+    }
+    lintOptions {
+        abortOnError = false
+    }
+    compileOptions {
+        sourceCompatibility JavaVersion.VERSION_21
+        targetCompatibility JavaVersion.VERSION_21
+    }
+}
+
+kotlin {
+    jvmToolchain(21)
+}
+
+repositories {
+    google()
+    mavenCentral()
+}
+
+
+dependencies {
+    implementation fileTree(dir: 'libs', include: ['*.jar'])
+    implementation project(':capacitor-android')
+    implementation "androidx.appcompat:appcompat:$androidxAppCompatVersion"
+    implementation "com.launchdarkly:launchdarkly-android-client-sdk:$launchDarklyAndroidVersion"
+    testImplementation "junit:junit:$junitVersion"
+    // JSObject is an org.json.JSONObject, which android.jar only stubs on the JVM; the real one lets the tests read it back.
+    testImplementation "org.json:json:20260814"
+}

package/android/src/main/AndroidManifest.xml

@@ -0,0 +1,2 @@
+<manifest xmlns:android="http://schemas.android.com/apk/res/android">
+</manifest>

package/android/src/main/kotlin/io/github/maximbelov/launchdarkly/Json.kt

@@ -0,0 +1,67 @@
+package io.github.maximbelov.launchdarkly
+
+import com.getcapacitor.JSObject
+import com.launchdarkly.sdk.LDContext
+import com.launchdarkly.sdk.LDValue
+import com.launchdarkly.sdk.json.JsonSerialization
+import org.json.JSONArray
+import org.json.JSONObject
+import org.json.JSONTokener
+
+/**
+ * Contexts in the JSON shape LaunchDarkly's SDKs use, read by the SDK's own parser, so custom attributes of any JSON type,
+ * nested objects, `anonymous`, `name`, multi-contexts and `_meta.privateAttributes` mean what they mean to LaunchDarkly. The key
+ * is taken as given: nothing here generates or replaces one.
+ */
+object Contexts {
+    /** The context [json] describes. Throws [IllegalArgumentException] for one the SDK does not accept. */
+    fun parse(json: String): LDContext {
+        val context = try {
+            JsonSerialization.deserialize(json, LDContext::class.java)
+        } catch (e: Exception) {
+            throw IllegalArgumentException("Invalid context: ${e.message}", e)
+        }
+        require(context != null && context.isValid) { "Invalid context: ${context?.error ?: "empty"}" }
+        return context
+    }
+
+    /** [parse], or null for a context that is absent or not valid. */
+    fun parseOrNull(json: String?): LDContext? = json?.let {
+        try {
+            parse(it)
+        } catch (e: IllegalArgumentException) {
+            null
+        }
+    }
+}
+
+/** Flag values between JavaScript (org.json values, as Capacitor hands them over) and the SDK's [LDValue], through JSON text. */
+object JsValues {
+    /** An org.json value (JSONObject, JSONArray, String, Number, Boolean, JSONObject.NULL or null) as an [LDValue]. */
+    fun toLDValue(value: Any?): LDValue {
+        if (value == null || value == JSONObject.NULL) return LDValue.ofNull()
+        return LDValue.parse(jsonText(value))
+    }
+
+    /**
+     * The JSON text of one org.json value. Android's org.json has no `valueToString`, so the value is written as the only item
+     * of an array and the brackets are dropped.
+     */
+    fun jsonText(value: Any?): String {
+        val array = JSONArray().put(value ?: JSONObject.NULL).toString()
+        return array.substring(1, array.length - 1)
+    }
+
+    /** An [LDValue] as the org.json value Capacitor sends to JavaScript; JSON null is [JSONObject.NULL]. */
+    fun toJs(value: LDValue?): Any {
+        if (value == null || value.isNull) return JSONObject.NULL
+        return JSONTokener(value.toJsonString()).nextValue()
+    }
+
+    /** Every flag as one JavaScript object. */
+    fun flags(values: Map<String, LDValue>): JSObject {
+        val flags = JSObject()
+        for ((key, value) in values) flags.put(key, toJs(value))
+        return flags
+    }
+}

package/android/src/main/kotlin/io/github/maximbelov/launchdarkly/LaunchDarklyClient.kt

@@ -0,0 +1,250 @@
+package io.github.maximbelov.launchdarkly
+
+import android.app.Application
+import com.launchdarkly.sdk.LDValue
+import com.launchdarkly.sdk.android.ConnectionInformation
+import com.launchdarkly.sdk.android.LDAllFlagsListener
+import com.launchdarkly.sdk.android.LDClient
+import com.launchdarkly.sdk.android.LDFailure
+import com.launchdarkly.sdk.android.LDStatusListener
+import java.util.concurrent.CountDownLatch
+import java.util.concurrent.ExecutionException
+import java.util.concurrent.ExecutorService
+import java.util.concurrent.Executors
+import java.util.concurrent.TimeUnit
+import java.util.concurrent.TimeoutException
+
+/** Where the client's events go: the plugin instance of the current bridge. */
+interface ClientEvents {
+    fun flagChanged(key: String, value: LDValue?, previous: LDValue?)
+    fun connectionModeChanged(mode: String)
+}
+
+/**
+ * The one LaunchDarkly client of the process. It outlives a plugin instance, since an activity that is recreated creates a new
+ * bridge and a new plugin, while the SDK keeps one client per process.
+ *
+ * Starting, restarting, identifying and closing run one after another on [lifecycle], in the order they were asked for. What
+ * only waits (for the start to finish, for the first flags) runs on [waiters], so a wait never holds up Capacitor's plugin
+ * thread or the lifecycle.
+ */
+object LaunchDarklyClient {
+    private val lifecycle: ExecutorService = Executors.newSingleThreadExecutor { Thread(it, "LaunchDarklyLifecycle") }
+    private val waiters: ExecutorService = Executors.newCachedThreadPool { Thread(it, "LaunchDarklyWait").apply { isDaemon = true } }
+
+    @Volatile var events: ClientEvents? = null
+
+    private val lock = Any()
+    private var client: LDClient? = null
+    private var options: StartOptions? = null
+    private var contextJson: String? = null
+    private var started: CountDownLatch? = null
+    private val lastValues = HashMap<String, LDValue>()
+
+    private val flagsListener = LDAllFlagsListener { keys -> onFlagsChanged(keys) }
+    private val statusListener = object : LDStatusListener {
+        override fun onConnectionModeChanged(connectionInformation: ConnectionInformation) {
+            events?.connectionModeChanged(connectionInformation.connectionMode.name)
+        }
+
+        override fun onInternalFailure(ldFailure: LDFailure?) = Unit
+    }
+
+    /** The mobile key of the running client, or of the one being started. */
+    val mobileKey: String? get() = synchronized(lock) { options?.mobileKey }
+
+    /**
+     * Starts the client unless one with the same mobile key is running or starting; one with another key is closed first.
+     * [done] runs on a waiter thread once the start has finished: the first flags are in or the wait is over.
+     */
+    fun start(application: Application, options: StartOptions, context: ContextChoice, done: () -> Unit = {}) {
+        val latch = synchronized(lock) {
+            if (this.options?.mobileKey == options.mobileKey && started != null) {
+                started!!
+            } else {
+                val latch = CountDownLatch(1)
+                val previous = this.options
+                this.options = options
+                this.contextJson = context.json
+                this.started = latch
+                lifecycle.execute { startNow(application, options, context, latch, closeFirst = previous != null) }
+                latch
+            }
+        }
+        waiters.execute {
+            awaitStart(latch, options)
+            done()
+        }
+    }
+
+    private fun startNow(application: Application, options: StartOptions, context: ContextChoice, latch: CountDownLatch, closeFirst: Boolean) {
+        try {
+            if (closeFirst) closeNow()
+            // Blocks this lifecycle thread, not the caller, for at most startWaitSeconds; the client is usable either way.
+            val newClient = LDClient.init(application, LdConfigFactory.build(options), context.context, options.startWaitWholeSeconds)
+            newClient.registerAllFlagsListener(flagsListener)
+            newClient.registerStatusListener(statusListener)
+            synchronized(lock) {
+                client = newClient
+                lastValues.clear()
+                lastValues.putAll(newClient.allFlags())
+            }
+        } finally {
+            latch.countDown()
+        }
+    }
+
+    /** Restarts the running client with [change] applied to its options, keeping the current context. */
+    fun restart(application: Application, change: (StartOptions) -> StartOptions, done: (Exception?) -> Unit) {
+        val (current, json) = synchronized(lock) { options to contextJson }
+        if (current == null || json == null) {
+            done(IllegalStateException("The client is not started."))
+            return
+        }
+        val context = try {
+            ContextChoice(Contexts.parse(json), json)
+        } catch (e: IllegalArgumentException) {
+            done(e)
+            return
+        }
+        val next = change(current)
+        val latch = CountDownLatch(1)
+        synchronized(lock) {
+            options = next
+            started = latch
+        }
+        lifecycle.execute { startNow(application, next, context, latch, closeFirst = true) }
+        waiters.execute {
+            awaitStart(latch, next)
+            done(null)
+        }
+    }
+
+    /** Switches the context; [done] gets whether the wait for its flags timed out, or the error. */
+    fun identify(context: ContextChoice, timeoutSeconds: Double, store: ContextStore, done: (Boolean?, Exception?) -> Unit) {
+        lifecycle.execute {
+            val current = synchronized(lock) { client }
+            if (current == null) {
+                done(null, IllegalStateException("The client is not started."))
+                return@execute
+            }
+            try {
+                current.identify(context.context).get((timeoutSeconds * 1000).toLong(), TimeUnit.MILLISECONDS)
+                remember(context, store)
+                done(false, null)
+            } catch (e: TimeoutException) {
+                // The SDK has switched to the context and keeps loading its flags; only the wait is over.
+                remember(context, store)
+                done(true, null)
+            } catch (e: ExecutionException) {
+                done(null, (e.cause as? Exception) ?: e)
+            } catch (e: InterruptedException) {
+                Thread.currentThread().interrupt()
+                done(null, e)
+            }
+        }
+    }
+
+    private fun remember(context: ContextChoice, store: ContextStore) {
+        synchronized(lock) { contextJson = context.json }
+        store.write(context.json)
+    }
+
+    /** Waits on a waiter thread until the start has finished, then answers. */
+    fun afterStart(answer: () -> Unit) {
+        val (latch, current) = synchronized(lock) { started to options }
+        waiters.execute {
+            if (latch != null && current != null) awaitStart(latch, current)
+            answer()
+        }
+    }
+
+    /** Answers on a waiter thread whether the client has its first flags, waiting up to [timeoutSeconds] for them. */
+    fun waitForInitialization(timeoutSeconds: Double, answer: (Boolean) -> Unit) {
+        val latch = synchronized(lock) { started }
+        if (latch == null) {
+            answer(false)
+            return
+        }
+        waiters.execute {
+            val deadline = System.nanoTime() + (timeoutSeconds * 1_000_000_000).toLong()
+            latch.await(remainingNanos(deadline), TimeUnit.NANOSECONDS)
+            while (true) {
+                if (synchronized(lock) { client }?.isInitialized == true) return@execute answer(true)
+                if (remainingNanos(deadline) <= 0) return@execute answer(false)
+                Thread.sleep(POLL_MILLIS)
+            }
+        }
+    }
+
+    val isInitialized: Boolean get() = synchronized(lock) { client }?.isInitialized == true
+
+    val context: String? get() = synchronized(lock) { contextJson }
+
+    /** Every flag from the SDK's store; reading them this way records no evaluation event. */
+    fun allFlags(): Map<String, LDValue> = synchronized(lock) { client }?.allFlags() ?: emptyMap()
+
+    fun variation(key: String, defaultValue: LDValue): LDValue =
+        synchronized(lock) { client }?.jsonValueVariation(key, defaultValue) ?: defaultValue
+
+    fun setOnline(online: Boolean) {
+        val current = synchronized(lock) { client } ?: return
+        if (online) current.setOnline() else current.setOffline()
+    }
+
+    fun flush() {
+        synchronized(lock) { client }?.flush()
+    }
+
+    fun close(done: () -> Unit) {
+        synchronized(lock) {
+            options = null
+            started = null
+            contextJson = null
+        }
+        lifecycle.execute {
+            closeNow()
+            done()
+        }
+    }
+
+    private fun closeNow() {
+        val current = synchronized(lock) {
+            val c = client
+            client = null
+            lastValues.clear()
+            c
+        } ?: return
+        current.unregisterAllFlagsListener(flagsListener)
+        current.unregisterStatusListener(statusListener)
+        try {
+            current.close()
+        } catch (e: Exception) {
+            // close() declares IOException and never throws it; nothing to do either way.
+        }
+    }
+
+    private fun onFlagsChanged(keys: List<String>) {
+        val current = synchronized(lock) { client } ?: return
+        val values = current.allFlags()
+        for (key in keys) {
+            val value = values[key]
+            val previous = synchronized(lock) {
+                val before = lastValues[key]
+                if (value == null) lastValues.remove(key) else lastValues[key] = value
+                before
+            }
+            events?.flagChanged(key, value, previous)
+        }
+    }
+
+    private fun awaitStart(latch: CountDownLatch, options: StartOptions) {
+        // The SDK's own wait ends the start; the margin only guards against a start that never returns.
+        latch.await((options.startWaitWholeSeconds + START_MARGIN_SECONDS).toLong(), TimeUnit.SECONDS)
+    }
+
+    private fun remainingNanos(deadline: Long) = deadline - System.nanoTime()
+
+    private const val POLL_MILLIS = 50L
+    private const val START_MARGIN_SECONDS = 10
+}

package/android/src/main/kotlin/io/github/maximbelov/launchdarkly/LaunchDarklyPlugin.kt

@@ -0,0 +1,148 @@
+package io.github.maximbelov.launchdarkly
+
+import android.app.Application
+import android.content.Context
+import com.getcapacitor.JSObject
+import com.getcapacitor.Plugin
+import com.getcapacitor.PluginCall
+import com.getcapacitor.PluginMethod
+import com.getcapacitor.annotation.CapacitorPlugin
+import com.launchdarkly.sdk.LDValue
+import org.json.JSONObject
+
+@CapacitorPlugin(name = "LaunchDarkly")
+class LaunchDarklyPlugin : Plugin(), ClientEvents {
+
+    private val store by lazy {
+        SharedPreferencesContextStore(
+            context.getSharedPreferences(SharedPreferencesContextStore.PREFERENCES, Context.MODE_PRIVATE),
+        )
+    }
+
+    private val application: Application get() = context.applicationContext as Application
+
+    /**
+     * Runs as the bridge is created, before the web view loads the app. With a `mobileKey` in `plugins.LaunchDarkly` of
+     * capacitor.config the client starts here, with the stored context or else `initialContext`, so the flags are on their way
+     * before any app code asks for them. Without one nothing starts, and `initialize()` does it.
+     */
+    override fun load() {
+        LaunchDarklyClient.events = this
+        val autoStart = PluginConfig.autoStart(config.configJSON) ?: return
+        val context = StartContext.choose(store.read(), autoStart.initialContext)
+        LaunchDarklyClient.start(application, autoStart.options, context)
+    }
+
+    @PluginMethod
+    fun initialize(call: PluginCall) {
+        val mobileKey = call.getString("mobileKey")?.takeIf { it.isNotBlank() }
+            ?: return call.reject("initialize needs a mobileKey on Android.")
+        if (LaunchDarklyClient.mobileKey == mobileKey) {
+            // One client per process: the same key changes nothing and answers the state once the start is done.
+            return LaunchDarklyClient.afterStart { call.resolve(state()) }
+        }
+        val given = readContext(call) ?: return
+        val options = StartOptions.parse(mobileKey, call.getObject("options"))
+        // The given context plays the part of initialContext: a context an earlier identify() stored wins over it.
+        val context = StartContext.choose(store.read(), given.json)
+        LaunchDarklyClient.start(application, options, context) { call.resolve(state()) }
+    }
+
+    @PluginMethod
+    fun waitForInitialization(call: PluginCall) {
+        val timeout = StartOptions.seconds(call.getDouble("timeoutSeconds") ?: StartOptions.DEFAULT_WAIT_SECONDS)
+        LaunchDarklyClient.waitForInitialization(timeout) { initialized ->
+            call.resolve(JSObject().put("initialized", initialized))
+        }
+    }
+
+    @PluginMethod
+    fun getState(call: PluginCall) {
+        LaunchDarklyClient.afterStart { call.resolve(state()) }
+    }
+
+    @PluginMethod
+    fun identify(call: PluginCall) {
+        val context = readContext(call) ?: return
+        val timeout = StartOptions.seconds(call.getDouble("timeoutSeconds") ?: StartOptions.DEFAULT_WAIT_SECONDS)
+        LaunchDarklyClient.identify(context, timeout, store) { timedOut, error ->
+            if (error != null) call.reject(error.message ?: "identify failed", error) else call.resolve(JSObject().put("timedOut", timedOut == true))
+        }
+    }
+
+    @PluginMethod
+    fun variation(call: PluginCall) {
+        val key = call.getString("key") ?: return call.reject("variation needs a key.")
+        val defaultValue = JsValues.toLDValue(call.data.opt("defaultValue"))
+        val value = LaunchDarklyClient.variation(key, defaultValue)
+        call.resolve(JSObject().put("value", JsValues.toJs(value)))
+    }
+
+    @PluginMethod
+    fun allFlags(call: PluginCall) {
+        call.resolve(JSObject().put("flags", JsValues.flags(LaunchDarklyClient.allFlags())))
+    }
+
+    @PluginMethod
+    fun setStreaming(call: PluginCall) {
+        val enabled = call.getBoolean("enabled") ?: return call.reject("setStreaming needs enabled.")
+        LaunchDarklyClient.restart(application, { it.copy(streaming = enabled) }) { error ->
+            if (error != null) call.reject(error.message, error) else call.resolve()
+        }
+    }
+
+    @PluginMethod
+    fun setOnline(call: PluginCall) {
+        val online = call.getBoolean("online") ?: return call.reject("setOnline needs online.")
+        LaunchDarklyClient.setOnline(online)
+        call.resolve()
+    }
+
+    @PluginMethod
+    fun flush(call: PluginCall) {
+        LaunchDarklyClient.flush()
+        call.resolve()
+    }
+
+    @PluginMethod
+    fun close(call: PluginCall) {
+        LaunchDarklyClient.close { call.resolve() }
+    }
+
+    @PluginMethod
+    fun clearStoredContext(call: PluginCall) {
+        store.clear()
+        call.resolve()
+    }
+
+    override fun flagChanged(key: String, value: LDValue?, previous: LDValue?) {
+        val change = JSObject().put("key", key).put("value", JsValues.toJs(value))
+        if (previous != null) change.put("previous", JsValues.toJs(previous))
+        notifyListeners("flagChange", change)
+    }
+
+    override fun connectionModeChanged(mode: String) {
+        notifyListeners("connectionModeChange", JSObject().put("mode", mode))
+    }
+
+    private fun readContext(call: PluginCall): ContextChoice? {
+        val json = call.getObject("context")?.toString() ?: run {
+            call.reject("A context is needed.")
+            return null
+        }
+        return try {
+            ContextChoice(Contexts.parse(json), json)
+        } catch (e: IllegalArgumentException) {
+            call.reject(e.message, e)
+            null
+        }
+    }
+
+    private fun state(): JSObject {
+        val state = JSObject()
+            .put("initialized", LaunchDarklyClient.isInitialized)
+            .put("flags", JsValues.flags(LaunchDarklyClient.allFlags()))
+        LaunchDarklyClient.context?.let { state.put("context", JSONObject(it)) }
+        return state
+    }
+}

package/android/src/main/kotlin/io/github/maximbelov/launchdarkly/LdConfigFactory.kt

@@ -0,0 +1,34 @@
+package io.github.maximbelov.launchdarkly
+
+import com.launchdarkly.sdk.android.Components
+import com.launchdarkly.sdk.android.LDConfig
+
+/**
+ * Builds the SDK configuration. Two settings here are not options, because LaunchDarkly bills client-side SDKs by the number
+ * of unique context keys (of the kind that has the most):
+ *
+ * - Automatic environment attributes are disabled. Enabled, the SDK adds `ld_application` and `ld_device` contexts to every
+ *   evaluation, and the `ld_device` key is generated per install, which counts every device as a context of its own.
+ * - Anonymous keys are not generated. Enabled, the SDK replaces the key of every anonymous context with a key generated per
+ *   install (`AnonymousKeyContextModifier`), so an app that shares one anonymous key across all its installs would again count
+ *   one context per device. The SDK's default is already false; it is set anyway, so a change of default cannot move it.
+ */
+object LdConfigFactory {
+    fun build(options: StartOptions): LDConfig {
+        val builder = LDConfig.Builder(LDConfig.Builder.AutoEnvAttributes.Disabled)
+            .mobileKey(options.mobileKey)
+            .generateAnonymousKeys(false)
+            .evaluationReasons(options.evaluationReasons)
+            .offline(options.offline)
+            .dataSource(if (options.streaming) Components.streamingDataSource() else Components.pollingDataSource())
+        options.application?.let { app ->
+            val info = Components.applicationInfo()
+            app.id?.let { info.applicationId(it) }
+            app.name?.let { info.applicationName(it) }
+            app.version?.let { info.applicationVersion(it) }
+            app.versionName?.let { info.applicationVersionName(it) }
+            builder.applicationInfo(info)
+        }
+        return builder.build()
+    }
+}

package/android/src/main/kotlin/io/github/maximbelov/launchdarkly/StartOptions.kt

@@ -0,0 +1,76 @@
+package io.github.maximbelov.launchdarkly
+
+import org.json.JSONObject
+import kotlin.math.ceil
+
+/** Application metadata sent with every request. It describes the app; it is not a context. */
+data class ApplicationMetadata(
+    val id: String? = null,
+    val name: String? = null,
+    val version: String? = null,
+    val versionName: String? = null,
+)
+
+/** How the client is started: from `plugins.LaunchDarkly` in capacitor.config, or from `initialize()`. */
+data class StartOptions(
+    val mobileKey: String,
+    val streaming: Boolean = true,
+    val evaluationReasons: Boolean = false,
+    val offline: Boolean = false,
+    val startWaitSeconds: Double = DEFAULT_WAIT_SECONDS,
+    val application: ApplicationMetadata? = null,
+) {
+    /** [startWaitSeconds] in whole seconds for the SDK's `init`, rounded up so that a fraction still waits. */
+    val startWaitWholeSeconds: Int get() = ceil(startWaitSeconds).toInt()
+
+    companion object {
+        const val DEFAULT_WAIT_SECONDS = 5.0
+
+        /** The options of `initialize()` or of the config block, everything but the key and the context. */
+        fun parse(mobileKey: String, json: JSONObject?): StartOptions {
+            val options = json ?: JSONObject()
+            return StartOptions(
+                mobileKey = mobileKey,
+                streaming = options.optBoolean("streaming", true),
+                evaluationReasons = options.optBoolean("evaluationReasons", false),
+                offline = options.optBoolean("offline", false),
+                startWaitSeconds = seconds(options.optDouble("startWaitSeconds", DEFAULT_WAIT_SECONDS)),
+                application = options.optJSONObject("application")?.let(::parseApplication),
+            )
+        }
+
+        /** A wait in seconds as given, or the default when it is not a usable number. */
+        fun seconds(value: Double, default: Double = DEFAULT_WAIT_SECONDS): Double =
+            if (value.isNaN() || value.isInfinite() || value < 0) default else value
+
+        private fun parseApplication(json: JSONObject) = ApplicationMetadata(
+            id = json.optStringOrNull("id"),
+            name = json.optStringOrNull("name"),
+            version = json.optStringOrNull("version"),
+            versionName = json.optStringOrNull("versionName"),
+        )
+    }
+}
+
+/** What the native start-up does when the app launches: start with [options] and [initialContext] unless a context was stored. */
+data class AutoStart(val options: StartOptions, val initialContext: String)
+
+object PluginConfig {
+    /** The context of a native start-up that has neither a stored context nor an `initialContext`. */
+    const val DEFAULT_INITIAL_CONTEXT = """{"kind":"user","key":"anonymous_user","anonymous":true}"""
+
+    /**
+     * Reads the `plugins.LaunchDarkly` block of capacitor.config. Without a `mobileKey` there is no native start-up, and the
+     * answer is null: the app starts the client with `initialize()` instead.
+     */
+    fun autoStart(config: JSONObject?): AutoStart? {
+        if (config == null) return null
+        val mobileKey = config.optStringOrNull("mobileKey") ?: return null
+        val initialContext = config.optJSONObject("initialContext")?.toString() ?: DEFAULT_INITIAL_CONTEXT
+        return AutoStart(StartOptions.parse(mobileKey, config), initialContext)
+    }
+}
+
+/** A string value, or null when it is absent, not a string, or blank. */
+internal fun JSONObject.optStringOrNull(name: String): String? =
+    (opt(name) as? String)?.takeIf { it.isNotBlank() }