LiftCanary

Guides

Targeting and audiences

Conditions, operators, built-in attributes and reusable audiences.

Targeting decides who a rule or an experiment applies to. You build it from conditions on the user's attributes; an audience is a set of conditions saved under a name so it can be reused in many flags and experiments.

Conditions#

A condition compares one attribute with a value:

JSON
{ "attribute": "country", "op": "in", "value": ["TR", "DE"] }

Conditions combine into a tree with all (and), any (or) and not, and can refer to saved audiences and locations:

Mobile visitors from Türkiye on product pages, except beta testers
{
  "all": [
    { "attribute": "country", "op": "eq", "value": "TR" },
    { "attribute": "device", "op": "eq", "value": "mobile" },
    { "location": "product_pages" },
    { "not": { "segment": "beta_testers" } }
  ]
}

In the dashboard, the condition editor shows rows joined by and (or or at the top level), with proper pickers for countries, languages, devices and versions. Anything richer opens as JSON.

Operators#

OperatorTrue whenValue
eqthe attribute equals the valueone value
neqthe attribute is set and differs from the valueone value
inthe attribute is one of the valuesa list
ninthe attribute is set and none of the valuesa list
contains, startsWith, endsWithtext comparisontext
matchesa JavaScript regular expression matches the texta pattern
gt, gte, lt, ltenumeric comparison (both sides must be numbers)a number
semverEq, semverGt, semverGte, semverLt, semverLteversion comparison: 2.10.0 is above 2.9.1a version
existsthe attribute is set (not missing, not null)none

Add "ignoreCase": true to compare text case-insensitively (eq, neq, in, nin, contains, startsWith, endsWith, matches).

Exact semantics#

  • Type-strict. "10" never equals 10. Send numbers as numbers if you compare them with gt/lt.
  • A missing attribute makes every operator false, including neq and nin, except exists. To target users who don't have an attribute, use { "not": { "attribute": "plan", "op": "exists" } }.
  • all: [] is true (everyone); any: [] is false (no one).
  • An unknown audience, an unknown location and an unknown operator are false.
  • Regular expressions are checked for catastrophic backtracking when saved and again in the SDK, and text longer than 1,024 characters never matches a regex, so a pattern can't freeze a visitor's browser.

Built-in attributes#

These keys are understood everywhere: SDKs, datafiles and saved audiences use them, and the dashboard offers proper pickers for them. The website snippet collects most of them by itself; anything else you pass yourself.

KeyMeaningCollected by
countryFrom the visitor's IP address (ISO code, e.g. TR).Website
regionFrom the IP address (e.g. 34 for Istanbul, CA for California).Website
cityFrom the IP address. Less precise than country.Website
deviceDetected from the browser.Values: desktop, mobile, tabletWebsite
osDetected by the website snippet. In apps, pass Platform.OS yourself.Values: ios, android, windows, macos, linux, chromeos, otherWebsite
browserDetected from the browser.Values: chrome, safari, firefox, edge, samsung, opera, otherWebsite
platformWebsite or native app. The snippet sets web; apps pass ios or android.Values: web, ios, androidWebsite
visitorNew during their first session on the site, returning afterwards.Values: new, returningWebsite
languageBrowser language (e.g. tr, en). In apps, pass the device language yourself.Website
utm_sourceutm_source of the landing URL, kept for the session.Website
utm_mediumutm_medium of the landing URL, kept for the session.Website
utm_campaignutm_campaign of the landing URL, kept for the session.Website
referrerDomain the visitor came from (e.g. google.com). Empty for direct visits.Website
pathCurrent page path, e.g. /checkout.Website
urlCurrent page address without the query string.Website
app_versionPass your app's version (e.g. 2.4.0) as an attribute.you
  • Country, region and city come from the CDN's geo headers (Cloudflare, Vercel or CloudFront) via the snippet's /geo request; the SDK receives the place names, never the IP address.
  • url never includes the query string or the hash. Locations match the full address, but on the device only (see Locations).
  • UTM values are the first touch of the session, so they stay the same while the visitor browses.

Your own attributes#

Pass anything else you know about the user: plan, company size, signup date, feature usage.

JavaScript
// Website snippet
liftcanary.setAttributes({ plan: "pro", seats: 12 });
liftcanary.identify("user_8812", { plan: "pro" }); // after login

// SDKs
const user = client.createUser({ id: "user_8812", attributes: { plan: "pro", seats: 12, app_version: "2.4.0" } });

Audiences#

Audiences (Project → Audiences) are saved condition sets with a key, a name and a plain-language summary. The builder has a searchable attribute picker, country and language pickers that understand names like “Turkey”, “UK” or “USA”, all/any matching and Test a visitor, which runs the SDK's own evaluator against attributes you type.

  • Use one in a rule or an experiment with { "segment": "key" } (the API calls audiences segments).
  • Audiences can include other audiences; cycles are rejected.
  • An audience that is in use can't be deleted; the error lists where it's used.
  • Editing an audience updates every flag and experiment that uses it, in the next datafile.