From 3138ae09f1558f08e72edbbe883725d1970e508c Mon Sep 17 00:00:00 2001 From: "snowplow-loop[bot]" Date: Thu, 23 Jul 2026 21:09:44 +0000 Subject: [PATCH 1/2] loop: implement documentation (loop/3a607af295a280da8c2adea3051ca267-documentation) --- .../initialization-options/index.md | 3 ++ .../web-trackers/tracking-events/index.md | 6 +++- .../tracking-events/page-views/index.md | 35 +++++++++++++++++++ 3 files changed, 43 insertions(+), 1 deletion(-) diff --git a/docs/sources/web-trackers/tracker-setup/initialization-options/index.md b/docs/sources/web-trackers/tracker-setup/initialization-options/index.md index 34aeb568b..0b055777b 100644 --- a/docs/sources/web-trackers/tracker-setup/initialization-options/index.md +++ b/docs/sources/web-trackers/tracker-setup/initialization-options/index.md @@ -104,6 +104,7 @@ The following table shows all the configuration parameters. These are **all opti | [`onRequestSuccess`](/docs/sources/web-trackers/configuring-how-events-sent/index.md#onrequestsuccess-callback) | Callback executed when a request succeeds (2xx status). | | `function` | | [`onRequestFailure`](/docs/sources/web-trackers/configuring-how-events-sent/index.md#onrequestfailure-callback) | Callback executed when a request fails (non-2xx status). | | `function` | | [`preservePageViewIdForUrl`](/docs/sources/web-trackers/tracking-events/page-views/index.md#change-id-behavior-for-spas) | Control when a new page view ID is generated based on URL changes. | `false` | `boolean` or `string` enum | +| [`preserveOriginalReferrer`](/docs/sources/web-trackers/tracking-events/page-views/index.md#preserve-the-original-referrer-in-spas) | Freeze the original external referrer for all subsequent page views in a single-page app. | `false` | `boolean` | | [`customFetch`](/docs/sources/web-trackers/configuring-how-events-sent/index.md#custom-event-store) | Override the default fetch function with a custom implementation. | | `function` | | [`eventStore`](/docs/sources/web-trackers/configuring-how-events-sent/index.md#custom-event-store) | Custom EventStore implementation for storing events before sending. | | `object` | | [`keepalive`](/docs/sources/web-trackers/configuring-how-events-sent/index.md#keepalive-option-for-collector-requests) | Allow requests to outlive the webpage. Enables requests to complete even if the page is closed. | `false` | `boolean` | @@ -171,6 +172,7 @@ snowplow('newTracker', 'sp', '{{collector_url_here}}', { onRequestSuccess: function(data) => { }, // Available in v3.18.1+ onRequestFailure: function(data) => { }, // Available in v3.18.1+ preservePageViewIdForUrl: false, + preserveOriginalReferrer: false, keepalive: false, // Introduced in v4 customFetch: undefined, // Introduced in v4 eventStore: undefined, // Introduced in v4 @@ -232,6 +234,7 @@ newTracker('sp', '{{collector_url_here}}', { onRequestSuccess: function(data) => { }, // Available in v3.18.1+ onRequestFailure: function(data) => { }, // Available in v3.18.1+ preservePageViewIdForUrl: false, + preserveOriginalReferrer: false, keepalive: false, // Introduced in v4 customFetch: undefined, // Introduced in v4 eventStore: undefined, // Introduced in v4 diff --git a/docs/sources/web-trackers/tracking-events/index.md b/docs/sources/web-trackers/tracking-events/index.md index 1c82b18a5..bd50632c9 100644 --- a/docs/sources/web-trackers/tracking-events/index.md +++ b/docs/sources/web-trackers/tracking-events/index.md @@ -291,7 +291,11 @@ On an SPA, the page URL might change without the page being reloaded. Whenever a To use `setCustomUrl` within an SPA, call it before all `trackPageView` calls. -If you want to ensure that the original referrer is preserved even though your page URL can change without the page being reloaded, use `setReferrerUrl` like this before sending any events: +If you want to ensure that the original referrer is preserved even though your page URL can change without the page being reloaded, you have two options: + +**Declarative (recommended):** set `preserveOriginalReferrer: true` in the [tracker configuration](/docs/sources/web-trackers/tracker-setup/initialization-options/index.md). The tracker automatically captures `document.referrer` at initialization and uses it as the referrer for all subsequent `trackPageView()` calls. + +**Imperative:** call `setReferrerUrl` with `document.referrer` before sending any events: diff --git a/docs/sources/web-trackers/tracking-events/page-views/index.md b/docs/sources/web-trackers/tracking-events/page-views/index.md index bcd5306c1..7614cbe92 100644 --- a/docs/sources/web-trackers/tracking-events/page-views/index.md +++ b/docs/sources/web-trackers/tracking-events/page-views/index.md @@ -134,6 +134,41 @@ tracker.preservePageViewIdForUrl('pathname'); +### Preserve the original referrer in SPAs + +In a single-page application, the referrer for each `trackPageView()` call is normally the previous internal URL. This means the original external referrer (for example, the search engine that brought the user to your site) is only visible on the first page view. + +Set `preserveOriginalReferrer: true` in the tracker configuration to freeze the original external referrer for all subsequent page views in the session. The tracker captures `document.referrer` at initialization and uses it as the referrer for every `trackPageView()` call, regardless of internal navigation. + +If `document.referrer` is empty at initialization (for example, when the user navigated directly to the site), this option has no effect and the default per-navigation referrer behavior applies. + + + + +```javascript +snowplow('newTracker', 'sp', 'collector.example.com', { + appId: 'my-app', + preserveOriginalReferrer: true +}); +``` + + + + +```javascript +import { newTracker } from '@snowplow/browser-tracker'; + +newTracker('sp', 'collector.example.com', { + appId: 'my-app', + preserveOriginalReferrer: true +}); +``` + + + + +If you also call [`setReferrerUrl()`](/docs/sources/web-trackers/tracking-events/index.md#custom-page-url-and-referrer-url) after initialization, the explicit value takes precedence over the preserved referrer. + ## Reset page activity on page view By default, tracking a page view using `trackPageView()`resets [activity tracking](/docs/sources/web-trackers/tracking-events/activity-page-pings/index.md). From 67179999c43d0e81f55b20f75ea17d0cb2d62bed Mon Sep 17 00:00:00 2001 From: Matus Tomlein Date: Mon, 27 Jul 2026 15:56:02 +0200 Subject: [PATCH 2/2] Add a note about version --- docs/sources/web-trackers/tracking-events/page-views/index.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/docs/sources/web-trackers/tracking-events/page-views/index.md b/docs/sources/web-trackers/tracking-events/page-views/index.md index 7614cbe92..8457cdf4b 100644 --- a/docs/sources/web-trackers/tracking-events/page-views/index.md +++ b/docs/sources/web-trackers/tracking-events/page-views/index.md @@ -136,6 +136,10 @@ tracker.preservePageViewIdForUrl('pathname'); ### Preserve the original referrer in SPAs +:::info +This feature is available since version 4.10 of the tracker. +::: + In a single-page application, the referrer for each `trackPageView()` call is normally the previous internal URL. This means the original external referrer (for example, the search engine that brought the user to your site) is only visible on the first page view. Set `preserveOriginalReferrer: true` in the tracker configuration to freeze the original external referrer for all subsequent page views in the session. The tracker captures `document.referrer` at initialization and uses it as the referrer for every `trackPageView()` call, regardless of internal navigation.