Skip to Content

Events

Automatic tracking and custom events

The core SDK automatically sends $pageview, $page_ping, $page_leave, and $outbound_link events. Errors from the error tracker show up as $exception events. Use track for your own events.

Automatic Tracking

EventWhen it fires
$pageviewWhen a page first becomes visible and on each client-side navigation
$page_pingWhen activity pauses, and while active after 15 and 45 seconds, then every 60
$page_leaveOnce when the visit ends: on navigation, when the page is closed, or on logout
$outbound_linkWhen a visitor clicks a link to another host, or a mailto: or tel: link
$exceptionWhen the error tracker reports an uncaught error or one you pass to reportError

Page views include the path, sanitized URL, referrer, page title, UTM parameters, and navigation type. A page that is closed or replaced before it becomes visible sends nothing.

Single-page navigation is detected through the History API, so pushState, replaceState, and back/forward navigation create page views automatically. Set trackHash: true for hash-based routers.

On client-side navigations, the $pageview is sent once the new page and its title have rendered. Events tracked in the meantime are sent after it, so they belong to the new page. Changing only the query string, such as a filter or page number, does not count as a new page view.

The navigation property on $pageview says how the visitor reached the page.

ValueMeaning
navigateA normal page load
reloadThe page was reloaded
back_forwardBack or forward to a page that loaded again
restoreBack or forward to a page restored from the back-forward cache
pushClient-side navigation with pushState
replaceClient-side navigation with replaceState
popBack or forward within a single-page app

Visit Duration

Each page view starts a visit. $page_ping and $page_leave events are cumulative checkpoints for that visit and share its visit_id with the page view.

PropertyDescription
visit_idLinks the checkpoint to its page view
time_on_pageMilliseconds the page was visible and focused during this visit
session_durationMilliseconds since the session started, including time spent away
scroll_depthHow far down the page the visitor scrolled, as a percentage

time_on_page pauses while the tab is hidden, the window is unfocused, or the page sits in the back-forward cache. Because checkpoints are cumulative, use the highest time_on_page per visit instead of summing them.

scroll_depth also only grows during a visit, so use its highest value too.

A session ends after 30 minutes of inactivity or 24 hours. A new session, a logout, or a switch between anonymous and granted consent starts a new visit, even on the same route.

Outbound link tracking is built in and always on. Left and middle clicks on links to a different host, and on mailto: and tel: links, send an $outbound_link event with the destination in the outbound_link property. The query string and hash are removed, so a prefilled email subject or body is never sent. Clicks whose default action was prevented are skipped, and a double click is only counted once.

Custom Events

Call track with a name and an optional object of JSON-serializable properties.

import { useTrack } from "@faststats/react";

const track = useTrack();
track("signup", { plan: "pro", source: "hero" });

The SDK trims names and ignores empty names.

Reserved Names

Names starting with $ are reserved for built-in events, including ones added later. track ignores them and logs a console warning once per name. Every other name is yours, including pageview or error, which show up as custom events separate from the built-in $pageview and $exception.

SDK versions before the $ prefix sent built-in events as pageview, page_ping, page_leave, outbound_link, and error. FastStats renames those as they arrive, so older versions keep working without an update. After upgrading, a track("pageview") call that the old SDK ignored is sent as a custom event.

Good Practices

Keep a small, stable set of event names and put changing details in properties.

track("checkout", { step: "cart" });
track("checkout", { step: "shipping" });
track("checkout", { step: "payment" });