Swift
The native Apple-platform SDK (iOS 15+, macOS 12+) — module Quonfig,
Swift-only, Swift Concurrency throughout, zero external dependencies.
Like the JavaScript and React clients it is a frontend SDK: it fetches
the server-evaluated config for a context, caches it, polls for updates with
ETag/304, and reads typed values synchronously. Evaluation happens
server-side in Quonfig — there is no on-device targeting engine.
Install
Distributed via Swift Package Manager. In Xcode: File → Add Package
Dependencies… and enter https://github.com/quonfig/sdk-swift.git (Xcode
offers the latest release), or add it to your Package.swift, replacing
VERSION with the latest release
(without the leading v):
dependencies: [
.package(url: "https://github.com/quonfig/sdk-swift.git", from: "VERSION"),
],
targets: [
.target(
name: "YourApp",
dependencies: [
.product(name: "Quonfig", package: "sdk-swift"),
]
),
]
Then import Quonfig.
Initialize the client
Initialize with your frontend SDK key (the same key type the JavaScript / React SDKs use — never embed a backend key in a mobile binary, it's extractable):
import Quonfig
let quonfig = try await Quonfig.initialize(
context: QuonfigContext([
"user": ["key": .string("u_123"), "email": .string("a@example.com")],
"device": ["mobile": .bool(true)],
]),
options: .init(
sdkKey: "YOUR_FRONTEND_SDK_KEY",
domain: "quonfig.com" // one knob for api + telemetry hosts
)
)
initialize is async throws and resolves once the first envelope is
available: from the network, or, after a bounded initTimeout (default 5s),
from the cold-start cache. With no network and no cache it follows
onInitFailure (see below). A hung
network never hangs your UI past initTimeout.
If Quonfig is unreachable at startup
initialize retries with jittered backoff (0.5s, 1s, 2s, ... capped at 30s)
for up to initTimeout. A cached copy from an earlier launch counts as
config in every mode: if the network doesn't answer in time, the client
starts on the cache (marked stale) and logs a WARN. Only when there is no cache
does onInitFailure decide:
onInitFailure | No network and no cache at initTimeout |
|---|---|
.fail (default) | initialize throws QuonfigInitError.timeout (the last attempt hung) or .unavailable (the last attempt failed fast on at least one API URL). No client is returned. |
.wait | initialize keeps retrying with no upper bound. |
.`continue` (alias .continueWithDefaults) | initialize returns a client on code defaults: isReady == false, source == .defaults. The poller keeps retrying and the client heals. With a cache, .continue returns at once on the cache. |
If every configured API URL rejects the SDK key (401/403/404/410), .fail
throws QuonfigInitError.unauthorized at once and .continue returns at once;
.wait keeps retrying. A rejection from the primary alone is an ordinary
failed attempt. initTimeout of zero or less runs exactly one attempt, then
applies onInitFailure.
let quonfig = try await Quonfig.initialize(
context: ctx, options: config, onInitFailure: .continue, initTimeout: 5)
if quonfig.source == .defaults { logger.warning("Quonfig: running on code defaults") }
await quonfig.waitForReady() // returns once an envelope (network or cache) is applied
source is .network, .cache or .defaults. For many apps .continue is
the better choice; see
Browsers and mobile apps.
While the store is warming (before the first envelope), isEnabled returns
false, the typed getters return your supplied default, and shouldLog logs
everything.
Read flags & configs
Reads are synchronous and never block — they serve from an in-memory
snapshot. They never throw. A typed getter returns your default for an absent
key, a not-yet-ready store, a value of another type or a malformed value; the
last two log one WARN per key through logSink.
let on = quonfig.isEnabled("new-checkout") // Bool
let color = quonfig.string("button-color", default: "blue") // String
let limit = quonfig.int("rate-limit", default: 100) // Int
let ratio = quonfig.double("sample-ratio", default: 0.1) // Double
let regions = quonfig.stringList("regions", default: ["us"]) // [String]
let timeout = quonfig.duration("http-timeout", default: 30) // TimeInterval (seconds)
let pricing = quonfig.json("pricing") // [String: Any]?
// Full resolution details (value + reason + variant), for experiments/telemetry.
let details = quonfig.details("checkout-experiment")
// Typed details: the value read under the typed getters' rules, plus errorCode.
let typed = quonfig.details("rate-limit", as: .int)
if typed.errorCode == .typeMismatch {
// the stored value is not an int, or is malformed
}
The getters follow the typed-getter contract shared by every Quonfig SDK:
- No string coercion.
stringreads only string and log_level configs, so a duration config returns your default; read it withduration. A stored"true"is not a bool. - Numbers convert only when exact.
doublereads an int config.intreads a double only when it is whole and within ±(2^53-1); it never truncates. jsonreturnsnilfor a missing key or any config that is not a json object.isEnabledistrueonly for a stored booltrue. A missing key or a non-bool value returnsfalseand logs one WARN per key.
details(_:as:) takes a QuonfigValueType (.bool, .int, .double,
.string, .stringList, .duration, .json). EvaluationDetails.errorCode
is nil on success and otherwise .typeMismatch (another type, or a malformed
value), .flagNotFound or .providerNotReady (no config loaded yet). The rules
are the same in every Quonfig SDK; see
Typed Getters, Defaults, and Error Codes.
string on a duration config used to return its ISO 8601 text ("PT30S"); it
now returns your default. int no longer reads whole doubles beyond
±(2^53-1), json returns nil for non-json configs, details(_:) on a
malformed value now reports .error / .typeMismatch, and failed reads log one
WARN per key.
Configs (non-flag values) are read the same way. By default configs are not sent to frontend SDKs — enable "Send to frontend SDKs" on each config you want a frontend SDK to read. Feature flags are always sent.
Context & updateContext
The context is a plain multi-namespace object. To switch identity (e.g. after a
sign-in), call updateContext — it immediately refetches the evaluated envelope
for the new context and keeps polling with it:
try await quonfig.updateContext(
QuonfigContext(["user": ["key": .string("u_456"), "email": .string("b@example.com")]])
)
React to live updates
The SDK polls (default 60s foreground) with ETag/If-None-Match, so an
unchanged flag set is a cheap 304. It refetches immediately on app foreground
and on updateContext, and suspends polling in the background.
Subscribe to be notified after every change (diff-before-notify, so unchanged polls don't churn) — SwiftUI-friendly:
let token = await quonfig.subscribe {
// re-read flags here and update your UI
}
// Hold the token; dropping it unsubscribes.
Invalid or revoked SDK key
If a poll is rejected because Quonfig no longer accepts the SDK key, sdk-swift
logs one ERROR (config fetch rejected: the SDK key is invalid or revoked, with the HTTP status and host, never the key), then waits
max(T, pollInterval) between polls, with T picked at random between 150 and
300 seconds. Going to the background and back keeps the slow cadence. The first
accepted poll logs one INFO and polling returns to pollInterval. The initial
fetch, the foreground catch-up and updateContext are not affected. The full
rule is on the Reliability page.
Dynamic log levels
Drive a logger's minimum level from a Quonfig log_level config, so you can
raise or lower verbosity from the dashboard without a redeploy. QuonfigLogger
is built on Apple's unified logging (os.Logger):
let log = QuonfigLogger(quonfig: quonfig, loggerKey: "log-level.my-app")
log.trace("entering render")
log.debug("cache warm: \(count) entries") // suppressed unless level <= DEBUG
log.info("signed in as \(userID)")
log.warn("retrying after \(err)")
log.error("checkout failed: \(err)")
The severity ladder is TRACE < DEBUG < INFO < WARN < ERROR < FATAL (the same
ranks every Quonfig SDK uses). A record emits iff its level is at or above the
configured threshold — a log_level config of WARN emits WARN/ERROR/FATAL
and drops the rest. The gate is re-checked on every call, so flipping the config
takes effect on the next log line. Message arguments are autoclosures, so a
suppressed record never builds its string.
Just want the decision (to gate your own logging framework)?
if quonfig.shouldLog(.debug, loggerKey: "log-level.my-app") { /* … */ }
Supply a QuonfigLogSink to bridge to another backend instead of os.Logger:
struct MySink: QuonfigLogSink {
func emit(level: QuonfigLogLevel, message: String) { /* forward anywhere */ }
}
let log = QuonfigLogger(quonfig: quonfig, loggerKey: "log-level.my-app", sink: MySink())
Quonfig evaluates server-side, so a frontend SDK gates against the single
threshold the server resolved for its current context. Per-logger overrides
(the backend SDKs' per-quonfig-sdk-logging.key routing) require on-device
evaluation and aren't available here — one log_level config drives one
threshold for the whole client. Best for application-wide log-level control, or
rules that key on stable context (user, app version, environment). Call
updateContext to re-evaluate after a context change.
Exposure-decoupled reads
The typed getters (isEnabled, string, int, double, stringList,
duration) take a logExposure: parameter (default true), so debug screens
and pre-render probes can read a flag without it counting as an exposure for
telemetry. json and details don't take it:
let v = quonfig.isEnabled("new-checkout", logExposure: false)
Offline & server-side evaluation
Because Quonfig evaluates entirely server-side:
- Cold start / offline for a previously-seen context works — the cached envelope is served instantly (no flicker), and also on a failed poll, so the last known-good values stay on screen.
- Offline with a new context can't be evaluated on-device. With no cached
envelope,
onInitFailuredecides: the default.failthrows frominitialize, and.continueserves your supplied defaults until the network returns (see startup).
Telemetry & privacy
By default the SDK uploads per-flag evaluation summaries (opt out with
collectEvaluationSummaries: false). Context shapes/examples are captured
server-side; tune with collectContextMode (PERIODIC_EXAMPLE default,
SHAPE_ONLY, or NONE).
The SDK ships an App Store PrivacyInfo.xcprivacy (wired into the SPM package
resources), and disables the eval request's URLCache so the context-bearing
eval URL is never written to an on-device cache.
Delivery options
How the SDK delivers telemetry, and what it does when the endpoint is slow or down, is the same in
every SDK and is explained once on the Telemetry page.
The Swift Configuration options and defaults:
| option | default |
|---|---|
telemetryFlushInterval | 60 (seconds) |
telemetryTimeout | 15 (seconds, foreground POST, connect and TLS included) |
telemetryMaxRetainedBatches | 5 |
telemetryMaxRetainedBytes | 524_288 (512KB) |
telemetryMaxRetainedAge | 300 (seconds) |
telemetryMaxEvaluationSummaries | 10_000 |
logSink | nil (os.Logger, subsystem com.quonfig.sdk, category Telemetry) |
Disk queue. Each window is serialized once and written to an on-disk queue (Application
Support, one file per batch) before it is POSTed, and deleted only after a 2xx. A window in flight
when the app is backgrounded or killed is resent byte for byte on the next foreground tick or
launch, unless it is older than 5 minutes by then.
Background. When the app goes to the background, the live window is written to disk and
POSTed once inside an OS background activity (ProcessInfo.performExpiringActivity), with a ~5s
network budget. shutdown() does the same final write-then-POST with the same ~5s bound, but runs
it directly in your await, not inside a background activity. In both cases older queued batches
wait for the next foreground tick, and the final POST is skipped if another POST is already in
flight or the 30s post-failure floor or a server Retry-After has not elapsed yet; the window
stays on disk and is sent on the next foreground tick or launch.
A 401, 403 or 404 from the telemetry endpoint stops telemetry for the process with one error
and deletes the queue.
Teardown
await quonfig.shutdown() // stops polling + telemetry, sending one last window (~5s max)
Reference
Quonfig methods
| method | purpose |
|---|---|
Quonfig.initialize(context:options:onInitFailure:initTimeout:) | create a client; resolves once the first envelope (network or cache) is available, otherwise follows onInitFailure |
isEnabled(_:logExposure:) | Bool (default false) for a flag in the current context |
string(_:default:logExposure:) / int(_:default:logExposure:) / double(_:default:logExposure:) | typed value or your default |
stringList(_:default:logExposure:) | [String] or your default |
duration(_:default:logExposure:) | TimeInterval in seconds, or your default |
json(_:) | [String: Any]? for an object config |
details(_:) | full resolution details (value + reason + variant + errorCode) |
details(_:as:) | resolution details under the typed getters' rules for a QuonfigValueType |
subscribe(_:) | run a closure after every change; returns a cancellation token |
updateContext(_:) | switch identity and refetch |
shouldLog(_:loggerKey:) | whether a record at a level should emit under a log_level config |
logLevelThreshold(for:) | the resolved QuonfigLogLevel for a log_level config, or nil |
shutdown() | stop polling + telemetry (sends one last window; queued batches are not drained) |
context / isReady / source | current context; whether an envelope has been applied; where values come from (.network, .cache, .defaults) |
waitForReady() | wait until an envelope (network or cache) has been applied |
Configuration options
| option | type | default | description |
|---|---|---|---|
sdkKey | String | required | your frontend SDK key |
domain | String | "quonfig.com" | single knob flipping api + telemetry hosts in lockstep |
apiURLs | [URL]? | derived from domain | explicit API base URLs (failover order); wins over domain |
telemetryURL | URL? | derived from domain | explicit telemetry base URL; wins over domain |
pollInterval | TimeInterval | 60 | foreground poll interval; 0 disables polling |
collectEvaluationSummaries | Bool | true | upload per-flag evaluation summaries; other telemetry* options are under Delivery options |
collectContextMode | CollectContextMode | .periodicExample | .periodicExample, .shapeOnly, or .none |
requestTimeout / resourceTimeout | TimeInterval? | nil | per-request / resource timeouts |
customHeaders | @Sendable () -> [String: String] | {} | headers recomputed per request (e.g. rotating proxy tokens) |