Guides
Goals and metrics
Name what experiments measure, and track clicks, page visits, forms and scrolling without code.
A goal gives a name to something experiments measure: “Purchase”, “Revenue per visitor”, “Checkout errors”. It points at an event, says how to aggregate it and whether higher or lower is better. Goals are shared by every experiment in the project.
Tracking events from code#
liftcanary.track("signup"); // website snippet
liftcanary.track("purchase", { value: 129.9, properties: { currency: "TRY", items: 3 } });
user.track("purchase", { value: 129.9 }); // npm, React Native, Node.js (Python: user.track("purchase", value=129.9))valueis a number: revenue, items, seconds. It's what mean and ratio goals add up.propertiesare stored with the event for your own analysis; they don't affect results.trackis safe to call before the SDK is ready; events are queued, batched, retried and survive page reloads.
Goal types#
| Type | Measures | Example |
|---|---|---|
conversion | share of exposed users with the event at least once | Purchase rate, signup rate |
mean | sum of value per exposed user (users without the event count as 0) | Revenue per visitor |
ratio | sum of value ÷ number of events: an average per event | Latency per call, cost per request, order value |
Direction is increase (higher is better: purchases) or decrease (lower is better: bounces, errors, latency). A variation that lowers a “decrease” goal is the winner. One goal per event and type: a second “purchase conversion” goal is refused.
Goal ID#
A goal's key is also its ID: liftcanary.track("<goal key>") counts toward the goal exactly like its event. Code can complete a goal without knowing which event it measures. For that reason, a goal's key can't be another goal's event key, and vice versa.
Goals without code#
The website snippet tracks these by itself, so goals can be added and changed without a deploy.
- 1Page visit: a visit to a matching page, here
/checkout/success. - 2Click: a click on an element matching a selector, here
#continue. - 3Form submission: a form submitted, here
form.newsletter. - 4Scroll depth: reaching a share of the page, once per page view.
| Trigger | Counts | Settings |
|---|---|---|
| Page visit | a visit to a matching page, including single-page-app navigation | pages (URL rules) or a saved location |
| Click | a click on an element matching a CSS selector, or inside it | selector; optionally only on some pages |
| Link click | a click on a link, optionally only links whose address matches | target URL rule; optionally only on some pages |
| Form submission | a form submitted, optionally only forms matching a selector | selector; optionally only on some pages |
| Scroll depth | scrolling to a percentage of the page, once per page view (pages that fit the screen count as 100%) | percent (1–100); optionally only on some pages |
- Listeners run in the capture phase, before page handlers that stop events or navigate away, and flush with
sendBeaconsince clicks and submits often leave the page. - The event is the goal's event key, with
properties.goalset to the goal key. - An invalid selector never breaks the page. Check what fires with
?liftcanary_debug=1. - “Only on some pages” takes URL rules or a saved location. Location triggers don't apply to goals: they count on the location's pages.
Late conversions#
Some goals happen days after the visit: a free trial that turns into a paid subscription two weeks later, a quote that becomes an order. Results normally count what happens while an experiment runs, so a visitor who starts a trial on its last day would never count as paying. Give such a goal late conversions (up to 30 days, lagDays in the API): once an experiment ends, the goal keeps counting for that many days, for the visitors who were in it. Who is in the experiment still ends with it: a visitor who arrives afterwards never counts.
- An ended experiment's results can change until its late conversions are in; the report says until when. They are saved for good after that, plus the 30 days in which late-sent events still arrive.
- Set it to how long the conversion takes, such as your trial length. In the dashboard, the billing goals for paid subscriptions and revenue start at 14 days; stores' paid orders (ikas, WooCommerce) at 7, their store revenue and cancelled or refunded orders at 14 (bank transfers, cash on delivery and returns come later).
- While an experiment runs nothing changes: its results show the conversions that have arrived so far. A multi-armed bandit only sees those, so it suits goals that happen during the visit better.
- Funnels and guardrails count what happens while the experiment runs.
The goals page#
Project → Goals lists each goal with its events over the last 7 days and the experiments that use it, plus tracked events that have no goal yet, one click to add. Add LLM goals creates the latency, cost, tokens, errors and feedback goals used by AI configs.
API#
{
"key": "add_to_cart",
"name": "Add to cart",
"eventKey": "add_to_cart",
"type": "conversion",
"direction": "increase",
"trigger": { "kind": "click", "selector": "button.add-to-cart", "location": "product_pages" }
}keyrequiredkey | The goal ID. |
namerequiredstring | Shown in results. |
eventKeyrequiredstring | Event it counts (up to 128 characters). Billing goals: set from their event. |
descriptionstring | Optional. |
lagDaysinteger | Late conversions: days (0–30) the goal keeps counting after an experiment ends. Default 0. |
type"conversion" | "mean" | "ratio" | Default conversion. |
direction"increase" | "decrease" | Default increase. |
triggerobject | Default { "kind": "code" }. Otherwise pageview (pages and/or location), click (selector), link (target?), form (selector?) or scroll (percent); each with optional pages and location. When both are set, a page must satisfy both. { "kind": "billing", "event": "trial_started" | "subscribed" | "revenue" | "cancelled" } counts an event from the project's billing webhook (Stripe, Paddle or Chargebee), as billing.trial_started and so on; "order_paid" | "order_revenue" | "order_cancelled" one from its store's (ikas, WooCommerce), as store.order_paid, store.revenue and store.order_cancelled. Its event key, type and default direction come with the event, and only the webhook can send it. |