Android SDK

1Installation#

Install from Abrova Center in two steps.

1. Add the Abrova Center repository in settings.gradle (or the project build.gradle):

repositories {
    google()
    mavenCentral()
    maven { url "https://center.abrova.ir/api/packages/abrova/maven" }
}

Kotlin DSL: maven { url = uri("https://center.abrova.ir/api/packages/abrova/maven") }

2. Add the dependency to your app's build.gradle.kts:

dependencies {
    implementation("ir.abrova:abrova-flags-android:0.2.0")
}

Groovy:

implementation 'ir.abrova:abrova-flags-android:0.2.0'

2Initialization#

Create one client for the app, for example in Application.onCreate, and call start(). Use your public API key (ab_live_...).

import android.app.Application
import ir.abrova.flags.AbrovaFlags
import ir.abrova.flags.AbrovaFlagsConfig

class MyApp : Application() {
    lateinit var flags: AbrovaFlags
        private set

    override fun onCreate() {
        super.onCreate()
        flags = AbrovaFlags(
            applicationContext,
            AbrovaFlagsConfig(
                apiKey = "ab_live_xxx",
                environment = "production", // null uses the Default values
            ),
        )
        flags.start()
    }
}

start() returns immediately. It serves the values cached on the device and fetches fresh ones in the background. There is no shared instance in 0.2.0: keep the client you created.

To wait for the first values, for example on a splash screen:

lifecycleScope.launch {
    val ready = flags.awaitReady(timeoutMs = 3_000) // false when the time ran out
}

3Read flags#

Getters never block and never throw. Each one takes the default to use when the flag is unknown, when no values are available yet, or when the flag has another type.

if (flags.isEnabled("new-checkout")) {
    // Show the new checkout
}

val dark = flags.getBoolean("dark-mode", false)
val theme = flags.getString("theme", "light")
val maxItems = flags.getNumber("max-items", 10.0)
val layout = flags.getJson("home-layout", mapOf("columns" to 2.0))

Details and reasons

val d = flags.getStringDetail("theme", "light")
Log.d("flags", "${d.value} ${d.enabled} ${d.variant} ${d.reason} ${d.version}")

getBooleanDetail, getStringDetail, getNumberDetail and getJsonDetail check the flag type and return a FlagDetail. getDetail(key, defaultValue = null) returns the stored value without a type check.

Compare with the constants on FlagReason, for example d.reason == FlagReason.NOT_READY. isEnabled is true only for ON and VARIANT.

4Identify the user#

Tell the SDK who the user is and what you know about them. Targeting rules and percentage rollouts are evaluated against this context.

// After sign-in
flags.identify("user-123", mapOf("plan" to "pro", "country" to "IR", "beta" to true, "age" to 31))

// Replace all attributes
flags.setAttributes(mapOf("plan" to "business"))

// Signed out, attributes stay
flags.setUserId(null)

// Sign-out: clears the user id, the attributes and the cached values
flags.reset()

• Each change fetches new values after a short pause (250 ms), so several calls in a row send one request. A call that changes nothing sends no request.
• setAttributes and the attributes of identify replace the whole set. They do not merge.
• When the user id changes, the previous user's values are dropped at once. Until the new values arrive, getters return your defaults (reason NOT_READY).
• Attributes are a String (at most 1,024 characters), a Number, a Boolean, null, or a list of those. At most 100 attributes. Anything else is dropped with a log warning.
• The user id and attributes are remembered on the device, so after a restart the client starts with the same user. Call reset() on sign-out.

If you call identify before start(), the first request already carries the user.

Anonymous id

Every install gets a random anonymous id (a UUID). It is stored on the device and sent with every request, so a 10% rollout reaches about 10% of signed-out installs too. When a user id is set, rollouts use the user id instead.

The anonymous id survives reset(). flags.resetAnonymousId() creates a new one. Read it with flags.anonymousId.

5Events#

import ir.abrova.flags.AbrovaFlagsError
import ir.abrova.flags.AbrovaFlagsListener

val listener = object : AbrovaFlagsListener {
    override fun onReady() {
        // First values are available (from the cache or the network). Fires once
    }

    override fun onUpdate(changedKeys: Set<String>) {
        // Values changed after a fetch
    }

    override fun onError(error: AbrovaFlagsError) {
        Log.w("flags", "${error.kind} ${error.statusCode} ${error.code} ${error.message}")
    }
}

flags.addListener(listener)
// later
flags.removeListener(listener)

All three methods are optional. Callbacks run on the main thread.

6Activity Example#

class CheckoutActivity : AppCompatActivity(), AbrovaFlagsListener {
    private val flags get() = (application as MyApp).flags

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        flags.addListener(this)
        render()
    }

    override fun onUpdate(changedKeys: Set<String>) {
        if ("new-checkout" in changedKeys) render()
    }

    override fun onDestroy() {
        flags.removeListener(this)
        super.onDestroy()
    }

    private fun render() {
        if (flags.isEnabled("new-checkout")) {
            setContentView(R.layout.activity_checkout_new)
        } else {
            setContentView(R.layout.activity_checkout)
        }
    }
}

7Refresh, offline and errors#

The SDK fetches values:

• on start(),
• after a change of user or attributes, reset() and resetAnonymousId(),
• when the app returns to the foreground and the values are older than 15 minutes,
• on refresh(),
• on a timer, only if you set refreshIntervalSeconds.

// In a coroutine: true when the values are current
val ok = flags.refresh()

// With a callback on the main thread
flags.refresh { ok -> /* ... */ }

The last values are stored in SharedPreferences (never the API key) and served at the next start, before the network answers. A failed request never clears them.

• Offline or server error: the last values keep being served. The SDK retries with a growing delay (up to 5 minutes).
• Rate limited (429): the SDK waits the time the service asks for, then retries.
• 401, 403 or 404 (wrong key, Flags not enabled for the project, unknown environment): automatic fetches stop until you call refresh().
• Before the first values: flags.isReady is false and getters return your defaults.

flags.close() stops all network work. The cached values stay on the device.

Configuration Options#

Upgrading from 0.1.x#

0.2.0 is a new API, and 0.1.x clients stop receiving flags. Update the dependency and change these calls:

• The values cached by 0.1.x are removed the first time 0.2.0 runs.
• Rollouts use a new bucketing method, so users are assigned to rollouts and variants again once.

Best Practices#