Metrickle

Events, people and properties

Last updated

Every SDK sends the same kinds of events in the same shape, so a goal, funnel or protected task means the same thing on the web, iOS, Android, Flutter and React Native. This page explains what’s recorded for you, what you add yourself, and how Metrickle ties events to one person. The examples use the web SDK; the iOS, Android and Flutter SDKs have the same calls.

Kinds of event

Each event has a type and a name.

TypeNameSent by
page$pageviewThe web SDK, on each page load and single-page navigation
screen$screenThe mobile SDKs, and screen() in React Native
trackYour own name, or one of Metrickle’s $ namestrack(), and the SDKs' automatic events
identify$identifyidentify()

Names that start with $ are Metrickle’s own. The SDKs refuse a custom event whose name starts with $.

Events recorded for you

You don’t need to send these. On the web, each group can be switched off with the SDK’s options.

EventPlatformsWhen
$pageviewWebA page loads, or the address changes in a single-page app
$screenMobileA screen is shown. Its name becomes the event’s path
$app_open, $app_backgroundMobileThe app starts or comes back to the foreground, and goes to the background
$rage_clickAllThree clicks or taps on the same spot within a second
$dead_click, $slow_click, $error_clickWebA click that did nothing, took more than a second to respond, or was followed by a script error
$u_turnAllSomeone went straight back to the previous page or screen within seconds. On the web, across full page loads too (not in cookieless mode)
$scroll_thrashWebSomeone scrolled up and down the page four times or more within 10 seconds, with a wheel, trackpad or touch
$form_error, $form_abandonWeb; $form_error on mobile through a helperA field failed validation, or someone started a form and left without sending it
$long_pauseWebSomeone paused for 30 seconds or more after starting on a page, then sent a form, pressed a data-mk-primary control, or left a form part-way
$web_vitalWebCore Web Vitals and other page speed measures
$outbound_clickWebA click on a link to another site
$errorWebAn uncaught script error

Surveys, feedback, heatmaps and study tasks add their own $ events, such as $survey_answered and $feedback, when you turn those features on.

What the automatic events feed

  • Friction signals feed Friction, including what each hotspot means.
  • $long_pause feeds doubt before deciding and cases. It isn’t a friction signal: a pause is doubt, not something broken.
  • $web_vital feeds Speed: each reading has a metric (LCP, INP, CLS, FCP or TTFB), a value in milliseconds (CLS times 1,000, so 100 is 0.1) and the browser’s rating. Slow loads are also a trait on Converters.
  • $outbound_click has the link’s href. Converters groups links out by the domain they go to.

What friction clicks record

$rage_click, $dead_click, $slow_click and $error_click carry the clicked element’s selector and visible text. The script tag (m.js, always the latest build) also sends the properties below; the npm package sends them from its first release after 0.2.0:

PropertyValuesWhat it tells Metrickle
affordancecontrol, pointer or noneWhether the element was a real control (a link, button or interactive role), only styled to look clickable (a pointer cursor), or plain content
inputkeyboard, mouse, touch or penWhat set it off. Dead, slow and error clicks already recorded it; rage clicks now do too
selectedtrue or falseRage clicks only: whether the clicks left text selected, which means someone was selecting text, not getting angry

These decide what a hotspot means, such as “Looks clickable but isn’t” or “Doesn’t work with a keyboard”. Rage clicks are recorded on the element people meant to click, such as the button rather than the icon inside it.

U-turns across page loads

On a site where each page is a full page load, the web SDK keeps the paths of the last two pages in the tab, and when each was opened, in session storage (mk_nav), so going straight back is noticed on the next page. It’s also checked when the back button restores a page from the browser’s cache. Paths only, never the query string or fragment, and the key goes when the tab closes. It’s never written in cookieless mode or for visitors who opted out; there, u-turns are seen within a single-page app only.

Up-and-down scrolling

$scroll_thrash has reversals (changes of direction, 4 or more), ms (from the first to the last) and input (wheel or touch). A change of direction counts only once the page has moved back by 30% of the window and at least 150 pixels. Keyboard scrolling, focus moving, screen readers, find in page and in-page links don’t count, and a pinch-zoomed page is skipped. At most once per page view.

Long pauses

$long_pause has ms (the pause), action (submit, primary or left), form (the form, as $form_abandon names it) and selector (the button or control pressed). The pause is the time between two actions on the same page, with the tab visible and no sound or video playing, so reading a page when it opens never counts. Pauses over 30 minutes aren’t recorded.

A form being sent is always a primary action. For one that isn’t in a form, such as a checkout button in a single-page app, add data-mk-primary:

<button data-mk-primary>Place order</button>

Metrickle leaves out pauses from sessions using a screen reader, keyboard navigation, zoom or large text, where taking longer is normal.

Your own events

Send an event for each step that matters to you and isn’t a page or screen on its own: a sign-up, a search, an item added to the basket.

metrickle.track("checkout_started", { items: 3, plan: "pro" });
  • Names are up to 128 characters. Pick one name per action and keep it stable: goals and funnels match on it.
  • Properties are a flat object of up to 64 keys. Keys are up to 128 characters.
  • Values are strings (up to 1,024 characters), finite numbers, true, false or null. Nested objects and arrays aren’t accepted.
  • Don’t put personal data such as email addresses or names in properties.

To add the same properties to every event, register them once:

metrickle.register({ app_theme: "dark" });

An event’s own properties win over registered ones with the same key.

People and sessions

Anonymous visitors

The SDK gives each browser or app install a random anonymous id and keeps it in local storage. A session ends after 30 minutes without activity.

In cookieless mode nothing is stored on the device. The server makes a visitor id from a hash that changes every day, and sessions are 30-minute periods of it. Returning visitors and retention then only count within one day. See privacy and cookieless tracking.

Signed-in people

Call identify() after someone signs in and reset() when they sign out:

metrickle.identify(user.id, { plan: user.plan }); // after sign-in
metrickle.reset();                                // on sign-out

From then on, Metrickle counts that person as one visitor: what they did before signing in, after it, and on every other device they sign in on. A server-side event sent with only their user id, such as a refund, lands on the same person.

  • Send an opaque id from your own database, not an email address.
  • Traits on identify() follow the same rules as properties. An email address in traits is never stored.
  • reset() forgets the user and starts a new anonymous id, so the next person on a shared device isn’t merged with the last.

Revenue

Put a numeric revenue property on the event where money changes hands:

metrickle.track("purchase", { revenue: 49, currency: "GBP" });
  • Only a property named revenue, on one of your own events, counts as revenue.
  • Metrickle doesn’t convert currencies you send yourself. Send every amount in the same currency.
  • To record a refund, send negative revenue for the same person. Refunds within 7 days of a completed task that add up to its value take that completion back, so task success counts what people keep. A smaller, partial refund keeps the completion and comes off revenue kept. If both the purchase and the refund carry the same order_id, the refund is matched to that order only. See protected tasks.
  • Don’t send revenue from both the client and a payment provider for the same purchase, or it’s counted twice.

Payments, renewals, refunds and cancellations can come straight from Stripe or RevenueCat instead, with no track() calls. See Revenue from Stripe and RevenueCat.

Cart value

To count what an abandoned attempt was worth, put a numeric value on the events that change what someone is about to buy:

metrickle.track("cart_updated", { value: 89.5, items: 3 });

value isn’t added to revenue on Overview, pages, sources or goals, so cart updates don’t inflate them.

How an attempt is valued

Money on tasks, cases, releases, Speed and Converters reads each event in this order:

  1. Revenue: the revenue property, or the amount from Stripe, RevenueCat or an event source’s order.
  2. Value: the value property, when there’s no revenue on that event.
  3. A value you set: for protected tasks and release verdicts only, the value set on the task or goal (a fixed amount, or a share of average order value), when completions carry too little value of their own.
  4. Nothing: that event adds no money.

A completed attempt takes the value of the event that completed it, so track("purchase", { value: 49 }) values the purchase even without revenue, and a task’s Revenue kept includes it. A case counts an abandoned attempt with nothing valued at what a completed attempt is worth on average. An abandoned attempt takes the last valued event inside it. Both must be numbers on your own events: a numeric string such as "49" is ignored, and a negative value is ignored (send a refund as negative revenue). If both are on one event, revenue wins.

Accessibility context

Each batch of events carries the accessibility settings the SDK can see on the device, so any funnel, task or journey can be split by them. You don’t send these yourself.

FlagMeans
screen_readerA screen reader is running
keyboardKeyboard navigation, or a hardware keyboard, Switch Control or Switch Access
reduced_motionReduce motion is on
reduced_transparencyReduce transparency is on
high_contrastIncreased contrast is on
forced_colorsForced colours (such as Windows high contrast)
inverted_colorsColours are inverted
grayscaleGreyscale is on
bold_textBold text is on
large_textText is larger than the default
zoomedThe page is zoomed in

Not every flag can be read on every platform. Events with none of them fall into the none group: people using no accessibility settings. See accessibility breakdowns.

Device context

Each batch also says where its events came from. The SDKs fill this in for you, and Metrickle keeps it on every event in the batch.

FieldExampleComes from
platformiosThe SDK
device_typemobileThe SDK, or the browser’s user agent on the web
osiOSThe SDK, or the browser’s user agent on the web
os_version17.4The device’s OS release, on the mobile SDKs
device_modeliPhone15,2The device’s model identifier, on the mobile SDKs
browserSafariThe browser’s user agent, on the web only
app_version4.12Your app’s version: the mobile SDKs send it, and the web npm package does when you set appVersion in init(). The script tag can’t set it
sdkmetrickle-ios@0.2.0The name and version of the SDK that sent the event
screen_w, screen_h390, 844The screen size in points or CSS pixels
localeen-GBThe device’s language and region
timezoneEurope/LondonThe device’s time zone

You can break down and filter reports by os_version and sdk, as well as by os, browser, device_type and app_version. In breakdowns and filters, an OS release is named with its OS, such as iOS 17.4 or Android 14, because a bare 14 could be either. Protected tasks also compare each OS release and each SDK version with the others, so an update that breaks one of them shows up on its own. Raw exports and the query API return the release as the device sent it, in os_version.

Feedback reports, and events Metrickle records for you from a payment provider or help desk, have no sdk.

Sending events without an SDK

Any platform that can make an HTTP request can send these events. See the HTTP ingest API for the exact format, or Segment and RudderStack if your events already go through one of them.