Tracking snippet reference - Documentation

This is a complete reference for the Pageviews tracking snippet — the script tag you add to your website. For the NPM module (recommended for SPAs), see the NPM module (@pageviews/tracker) article.

Basic snippet

<script src="https://pageviews.ai/{site_id}.js" async></script>

The async attribute ensures the script loads without blocking page rendering. The script is less than 1 KB — it will have no measurable impact on your page load speed.

Script attributes

data-api

Override the API endpoint where events are sent. Useful if you want to proxy tracking requests through your own domain to avoid ad blockers.

<script src="https://pageviews.ai/{site_id}.js" data-api="https://your-proxy.com/api/event" async></script>

Without this attribute, events are sent to the default Pageviews API endpoint derived from the script's origin.

JavaScript API

The tracking script exposes a global pageviews() function with two commands:

Track custom events

pageviews('track', 'Signup');

Track events with properties

pageviews('track', 'Purchase', { props: { plan: 'pro', price: '49' } });

All property values are coerced to strings before sending.

Track events with a URL override

pageviews('track', 'Virtual Pageview', { url: 'https://example.com/thank-you' });

Track events with a callback

pageviews('track', 'Add to Cart', { props: { product: 'widget' }, callback: function(result) { console.log('Sent', result.status); } });

Identify visitors

Associate a custom identifier with the current visitor for the realtime dashboard. This data is never persisted.

pageviews('identify', { userId: 'john@example.com' });

Automatic tracking

The following features are enabled automatically when the script loads — no additional configuration needed:

Feature	What it tracks	Event name
Pageviews	Page loads and client-side navigations.	`pageview`
Engagement	Active time on page (ms) and scroll depth (%).	`engagement`
SPA navigation	Intercepts `history.pushState()` and `popstate` events. Only fires when the pathname changes.	`pageview`
Hash routing	Tracks `hashchange` events for hash-based routers (when enabled in your dashboard).	`pageview`
Back-forward cache	Detects browser cache restoration via `pageshow` event.	`pageview`
Outbound links	Clicks on links to external domains.	`Outbound Link: Click`
File downloads	Clicks on links to downloadable files.	`File Download`
Form submissions	Form submit events (validated forms only).	`Form Submission`
Scroll depth	Maximum scroll percentage, used for scroll-triggered goals.	Sent with engagement

Tracked file extensions

File download tracking recognizes these extensions: pdf, xlsx, docx, txt, rtf, csv, exe, key, pps, ppt, pptx, 7z, pkg, rar, gz, zip, avi, mov, mp4, mpeg, wmv, midi, mp3, wav, wma, dmg.

Automatic exclusions

The tracker automatically ignores events in the following situations:

Localhost — No events are sent from localhost, 127.x.x.x, or [::1].
Bots and automation — Headless browsers (Selenium, Puppeteer, Cypress, PhantomJS, Nightmare) are detected and excluded.
Prerendered pages — Tracking is deferred until the page is actually viewed by a real user.

Opting out of tracking

Visitors can opt out of tracking by setting a flag in their browser's localStorage:

localStorage.setItem('pageviews_ignore', 'true');

To opt back in, remove the flag:

localStorage.removeItem('pageviews_ignore');

You can use this to exclude yourself from your own analytics. While opted out, all tracking calls are silently ignored.

Content Security Policy (CSP)

If your site uses a Content Security Policy, add the Pageviews script domain to your script-src directive:

script-src 'self' https://pageviews.ai;

If you use the data-api attribute to proxy requests, also add your proxy domain to the connect-src directive.