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.
| Type | Name | Sent by |
|---|---|---|
page | $pageview | The web SDK, on each page load and single-page navigation |
screen | $screen | The mobile SDKs, and screen() in React Native |
track | Your own name, or one of Metrickle’s $ names | track(), and the SDKs' automatic events |
identify | $identify | identify() |
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.
| Event | Platforms | When |
|---|---|---|
$pageview | Web | A page loads, or the address changes in a single-page app |
$screen | Mobile | A screen is shown. Its name becomes the event’s path |
$app_open, $app_background | Mobile | The app starts or comes back to the foreground, and goes to the background |
$rage_click | All | Three clicks or taps on the same spot within a second |
$dead_click, $slow_click, $error_click | Web | A click that did nothing, took more than a second to respond, or was followed by a script error |
$u_turn | All | Someone went straight back to the previous page or screen within seconds. On the web, across full page loads too (not in cookieless mode) |
$scroll_thrash | Web | Someone scrolled up and down the page four times or more within 10 seconds, with a wheel, trackpad or touch |
$form_error, $form_abandon | Web; $form_error on mobile through a helper | A field failed validation, or someone started a form and left without sending it |
$long_pause | Web | Someone 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_vital | Web | Core Web Vitals and other page speed measures |
$outbound_click | Web | A click on a link to another site |
$error | Web | An 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_pausefeeds doubt before deciding and cases. It isn’t a friction signal: a pause is doubt, not something broken.$web_vitalfeeds Speed: each reading has ametric(LCP,INP,CLS,FCPorTTFB), avaluein milliseconds (CLS times 1,000, so100is 0.1) and the browser’srating. Slow loads are also a trait on Converters.$outbound_clickhas the link’shref. 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:
| Property | Values | What it tells Metrickle |
|---|---|---|
affordance | control, pointer or none | Whether the element was a real control (a link, button or interactive role), only styled to look clickable (a pointer cursor), or plain content |
input | keyboard, mouse, touch or pen | What set it off. Dead, slow and error clicks already recorded it; rage clicks now do too |
selected | true or false | Rage 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,falseornull. 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:
- Revenue: the
revenueproperty, or the amount from Stripe, RevenueCat or an event source’s order. - Value: the
valueproperty, when there’s no revenue on that event. - 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.
- 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.
| Flag | Means |
|---|---|
screen_reader | A screen reader is running |
keyboard | Keyboard navigation, or a hardware keyboard, Switch Control or Switch Access |
reduced_motion | Reduce motion is on |
reduced_transparency | Reduce transparency is on |
high_contrast | Increased contrast is on |
forced_colors | Forced colours (such as Windows high contrast) |
inverted_colors | Colours are inverted |
grayscale | Greyscale is on |
bold_text | Bold text is on |
large_text | Text is larger than the default |
zoomed | The 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.
| Field | Example | Comes from |
|---|---|---|
platform | ios | The SDK |
device_type | mobile | The SDK, or the browser’s user agent on the web |
os | iOS | The SDK, or the browser’s user agent on the web |
os_version | 17.4 | The device’s OS release, on the mobile SDKs |
device_model | iPhone15,2 | The device’s model identifier, on the mobile SDKs |
browser | Safari | The browser’s user agent, on the web only |
app_version | 4.12 | Your 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 |
sdk | metrickle-ios@0.2.0 | The name and version of the SDK that sent the event |
screen_w, screen_h | 390, 844 | The screen size in points or CSS pixels |
locale | en-GB | The device’s language and region |
timezone | Europe/London | The 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.