Events, people and properties
Last updated
Every SDK sends the same kinds of events in the same shape, so a goal, funnel or protected flow 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 |
$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 |
$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.
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. A refund within 7 days of a completed task takes that completion back, so task success counts what people keep. See protected flows.
- 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 is never counted as revenue.
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. See accessibility breakdowns.
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.