Options and behaviour
What every SDK shares: the options they take, how a person is described, what an evaluation returns, and how they behave when the network does not. Language pages list each SDK's exact methods.
Two kinds of SDK#
Server SDKs use a server (or admin) key, download the environment's configuration and evaluate it in memory, so a flag check is a local call with no network. Node.js, NestJS, Go, Python, PHP, Laravel, .NET, Java and the Next.js server helper work this way.
Client SDKs use a client key and ask the server what is on for one person. The server decides, so no targeting rules ever reach the device. JavaScript, React, React Native, Vue, Flutter, Swift and the Next.js browser provider work this way.
| SDK | Key | Description |
|---|---|---|
| JavaScript | client | @flagswift/js. Browser, framework-free. |
| React | client | @flagswift/react. Provider and hooks. |
| React Native | client | @flagswift/react-native. Adds app-state pausing. |
| Vue | client | @flagswift/vue. Plugin, composables, component and directive. |
| Flutter | client | flagswift on pub.dev. Pure Dart client plus widgets. |
| Swift | client | FlagSwift via Swift Package Manager. SwiftUI layer included. |
| Next.js | server and client | @flagswift/nextjs. Server helper with a server key; /client provider with a client key. |
| Node.js | server | @flagswift/node. Local evaluation. |
| NestJS | server | @flagswift/nestjs. Module, service, guard. |
| Go | server | github.com/flagswift/flagswift-go. Standard library only. |
| Python | server | flagswift. Standard library only. |
| PHP | server | flagswift/flagswift-php. Shared config store. |
| Laravel | server | flagswift/flagswift-laravel. Facade, Blade, middleware. |
| .NET | server | FlagSwift and FlagSwift.Extensions.DependencyInjection. |
| Java | server | io.flagswift:flagswift-java and a Spring Boot 3 starter. |
Package names
Options every SDK takes#
Names follow each language's habits (baseUrl, WithBaseURL, base_url, BaseUrl). The language pages show the exact spelling. Durations are milliseconds in JavaScript, seconds in Python and PHP, and native duration types elsewhere.
| Option | Type | Description |
|---|---|---|
| apiKey* | string | Client key (fs_client_) for client SDKs, server key (fs_srv_) or admin key for server SDKs. Empty throws MISSING_API_KEY. |
| baseUrl* | string | Your server address. Must start with http:// or https://, or MISSING_BASE_URL is thrown. There is no default host. A trailing slash is trimmed. |
| environment | string | Only for keys that cover every environment of a project. The Go, Python, Java, .NET and Laravel SDKs fall back to the FLAGSWIFT_ENVIRONMENT variable; the others (Node.js, NestJS, Next.js, PHP) take it only as an option. |
| refreshInterval | duration | How often to check for changes. Default 30 seconds. Zero or negative turns polling off. Failures slow it down (see below). |
| streaming | boolean | JavaScript, React, Vue, Next.js (client provider), Node, NestJS, Go, Python and Java: open the real-time stream (see Real-time updates). Default false. PHP, Laravel, .NET, Flutter, Swift and React Native do not stream; they poll. |
| streamingPollInterval | duration | While a stream is connected, polling slows to this safety net. Default 5 minutes. |
| autoExposures | boolean | Report an exposure the first time each person gets each outcome from a single-flag read. Default false. See Outcome analytics. |
| timeout | duration | Per request. Default 5 seconds (2 in the PHP SDK). |
| initTimeout | duration | The longest startup waits for the first load. Default 5 seconds. Startup never throws when it passes. |
| maxRetries | number | Retries for network errors, timeouts, 429 and 5xx. Default 2 for client SDKs, 3 for server SDKs (2 in the PHP SDK). 4xx other than 429 is never retried. |
| fallbacks | map | Values served for unknown flags, or before anything has loaded. A boolean sets on or off; anything else is served as the value. |
| bootstrap / initialFlags | payload | Start from known data so the first check is correct. Server SDKs take a saved configuration; client SDKs take the flag results. Ignored if malformed or the hash version differs. |
| storage / snapshotPath | adapter or path | Client SDKs keep the last flags in a storage adapter; server SDKs keep the last configuration in a file (written atomically, owner-only). |
| reportErrors | boolean | Report error counts, never user data, at most once a minute. Default true. |
| onError | function | Called when a refresh fails. It must not block. SDKs never throw from a flag check. |
| onUpdate | function | Server SDKs: called after a new configuration replaces the old one. |
Describing a person#
Every check takes who is asking. identifier is the user, account is their organization or tenant, device is the install, and attributes are free-form values rules can match. Each of the three identifiers can also be a list. A rollout buckets on the first identifier of the kind the flag uses; any identifier can match explicit targeting.
{ identifier: "user-123", account: "acme", device: "ios-7f3a", attributes: { plan: "pro", country: "NG" } }- If a flag buckets by user and none is given, it serves off with the reason
NO_IDENTIFIER. - Most SDKs also accept a bare string or list of strings as shorthand for identifiers.
- Rules compare with
equals,containsandin, using the same string conversion in every language.
What an evaluation returns#
| Field | Type | Description |
|---|---|---|
| enabled | boolean | Whether the flag is on for this person. |
| reason | string | Why. Server SDKs always know it; client SDKs do not receive reasons. |
| variant | string | The chosen variant key of a multivariate flag. |
| value | any | The variant's value: string, number or JSON. Plain flags have none. |
| found | boolean | Server SDKs: false when the flag is unknown or unusable, so you can tell a missing flag from an off one. |
| version | number | Client SDKs: the flag's version, which rises with every change. |
| Reason | Description |
|---|---|
| KILL_SWITCH | The emergency stop is active. |
| DISABLED | The flag is off in this environment. |
| TARGETED_USER | The person is named in the flag's targeting list. |
| SEGMENT_MATCH | The person is in a segment the flag targets. |
| RULE_MATCH | A rule's conditions matched. |
| DEPENDENCY_BLOCKED | A prerequisite flag is not on. |
| FULL_ROLLOUT | The rollout is at 100 percent. |
| ROLLOUT_IN | The person's bucket falls inside the rollout percentage. |
| ROLLOUT_OUT | The person's bucket falls outside it. |
| NO_IDENTIFIER | The flag buckets on something the person did not provide. |
| ENV_NOT_CONFIGURED | Nothing has loaded, or the flag has no settings for this environment. |
| FLAG_NOT_FOUND | Unknown flag. The fallback is served. |
How they behave when things go wrong#
- A flag check never throws. The order of answers is the flag itself, then the check's own fallback, then the configured
fallbacks, then off. - A failed refresh keeps the last good flags (or configuration) and its ETag, records the failure in status or state, and calls
onError. That covers network errors, timeouts, 5xx, 401, 403 and 404, an HTML or garbage body, a wrong shape and an unknown hash version. A throwingonErrorcannot break polling. - An ETag is kept only for a response that passed validation, so a later
304can never hide a stale configuration. - Requests retry network errors, timeouts, 429 and 5xx with exponential backoff (500 ms base, 10 s cap, full jitter).
Retry-Afteris honoured up to 30 seconds. - Polling slows after failures: the delay doubles per consecutive failure up to five minutes (never below the interval), with 20 percent jitter either way (so the delay can pass the five-minute cap by up to 20 percent). A success resets it.
- Server SDKs poll with
If-None-Match; a304counts as success and costs almost nothing. Client SDKs (the JavaScript family, Flutter and Swift) do the same for the flags they fetched themselves for the same person, onPOSTas well asGET, and drop the tag when the person changes. On FlagSwift Commercial a304is free and a200counts toward the plan's request allowance. - A
401or403is terminal in every SDK: the key is wrong, revoked or limited to another environment, so the SDK keeps serving the last good flags, reports the failure and does not hammer the server. Fix the key and restart. A402is never returned by the delivery endpoints, so a plan limit cannot break flag delivery. - A configuration with an unknown
hashVersionis refused (UNSUPPORTED_HASH_VERSION) and the last good one stays. - Error counts, at most 50 distinct entries, go to
/api/v1/evaluation/errorsafter a successful refresh, at most once a minute.
| Code | Description |
|---|---|
| MISSING_API_KEY | The key is empty. |
| MISSING_BASE_URL | The address is missing or does not start with http:// or https://. |
| NETWORK_ERROR | The request could not be made. |
| TIMEOUT | The request ran past its timeout. |
| HTTP_<status> | The server answered with an error status, for example HTTP_401. |
| INVALID_RESPONSE | The reply was not the expected shape. |
| UNSUPPORTED_HASH_VERSION | The configuration uses a bucketing version this SDK does not know. |
Segments from your own code#
Every server and client SDK accepts segment keys on the person (segments), which count as extra segment membership for that evaluation. This is available in the JavaScript family (JavaScript, React, Vue, Next.js, React Native, Node.js, NestJS), Go, Python, PHP, Laravel, .NET, Java, Flutter and Swift. The SDK cleans the list before use: each key is trimmed, empty keys and keys over 128 characters are dropped, duplicates are removed and at most 100 are kept. The API rejects a whole request that carries an over-long key, so the SDKs drop them first.
Spring Boot
The Spring starter's default resolver reads no segments. Provide a custom resolver to pass them.
Real-time updates#
By default SDKs poll. With streaming: true the JavaScript, React, Vue, Next.js (client provider), Node, NestJS, Go, Python and Java SDKs also keep one Server-Sent Events connection open (see /api/v1/evaluation/stream in the Evaluation API). When a flag changes the server sends a small change event, and the SDK fetches the new configuration at once: server SDKs download it with their ETag and keep evaluating locally, client SDKs ask the server to evaluate again. The SDK's local cache and local evaluation work exactly as before; the stream only decides when to refresh.
- While connected, polling slows to
streamingPollInterval(5 minutes) as a safety net, because a change made on another server instance may not reach this connection. - If the connection drops it reconnects with backoff and jitter and refetches on reconnect, so nothing missed is lost. Polling resumes at its normal rate while it is down.
- If streaming is switched off on the server (
204), the endpoint is missing (an older server), the key is refused, or the runtime cannot read a response as it arrives (React Native), the SDK settles on polling and stays there. Flags keep working in every case. - Pausing the SDK (a hidden browser tab, an app in the background) closes the stream; resuming reopens it and refreshes.
- A change that arrives while a refetch is already running causes one more refetch right after it, so a change is never missed; a burst costs at most two fetches. The health report shows
streamingas off, connecting, connected or unavailable.
const flags = new FlagSwift({ apiKey, baseUrl, environment: "production", streaming: true });Offline and outages#
Once initialised, an SDK keeps answering without internet or while your FlagSwift server is down. Evaluation reads memory only. What differs is what survives a restart.
| SDK | Description |
|---|---|
| JavaScript, React, Vue | localStorage by default. Pass storage: false to turn it off, or your own adapter. |
| React Native, Flutter | Pass a storage adapter (AsyncStorage, SharedPreferencesStorage). Without one nothing survives a restart. |
| Swift | UserDefaults by default. Set storage to nil to turn it off. |
| Node.js, NestJS, Go, Python, Java, .NET | A snapshot file, set with snapshotPath (SnapshotPath, WithSnapshotPath, snapshotPath(...) in Java). Corrupt or wrong-hash files are ignored. |
| PHP, Laravel | The config store: a file, APCu or your Laravel cache. A failed refresh sets a backoff shared by all workers. |
| Next.js (server) | In memory per process, refreshed on use. Pass bootstrap for a start that works without the server. |
- A start with no network and nothing saved serves your
fallbacks, then off, until the server is reachable. This is the one gap. - Startup is bounded by
initTimeout. The fetch carries on in the background and applies when it arrives. - Client SDKs:
identifywhile offline uses the new person's cached flags if there are any, otherwise it keeps the previous flags. - PHP cannot be fully non-blocking when its stored copy is stale and the server is down: it makes one capped attempt per backoff window.
One page per SDK#
Each SDK has its own page, with an at-a-glance table and every method and option. Find them under SDK reference in the sidebar, or compare them on SDK features.
| SDK | Requires | Verified |
|---|---|---|
| JavaScript | Requires:Any modern browser | Verified:Tested against shared vectors |
| React | Requires:React 18+ | Verified:Unit tests |
| React Native | Requires:React Native 0.70+, AsyncStorage for the cache | Verified:Unit tests |
| Vue | Requires:Vue 3.3+ | Verified:Unit tests |
| Flutter | Requires:Dart 3, Flutter 3.13+ | Verified:Not yet compiled |
| Swift | Requires:Swift 5.9, iOS 14+ | Verified:Not yet compiled |
| Next.js | Requires:Next.js 13.4+, React 18+ | Verified:Unit tests |
| Node.js | Requires:Node 18+ | Verified:Tested against shared vectors |
| NestJS | Requires:NestJS 9+, Node 18+ | Verified:Unit tests |
| Go | Requires:Go 1.21+ | Verified:Tested against shared vectors |
| Python | Requires:Python 3.8+ | Verified:Tested against shared vectors |
| PHP | Requires:PHP 8.1+ | Verified:Tested against shared vectors |
| Laravel | Requires:Laravel 10 to 13 | Verified:Tested against stand-ins for Laravel only |
| Java | Requires:Java 11+ (the Spring Boot starter needs Java 17) | Verified:javac and JUnit only, no real Maven build |
| .NET | Requires:.NET 8+ | Verified:Not yet compiled |