LiftCanary

Getting started

Core concepts

Projects, environments, flags, variations, variables, rules, datafiles and events.

Organization and project#

An organization is your company's account: people, roles and API tokens belong to it. People can be members of several organizations and switch between them. A project is one product (your shop, your app); flags, audiences, locations, goals and experiments live in a project. Web and mobile versions of one product usually share a project, so a user sees the same variation on both.

Environment and SDK key#

Each project has environments, by default development and production. A flag is defined once per project, but switched on, targeted and tested per environment. Each environment has a public SDK key (pk_…) that SDKs use to download its datafile and send events. It can't change anything, so it's safe in page source and app bundles.

Add, rename and delete environments, and regenerate an SDK key, under Project settings. Regenerating a key cuts off every app still using the old one, so do it only when a key ended up somewhere it shouldn't be.

Flag#

A flag is a named decision point in your code, like new_checkout. For each user, the SDK decides which variation of the flag they get.

Variations#

A variation has a key (used by code, rules and analytics), an optional display name, and an enabled switch: whether the feature is “on” for users who get it. A simple flag has off and on; an experiment flag can have control, one_page and two_step. The first variation is the baseline in experiments.

Variables (remote config)#

Variables are typed values (text, number, true/false or JSON) with a default, which each variation can override: a button label, a price, a timeout, a whole layout config. Reading variables instead of comparing variation keys keeps your code working when variations are renamed or added.

JavaScript
// Robust: works for any number of variations
const label = liftcanary.variable("new_checkout", "button_text", "Buy now");

// Brittle: breaks when a variation is renamed
if (liftcanary.decide("new_checkout").variationKey === "one_page") { /* … */ }

Targeting rules#

In each environment a flag has:

  • an on/off switch (the kill switch); when off, everyone gets the off variation,
  • user overrides: specific user ids pinned to a variation, for QA and allowlists,
  • rules, evaluated top to bottom. Each rule has optional conditions (who it applies to), a traffic share and an allocation across variations,
  • a default variation for users no rule took.

A rule is either a rollout (deliver variations, nothing is measured) or an experiment (users are randomized and an exposure is recorded, so results can be computed). Shares are in buckets: 10,000 buckets are 100%, so 2,500 is 25%.

Audience and location#

Conditions say who a rule is for. An audience is a saved, reusable set of conditions (“mobile visitors from Türkiye”). A location is a saved set of pages (“product pages, except previews”), optionally with a trigger such as a click. See Targeting and audiences and Locations and triggers.

User, attributes and bucketing#

SDKs decide for a user: an id plus attributes (country, device, plan, app version…). The website snippet fills in many attributes by itself and uses an anonymous id stored in the browser; call identify() after login (see identity for what changes at login) so a person keeps their variation across devices. Assignment is deterministic: the same user id, flag and rule always give the same variation, on every platform, with no state stored anywhere.

Datafile and revision#

Every change in an environment publishes a new datafile with a higher revision. SDKs fetch it and never go back to an older revision. How soon a change reaches users depends on the SDK: the Node.js and Python SDKs get live updates, so a flag change or a kill switch reaches your servers in about a second (they still check every 30 seconds in case the connection drops). The npm and React Native clients check every minute and when the app comes back to the foreground, and the website snippet on every page load, every 5 minutes and whenever the tab becomes visible again (see SDK reference). Browsers and apps also keep the last datafile they downloaded, so they can still decide when offline. The format is documented in Datafile format.

Experiment, exposure and goal#

TermMeaning
ExperimentAn experiment rule on a flag in one environment, plus a name, hypothesis, metrics, confidence level and status (draft, running, stopped).
ExposureRecorded the first time a user is decided into an experiment variation. Only exposed users count in results, and only their events after exposure.
EventSomething a user did: track("purchase", { value }) or an automatically tracked click, page visit or form.
GoalA named metric on an event: a conversion rate, a value per user (revenue) or an average per event (latency). Each goal knows whether higher or lower is better.
GuardrailA goal an experiment must not make worse; checked automatically, with an optional automatic stop.