Track events

Pageviews, single-page apps, custom events, click autocapture, identify and the frustration signals Klickbee detects for you.

Once the tracker is installed, a lot is collected without any code: pageviews, scroll depth, JavaScript errors and, if you leave autocapture on, every meaningful click. This page covers what is automatic, what you can add yourself, and how to read the frustration signals.

Pageviews

A pageview is recorded with the full URL, the path, the referrer and the page title. How it is triggered depends on how you installed the tracker:

Install method	When a pageview is sent
Script tag	When the page loads, and automatically on every navigation in a single-page app.
npm package with the React provider	When the provider mounts, and every time the `pathname` you pass it changes.
npm package, plain client	Only when you call `tracking.pageview()`. Call it on each route change.

Single-page apps

With the script tag, the tracker wraps the browser's history functions and listens to the back and forward buttons. A new pageview is sent only when the path changes. A change of query string or #hash alone does not count as a new page.

When a visitor moves to another page, the tracker also sends the scroll data of the page being left and, if replay is on, starts a fresh snapshot for the new path. That is what lets heatmaps and replays show each page separately.

Custom events

Use a custom event to count something the tracker can't guess: a signup, a pricing toggle, a file download.

// Script tag
window.klickbee.track("signup_clicked", { plan: "pro" });

// npm package
tracking.track("signup_clicked", { plan: "pro" });

Rules to know:

The name is a string of up to 255 characters.
Properties are optional and must be flat: each value is a string, a number, a boolean or null. Nested objects and arrays aren't accepted.
Names that start with $ are reserved for the tracker's own events ($scroll, $deadclick, $ragescroll, $error, $experiment). Don't use them for yours.
Use stable, lower-case names such as signup_completed. Goals and funnels match names exactly, including upper and lower case.

You'll find your events in the dashboard in several places:

Overview: the Top events list.
Live events: a real-time feed of what is being captured.
Sessions: the event timeline of a session.
Funnels: as Event steps.
Goals: as goals of type Event.

You will see some $ events in Top events

The tracker's own events, such as $scroll, can appear in Top events, in Live events and in the Events total on Overview. That is expected.

Events can also carry a value and a currency for ad platforms: track purchase with { value: 49.9, currency: "EUR" }, and point a conversion mapping at those two properties. See Conversions.

Autocapture: clicks without code

With autocapture on, the tracker records clicks on buttons, links and other interactive elements, without any code on your side. For each click it keeps the element's CSS selector, its visible text or label, its link target and where on the page it was clicked.

Script tag: autocapture is on unless you set data-autocapture="false".
npm package: autocapture is off unless you set autocapture: true.

Autocapture feeds the click heatmap, click goals (see Goals), the Live events feed (type "autocapture") and three of the frustration signals below. Heatmaps also need replay on, because the page picture comes from a recording.

The element's visible or accessible text is captured, up to 255 characters. The data-kb-mask and data-kb-block markers described in Privacy & consent only apply to session replay, not to click autocapture. If a clickable element's text can contain something personal (a name, an email address), give it an aria-label without personal data, which is captured instead of the text, or turn autocapture off.

Identify your visitors

Call identify once you know who someone is, typically after login:

window.klickbee.identify("user_1234", { plan: "pro" });

From then on, their sessions carry that identifier: it is displayed on the session page and in the live feed, so you can find a given customer's sessions. Call reset() when they log out so the next person on the same browser isn't mixed with them.

Identifiers and traits are stored as-is

Whatever you pass to identify is saved exactly as sent. Use an internal user id rather than an email address, and keep sensitive data out of traits. Details in Privacy & consent.

Frustration signals

Klickbee detects moments where a visitor struggles, then shows them on the Sessions list, on the session page and on the replay timeline.

Signal	What it means	Needs
Rage click	3 or more clicks on the same element within 1.5 seconds.	Autocapture
Dead click	A click that led to nothing: no change on the page, no scroll and no URL change within 1 second.	Autocapture
Error click	A click followed within 1 second by a JavaScript error.	Autocapture, and `captureErrors` (on by default)
U-turn	The visitor goes from page A to B and is back on A in less than 5 seconds.	Pageviews
Rage scroll	At least 4 changes of scroll direction within 2 seconds.	Nothing extra

Each session gets a Frustration badge. Hover over it to see the breakdown, for example "3 rage · 1 dead · 1 U-turn". On the Sessions page, the Frustration only filter keeps only the sessions that contain at least one signal. See Sessions & heatmaps.

JavaScript errors

Unless you turn it off with captureErrors: false (npm package), the tracker records uncaught errors and unhandled promise rejections as $error events. To protect your quota and your data, a message is cut to 255 characters, repeated identical errors are skipped, and at most 10 are sent per page.

A/B test variants (npm package)

If you run a front-end test, tracking.experiment("pricing_test", "b") records which variant a visitor saw. The Experiments page, under Variant test, then compares the variants against a goal. This method isn't available on window.klickbee, so it needs the npm package.

Goals: turn pageviews, events and clicks into conversions.
Funnels, paths & retention
Troubleshooting

On this page