Tracking script overview

The Pageviews tracking script is a lightweight JavaScript snippet that collects anonymous analytics data from your website visitors. It is designed to be fast, privacy-respecting, and simple to integrate.

How it works

When a visitor loads a page on your website, the tracking script sends a single event to Pageviews containing:

  • The page URL being viewed
  • The referrer (where the visitor came from)
  • The screen size (used to determine device type)
  • The browser and operating system
  • The visitor's country (derived from IP address, which is never stored)

What it does NOT collect

  • No cookies are set or read
  • No personal data (names, email addresses, etc.)
  • No IP addresses are stored
  • No cross-site tracking or fingerprinting

Script features

The tracking script includes built-in support for:

  • Engagement tracking — Measures active time on page and scroll depth automatically.
  • SPA navigation — Automatically detects client-side navigation via the History API.
  • Hash-based routing — Tracks hash changes for frameworks that use hash routing.
  • Back-forward cache — Detects browser cache restoration and counts it as a new pageview.
  • Outbound link tracking — Detects clicks on external links.
  • File download tracking — Tracks downloads of common file types (PDF, ZIP, etc.).
  • Form submission tracking — Tracks validated form submissions.
  • Scroll depth — Measures how far visitors scroll on each page (used for scroll goals).
  • Custom events — Send custom goal events with optional properties.
  • Visitor identification — Associate a custom identifier with visitors on the realtime dashboard.

Sending custom events

You can trigger custom events from your JavaScript code using the global pageviews function:

pageviews('track', 'My Event Name', { props: { plan: 'pro', value: '42' } });

This is useful for tracking button clicks, sign-ups, purchases, or any other user action. See the Custom event goals article for more details, and the Tracking snippet reference for the full API.