iOS SDK

1Installation#

Install with Swift Package Manager. In Xcode: File > Add Package Dependencies and enter:

https://github.com/Abrova-co/abrova-ios-flags-sdk.git

Or add it to your Package.swift:

dependencies: [
    .package(url: "https://github.com/Abrova-co/abrova-ios-flags-sdk.git", from: "0.2.0")
]

2Initialization#

Create one client for the app and call start(). Use your public API key (ab_live_...).

import AbrovaFlags

let flags = AbrovaFlags(config: AbrovaFlagsConfig(
    apiKey: "ab_live_xxx",
    environment: "production" // nil 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 launch screen:

let ready = await flags.waitUntilReady(timeout: 3) // 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
}

let dark = flags.getBoolean("dark-mode", default: false)
let theme = flags.getString("theme", default: "light")
let maxItems = flags.getNumber("max-items", default: 10)
let layout = flags.getJson("home-layout", default: ["columns": 2])

A json flag can also be decoded into your own type:

struct HomeLayout: Decodable {
    let columns: Int
}

let layout = flags.getJson("home-layout", as: HomeLayout.self, default: HomeLayout(columns: 2))

Details and reasons

let d = flags.stringDetail("theme", default: "light")
print(d.value, d.enabled, d.variant ?? "-", d.reason, d.version ?? 0)

booleanDetail, stringDetail, numberDetail and jsonDetail check the flag type and return a FlagDetail. getDetail(_:default:) returns the stored value without a type check.

Compare with the constants on FlagReason, for example d.reason == .notReady. 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", attributes: ["plan": "pro", "country": "IR", "beta": true, "age": 31])

// Replace all attributes
flags.setAttributes(["plan": "business"])

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

// 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 Bool, nil / NSNull, or an array 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#

let token = flags.addListener { event in
    switch event {
    case .ready:
        break // First values are available (from the cache or the network). Fires once
    case .updated(let changedKeys):
        print("changed:", changedKeys)
    case .error(let error):
        print(error.kind, error.statusCode ?? 0, error.code ?? "-", error.message)
    }
}

// later
token.cancel()

Events always arrive on the main thread.

6SwiftUI Example#

import SwiftUI
import AbrovaFlags

final class FlagStore: ObservableObject {
    let flags: AbrovaFlags
    @Published private(set) var revision = 0

    init() {
        flags = AbrovaFlags(config: AbrovaFlagsConfig(apiKey: "ab_live_xxx", environment: "production"))
        flags.addListener { [weak self] event in
            switch event {
            case .ready, .updated:
                self?.revision += 1 // redraw views that read flags
            case .error:
                break
            }
        }
        flags.start()
    }
}

@main
struct MyApp: App {
    @StateObject private var store = FlagStore()

    var body: some Scene {
        WindowGroup {
            CheckoutView().environmentObject(store)
        }
    }
}

struct CheckoutView: View {
    @EnvironmentObject var store: FlagStore

    var body: some View {
        if store.flags.isEnabled("new-checkout") {
            Text("New checkout")
        } else {
            Text("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.

// true when the values are current
let ok = await flags.refresh()

// With a completion handler
flags.refresh { ok in /* ... */ }

The last values are stored in UserDefaults (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 package and change these calls:

Rollouts use a new bucketing method, so users are assigned to rollouts and variants again once.

Best Practices#