Events
Automatic tracking and custom events
The core SDK automatically sends pageview, page_leave, and outbound_link
events. Use track for your own events.
Automatic Tracking
| Event | When it fires |
|---|---|
pageview | When a page first becomes visible and on each client-side navigation |
page_leave | Every 15 seconds while the page is active, and when the visit pauses or ends |
outbound_link | When a visitor clicks a link to another host |
Page views include the path, sanitized URL, referrer, page title, and UTM parameters. 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.
Visit Duration
Each page view starts a visit. page_leave events are cumulative checkpoints
for that visit and share its visit_id with the page view.
| Property | Description |
|---|---|
visit_id | Links the checkpoint to its page view |
time_on_page | Milliseconds the page was visible and focused during this visit |
session_duration | Milliseconds since the session started, including time spent away |
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.
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 Links
Outbound link tracking is built in and always on. Left and middle clicks on
http and https links to a different host send an outbound_link event with
the destination in the outbound_link property. The query string and hash are
stripped from the URL, 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" });<script setup lang="ts">
const { $faststats } = useNuxtApp();
$faststats.track("signup", { plan: "pro", source: "hero" });
</script>import { track } from "@faststats/web";
track("signup", { plan: "pro", source: "hero" });The SDK trims names and ignores empty names. It reserves pageview,
page_leave, error, and outbound_link for built-in events, so track
ignores those names.
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" });