Custom events mark a specific, timestamped point in a session — "checkout tapped," "payment failed," "onboarding step 3" — the same way a breadcrumb works in tools like Sentry. Unlike Tags, which describe the whole session, a custom event is a point-in-time marker on the replay timeline. And unlike Screen Tracking, which records where the user was automatically from your app's routes, a custom event is something that happened, and only because you called for it.
Recording an event#
Picto.recordEvent('checkoutTapped', data: {'sku': 'abc123', 'price': '19.99'});
Picto.recordEvent('paymentFailed');
name identifies the kind of event; data is an optional flat map of string key/value pairs — omit it entirely for a plain marker with no extra data. Both are recorded directly into the binary stream (not the upload's
metadata map — no extra wiring needed at upload time, unlike tags), so they play back at the exact moment they were recorded.
Where they show up#
Custom events appear in two places in the replay viewer, both in their own color:
- The Events lane on the session timeline — their own row, directly below the Screen lane that screen tracking fills.
-
The
Tagsfilter chip in the event list. A custom event is recorded as a tag event, so that is the chip it arrives under.
They're application-level moments you chose to mark, not ambient signal — which is why they are not folded in with device changes (lifecycle transitions, metrics, brightness, focus) or errors. See Watching a Replay.
What not to put in data#
Same policy as everywhere else in the recording pipeline: never put user-entered text, PII, or anything sensitive into an event's
data map. Use identifiers and categories (a SKU, a step number, a boolean outcome) — not raw user input.