Referrers in single-page apps
In a single-page app, the History API changes the URL and view without a full page load, so the browser does not send a new Referer header for each route. The header reflects the original entry point, not the internal navigation, which means SPA analytics must capture referrer and entry data at first load and track route changes separately.
Why SPAs break naive referrer reads
A single-page app uses the History API (pushState/replaceState) to change the URL and render a new view without a full document load. Because there is no new HTTP navigation, the browser does not generate a new Referer header for each route — document.referrer keeps pointing at the page that originally loaded the app.
This means an analytics call fired on an internal route that reads document.referrer will see the original external entry point (or empty), not the previous in-app view. Treating that value as the referrer of the current screen double-counts or misattributes the source.
- History API route changes send no new Referer header
- document.referrer reflects the entry load, not the current view
- Internal navigations have no HTTP referrer at all
How to capture referrer correctly in an SPA
Capture the entry referrer once, at the first load, and persist it for the session so later in-app events can be attributed to the original source. For internal navigation, track the previous route in app state rather than relying on the Referer header, which will not change.
Keep campaign attribution on the entry URL: read UTM parameters at first load and store them, because client-side route changes can drop the query string from the visible URL. Server-side capture at the initial request is the most reliable point to record both the referrer host and the campaign parameters before the SPA takes over navigation.
How it appears in analytics and logs
In an SPA, the document Referer is set on the first real navigation and does not update when the app pushes a new route. Internal view changes carry no fresh Referer, so per-view referrer reads are stale unless the app records the entry referrer itself.
Diagnostic use case
Explain why an SPA's internal navigations do not generate new referrers, and capture the true entry referrer once at load instead of per route change.
What WebmasterID can help detect
WebmasterID captures the entry referrer server-side at first load and associates later in-app events with that original source, so SPA route changes do not blank out or duplicate the channel.
Common mistakes
- Reading document.referrer on every route and treating it as the current view's source.
- Expecting History API navigations to send a fresh Referer header.
- Losing UTM parameters when the SPA rewrites the URL after load.
- Attributing internal view changes to an external referrer.
Privacy and accuracy notes
SPA tracking should record the entry referrer host and route path only — not a per-user fingerprint. WebmasterID treats the entry referrer as a channel signal, never as visitor identity.
Related pages
- Referrer-Policy and missing referrers
Referrer-Policy is the web standard that controls how much of the referrer a browser sends with a request. Site owners set it via an HTTP header or a meta tag, and modern browsers default to a privacy-leaning value. Understanding the policy values explains why so many referrers arrive trimmed to the origin or missing entirely.
- Self-referral and internal referrers
A self-referral happens when your own domain shows up as the referrer for a visit, which usually means a session broke and restarted mid-journey. Common causes include cross-subdomain navigation, redirect chains, and third-party payment or auth hops that return to your site. The fix is to exclude your own domains so internal navigation is not counted as a new source.
- UTM vs referrer: which wins
When a visit carries both a referrer and UTM campaign parameters, most analytics treat the explicit UTM source as authoritative over the inferred referrer. That is usually correct: UTM tags describe intent you set deliberately, while a referrer is whatever the browser happened to send. Understanding the precedence prevents double-counting and mis-attribution.
- Event tracking
Record SPA route changes as events while keeping the entry referrer attributed correctly.
Sources and verification notes
- MDN — History APIpushState/replaceState change the URL without a navigation or new Referer.
- MDN — Document.referrer
Last reviewed 2026-06-24. Facts are checked against primary/official sources where available; uncertain specifics are marked “Data not yet verified” rather than guessed.