LiftCanary

Guides

Locations and triggers

Saved sets of pages, and activation on click, visibility, an element or your own code.

Audiences say who takes part; locations say where. A location is a saved set of pages, such as “every product page except previews” or “cart and all checkout steps”, that experiments, flag rules, audiences, redirect tests and goals refer to by key. When your URLs change, you fix them in one place.

Pages#

A page belongs to a location when any include rule matches it and no exclude rule does. Each rule has a match type and an optional case sensitive switch (off by default; host names are always compared case-insensitively).

TypeCompared withExample
Simplepath (or host + path), ignoring http/https, www., a trailing /, the query and the hash/pricing
Exactpath; add ?a=1 to the pattern to compare the query too/cart
Starts withpath (or host + path)/products/
Containsanywhere in host + path + querypreview=1
Regular expressionorigin + path + query, in JavaScript syntax^https://shop\.com/(tr|en)/p/\d+

The location editor has a URL tester: paste one or more addresses and see which rule includes or excludes each, computed with the SDK's own matcher. The templates (whole site, home page, product pages, categories, cart and checkout, blog) are a starting point; adjust the paths to your site.

Using a location#

WhereHow
Experiment wizard“Where, and who takes part?” → Pages. Combined with the audience.
Flag rules and audiencescondition { "location": "product_pages" }, also inside all/any/not
Redirect tests“Saved location” instead of custom page rules (page-load locations only, see below)
Goals“Only on some pages” → saved location; trigger.location in the API, together with or instead of pages

In the dashboard, Choose (or Change) opens the list of locations with each one's page rules, exclusions and trigger, searchable by name or URL; click one to use it.

Editing a location updates everything that uses it in the next datafile. A location that is in use can't be deleted; its page lists where it's used.

How it's evaluated#

A location condition is matched against the full current address, query string included, so an exclusion like contains preview=1 works. The website snippet passes it as user.page and refreshes it on single-page-app navigation (pushState, popstate). The address stays on the device: it is never sent with events, because query strings can contain personal data.

Apps and servers have no page; there, the url attribute is used if you pass one. An unknown location, or no page at all, never matches.

Activation triggers#

By default a visitor is in a location as soon as one of its pages loads. A location can instead wait for something to happen on the page, so an experiment only enrolls, and only counts, the visitors who get that far. Testing a new size chart? Count only people who open the size chart, not everyone who sees a product page.

TriggerActivates whenAPI
When the page loads (default)a page of the location loads{ "type": "pageload" }
When an element is clickedthe element, or something inside it, is clicked{ "type": "click", "selector": ".size-chart" }
When an element comes into viewthe element scrolls into view{ "type": "visible", "selector": "#reviews" }
When an element is on the pagethe element exists, also when it's added later (popups, single-page apps){ "type": "element", "selector": ".upsell-modal" }
From your codeyour page calls liftcanary.activate("key"){ "type": "manual" }
  • Each trigger fires once per page view, and only on the location's own pages.
  • A new address, including a pushState navigation, starts over: the location is inactive until its trigger fires again.
  • An invalid CSS selector never breaks the page; it simply never matches.

Reacting to an activation#

Flags evaluated after the trigger see the location. Put the code that changes the page in whenActive, which runs right away if the visitor is already in the location and again on every later activation:

JavaScript
liftcanary.whenActive("size_chart", (sk) => {
  if (sk.isEnabled("new_size_chart")) showNewSizeChart();
});

// Every activation, any location
liftcanary.onActivate((locationKey) => console.log("activated", locationKey));
window.addEventListener("liftcanary:activate", (e) => console.log(e.detail.location));

Manual activation#

JavaScript
// When your quiz, configurator or modal is ready:
liftcanary.activate("size_quiz");

// Without a key: every manual location the visitor is on
liftcanary.activate();

activate(key) also forces a click, visible or element location, which helps in tests. It is safe to call before the SDK has loaded: the snippet's inline stub queues it.

Server-side and in apps#

The browser snippet passes the activated keys to the decision engine as user.activeLocations (never sent with events). Other SDKs can pass them too:

TypeScript
client.createUser({ id, page: "https://shop.com/products/42", activeLocations: ["size_chart"] }).decide("new_size_chart");

API#

POST /v1/projects/web/locations
{
  "key": "product_pages",
  "name": "Product pages",
  "description": "Every product page, without previews",
  "include": [{ "type": "startsWith", "value": "/products/" }],
  "exclude": [{ "type": "contains", "value": "preview=1" }],
  "trigger": { "type": "pageload" }
}

See Endpoint reference → Locations. PATCH changes only the fields you send.