Skip to content
FlagSwiftDocs

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.

Every SDK, its package and the key it needs
SDKKeyDescription
JavaScriptclient@flagswift/js. Browser, framework-free.
Reactclient@flagswift/react. Provider and hooks.
React Nativeclient@flagswift/react-native. Adds app-state pausing.
Vueclient@flagswift/vue. Plugin, composables, component and directive.
Flutterclientflagswift on pub.dev. Pure Dart client plus widgets.
SwiftclientFlagSwift via Swift Package Manager. SwiftUI layer included.
Next.jsserver and client@flagswift/nextjs. Server helper with a server key; /client provider with a client key.
Node.jsserver@flagswift/node. Local evaluation.
NestJSserver@flagswift/nestjs. Module, service, guard.
Goservergithub.com/flagswift/flagswift-go. Standard library only.
Pythonserverflagswift. Standard library only.
PHPserverflagswift/flagswift-php. Shared config store.
Laravelserverflagswift/flagswift-laravel. Facade, Blade, middleware.
.NETserverFlagSwift and FlagSwift.Extensions.DependencyInjection.
Javaserverio.flagswift:flagswift-java and a Spring Boot 3 starter.

Package names

Registry names for Go, PHP, Laravel, .NET, Java, Flutter and Swift are placeholders until publishing is decided. Use the path in your own source tree until then.

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.

Options shared by the SDKs
OptionTypeDescription
apiKey*stringClient key (fs_client_) for client SDKs, server key (fs_srv_) or admin key for server SDKs. Empty throws MISSING_API_KEY.
baseUrl*stringYour server address. Must start with http:// or https://, or MISSING_BASE_URL is thrown. There is no default host. A trailing slash is trimmed.
environmentstringOnly 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.
refreshIntervaldurationHow often to check for changes. Default 30 seconds. Zero or negative turns polling off. Failures slow it down (see below).
streamingbooleanJavaScript, 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.
streamingPollIntervaldurationWhile a stream is connected, polling slows to this safety net. Default 5 minutes.
autoExposuresbooleanReport an exposure the first time each person gets each outcome from a single-flag read. Default false. See Outcome analytics.
timeoutdurationPer request. Default 5 seconds (2 in the PHP SDK).
initTimeoutdurationThe longest startup waits for the first load. Default 5 seconds. Startup never throws when it passes.
maxRetriesnumberRetries 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.
fallbacksmapValues served for unknown flags, or before anything has loaded. A boolean sets on or off; anything else is served as the value.
bootstrap / initialFlagspayloadStart 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 / snapshotPathadapter or pathClient SDKs keep the last flags in a storage adapter; server SDKs keep the last configuration in a file (written atomically, owner-only).
reportErrorsbooleanReport error counts, never user data, at most once a minute. Default true.
onErrorfunctionCalled when a refresh fails. It must not block. SDKs never throw from a flag check.
onUpdatefunctionServer 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.

ts
{ 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, contains and in, using the same string conversion in every language.

What an evaluation returns#

Fields of an evaluation result
FieldTypeDescription
enabledbooleanWhether the flag is on for this person.
reasonstringWhy. Server SDKs always know it; client SDKs do not receive reasons.
variantstringThe chosen variant key of a multivariate flag.
valueanyThe variant's value: string, number or JSON. Plain flags have none.
foundbooleanServer SDKs: false when the flag is unknown or unusable, so you can tell a missing flag from an off one.
versionnumberClient SDKs: the flag's version, which rises with every change.
Evaluation reasons
ReasonDescription
KILL_SWITCHThe emergency stop is active.
DISABLEDThe flag is off in this environment.
TARGETED_USERThe person is named in the flag's targeting list.
SEGMENT_MATCHThe person is in a segment the flag targets.
RULE_MATCHA rule's conditions matched.
DEPENDENCY_BLOCKEDA prerequisite flag is not on.
FULL_ROLLOUTThe rollout is at 100 percent.
ROLLOUT_INThe person's bucket falls inside the rollout percentage.
ROLLOUT_OUTThe person's bucket falls outside it.
NO_IDENTIFIERThe flag buckets on something the person did not provide.
ENV_NOT_CONFIGUREDNothing has loaded, or the flag has no settings for this environment.
FLAG_NOT_FOUNDUnknown 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 throwing onError cannot break polling.
  • An ETag is kept only for a response that passed validation, so a later 304 can 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-After is 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; a 304 counts 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, on POST as well as GET, and drop the tag when the person changes. On FlagSwift Commercial a 304 is free and a 200 counts toward the plan's request allowance.
  • A 401 or 403 is 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. A 402 is never returned by the delivery endpoints, so a plan limit cannot break flag delivery.
  • A configuration with an unknown hashVersion is refused (UNSUPPORTED_HASH_VERSION) and the last good one stays.
  • Error counts, at most 50 distinct entries, go to /api/v1/evaluation/errors after a successful refresh, at most once a minute.
Error codes
CodeDescription
MISSING_API_KEYThe key is empty.
MISSING_BASE_URLThe address is missing or does not start with http:// or https://.
NETWORK_ERRORThe request could not be made.
TIMEOUTThe request ran past its timeout.
HTTP_<status>The server answered with an error status, for example HTTP_401.
INVALID_RESPONSEThe reply was not the expected shape.
UNSUPPORTED_HASH_VERSIONThe 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 streaming as off, connecting, connected or unavailable.
ts
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.

Where each SDK keeps its last good data
SDKDescription
JavaScript, React, VuelocalStorage by default. Pass storage: false to turn it off, or your own adapter.
React Native, FlutterPass a storage adapter (AsyncStorage, SharedPreferencesStorage). Without one nothing survives a restart.
SwiftUserDefaults by default. Set storage to nil to turn it off.
Node.js, NestJS, Go, Python, Java, .NETA snapshot file, set with snapshotPath (SnapshotPath, WithSnapshotPath, snapshotPath(...) in Java). Corrupt or wrong-hash files are ignored.
PHP, LaravelThe 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: identify while 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.

Every SDK page
SDKRequiresVerified
JavaScriptRequires:Any modern browserVerified:Tested against shared vectors
ReactRequires:React 18+Verified:Unit tests
React NativeRequires:React Native 0.70+, AsyncStorage for the cacheVerified:Unit tests
VueRequires:Vue 3.3+Verified:Unit tests
FlutterRequires:Dart 3, Flutter 3.13+Verified:Not yet compiled
SwiftRequires:Swift 5.9, iOS 14+Verified:Not yet compiled
Next.jsRequires:Next.js 13.4+, React 18+Verified:Unit tests
Node.jsRequires:Node 18+Verified:Tested against shared vectors
NestJSRequires:NestJS 9+, Node 18+Verified:Unit tests
GoRequires:Go 1.21+Verified:Tested against shared vectors
PythonRequires:Python 3.8+Verified:Tested against shared vectors
PHPRequires:PHP 8.1+Verified:Tested against shared vectors
LaravelRequires:Laravel 10 to 13Verified:Tested against stand-ins for Laravel only
JavaRequires:Java 11+ (the Spring Boot starter needs Java 17)Verified:javac and JUnit only, no real Maven build
.NETRequires:.NET 8+Verified:Not yet compiled