SDKs
SDK reference
Client options, the user context, decisions and reasons, shared by every SDK.
The npm, React Native and Node.js SDKs are thin platform layers over one engine, @liftcanary/core. Everything on this page works the same in all of them; each package re-exports the core types. The Python, Go, Java, PHP, Ruby, .NET, Swift, Kotlin and Flutter SDKs port the same engine and pass the same test vectors, with each language's naming (create_user in Python and Ruby, CreateUser in Go and .NET).
Client options#
const client = createClient({ sdkKey: "pk_...", pollingIntervalMs: 60_000 });sdkKeyrequiredstring | The environment's public SDK key. |
datafileDatafile | A datafile to start from, so the first decisions need no network request (server rendering, bundled in an app). |
cdnUrlstring | Where datafiles are downloaded from: <cdnUrl>/datafiles/<sdkKey>.json. Default https://cdn.liftcanary.com. |
eventsUrlstring | Where events are sent: <eventsUrl>/v1/batch. Default https://events.liftcanary.com. |
pollingIntervalMsnumber | How often to check for a new datafile. Default 60000 (Node.js: 30000). 0 turns polling off. |
streamingboolean | Live updates: published changes arrive in about a second, with polling underneath. Default true in Node.js, the only JavaScript platform that has them; browsers and apps poll. |
streamUrlstring | Where live updates connect: <streamUrl>/stream/<sdkKey>. Default: cdnUrl. |
eventBatchSizenumber | Events per request. Default 20 (Node.js: 200). |
eventFlushIntervalMsnumber | How often queued events are sent. Default 5000 (Node.js: 2000). |
eventMaxQueueSizenumber | Events kept in memory before the oldest are dropped. Default 1000 (Node.js: 20000). Drops are counted in client.events.dropped. |
cacheDatafileboolean | Default true. Saves the last datafile in the platform's storage (localStorage, AsyncStorage) and uses it when a download fails or is slower than ready()'s timeout. Only works where the SDK has storage: not in Node.js. |
loggerLogger | Receives debug, warning and error messages. Silent by default; consoleLogger is exported. |
Client#
ready(timeoutMs = 3000)Promise<boolean> | Resolves true once a datafile is available. If the download fails or the timeout passes, the cached datafile is used when there is one; otherwise false. Never rejects. |
createUser(user)UserContext | The person the following decisions and events are for. Not an account: nothing is created or sent, so it's free to call once per request or render. With anonymousId, also links it (see identify). |
identify(userId, anonymousId)void | Links an anonymous id to a user (a sign-in), so results count them as one person. Sent once per pair. See From landing page to app. |
decide(flagKey, user, options?)Decision | Decide one flag. Logs an exposure for experiment rules unless sendExposure is false. |
decideAll(user, options?)Record<string, Decision> | Decide every flag in the datafile. |
track(eventKey, user, options?)void | Record an event. |
logExposure(decision, user)void | Record an exposure yourself (after deciding with sendExposure: false). Deduplicated per user, flag, rule and variation. |
subscribe(listener)() => void | Called whenever a newer datafile is applied. Returns an unsubscribe function. |
onExposure(listener)() => void | Called with { flagKey, ruleKey, variationKey, userId } for every exposure logged (once per user, flag, rule and variation; never in preview), e.g. to tell your own analytics. Returns an unsubscribe function. |
setPreview(forced | null)void | Preview mode: { flag: variation } decides those variations for everyone and sends nothing until it's turned off with null. |
datafileDatafile | null | The current datafile. |
revisionnumber | Its revision; −1 until one is loaded. |
setDatafile(datafile)boolean | Apply a datafile you fetched yourself. Ignored (false) if older than the current one. |
refreshDatafile()Promise<boolean> | Check for a new datafile now. |
flush()Promise<void> | Send queued events now. |
close()Promise<void> | Stop polling, flush events and release listeners. |
events.droppednumber | Events dropped because the queue was full. |
User#
idrequiredstring | Stable user id: your user id, or an anonymous id for visitors who aren't logged in. |
attributesRecord<string, string | number | boolean | null> | Targeting attributes. Sent with events. See built-in attributes. |
bucketingIdstring | Hash on this instead of id, e.g. a company id, so a whole account gets one variation. |
pagestring | Full current URL for location conditions. Never sent with events. |
activeLocationsstring[] | Keys of triggered locations activated on this page view. Never sent with events. |
anonymousIdstring | The anonymous id this person had before signing in (the liftcanary_anon cookie). Not used for decisions; linked to id once. |
UserContext#
const user = client.createUser({ id: "user_8812", attributes: { plan: "pro" } });
user.isEnabled("new_checkout"); // boolean
user.getVariable("new_checkout", "button_text", "Buy now"); // typed, with a fallback
user.decide("new_checkout"); // Decision
user.decide("new_checkout", { sendExposure: false }); // decide now, log the exposure later
user.decideAll();
user.track("purchase", { value: 499.9, properties: { currency: "TRY" } });
user.logExposure(decision);getVariable returns the fallback when the flag or variable doesn't exist, the value is null, or its type differs from the fallback's (a number fallback never receives a string).
Decision#
{
"flagKey": "new_checkout",
"enabled": true,
"variationKey": "one_page",
"ruleKey": "checkout_test",
"inExperiment": true,
"reason": "RULE_MATCH",
"variables": { "button_text": "Complete order" },
"revision": 42
}| Reason | Meaning |
|---|---|
NOT_READY | No datafile yet. Every flag is off with no variables: your fallbacks apply. |
FLAG_NOT_FOUND | The flag doesn't exist in this environment (never created, or archived). |
FLAG_DISABLED | The flag is switched off: the off variation. |
OVERRIDE | The user id has an override. |
PREVIEW | A variation forced with client.setPreview() (the website snippet's preview links). Nothing is sent while a preview is on. |
RULE_MATCH | A rule took the user; ruleKey says which. inExperiment is true for experiment rules. |
DEFAULT | The flag is on but no rule took the user: the default variation. |
variables always holds every variable of the flag: the variation's values over the flag's defaults.
Exposures#
decide (and everything built on it: isEnabled, getVariable, the hooks, the snippet) records an exposure when the user is in an experiment rule. Exposures are deduplicated in memory per user, flag, rule and variation, and again in the warehouse, so calling isEnabled in a loop is fine.
Events and delivery#
- Events are queued and sent in batches, with exponential backoff (up to a minute) on network errors and 5xx/429 responses.
- Other 4xx responses drop the batch: it can never be accepted.
- Every event has a
uuid, so retries are deduplicated by the collector. - The browser and React Native SDKs persist the queue (localStorage, AsyncStorage) so events survive reloads and restarts, and keep the last datafile there for offline starts.
Wire format: Events and the collector.