LiftCanary

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#

JavaScript
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))
  • value is a number: revenue, items, seconds. It's what mean and ratio goals add up.
  • properties are stored with the event for your own analysis; they don't affect results.
  • track is safe to call before the SDK is ready; events are queued, batched, retried and survive page reloads.

Goal types#

TypeMeasuresExample
conversionshare of exposed users with the event at least oncePurchase rate, signup rate
meansum of value per exposed user (users without the event count as 0)Revenue per visitor
ratiosum of value ÷ number of events: an average per eventLatency 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.

  1. 1Page visit: a visit to a matching page, here /checkout/success.
  2. 2Click: a click on an element matching a selector, here #continue.
  3. 3Form submission: a form submitted, here form.newsletter.
  4. 4Scroll depth: reaching a share of the page, once per page view.
TriggerCountsSettings
Page visita visit to a matching page, including single-page-app navigationpages (URL rules) or a saved location
Clicka click on an element matching a CSS selector, or inside itselector; optionally only on some pages
Link clicka click on a link, optionally only links whose address matchestarget URL rule; optionally only on some pages
Form submissiona form submitted, optionally only forms matching a selectorselector; optionally only on some pages
Scroll depthscrolling 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 sendBeacon since clicks and submits often leave the page.
  • The event is the goal's event key, with properties.goal set 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#

POST /v1/projects/web/goals
{
  "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" }
}
keyrequired
key
The goal ID.
namerequired
string
Shown in results.
eventKeyrequired
string
Event it counts (up to 128 characters). Billing goals: set from their event.
description
string
Optional.
lagDays
integer
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.
trigger
object
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.