Custom events (internally called "tags" in the wire format, but exposed to you as recordEvent) 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.
Recording an event#
final service = PictoService(recording.canvasRecorder);
service.recordEvent('checkoutTapped', data: {'sku': 'abc123', 'price': '19.99'});
service.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 on the replay viewer's scrub bar and event list, in their own color, distinct from environment noise (lifecycle transitions, metrics changes) and errors — they're application-level moments you chose to mark, not ambient signal. 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.