docs(web-trackers): document preserveOriginalReferrer tracker option

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

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:
 
 <Tabs groupId="platform" queryString>
   <TabItem value="js" label="JavaScript (tag)" default>

docs/sources/web-trackers/tracking-events/page-views/index.md

@@ -134,6 +134,45 @@ tracker.preservePageViewIdForUrl('pathname');
   </TabItem>
 </Tabs>
 
+### 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.
+
+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.
+
+<Tabs groupId="platform" queryString>
+  <TabItem value="js" label="JavaScript (tag)" default>
+
+```javascript
+snowplow('newTracker', 'sp', 'collector.example.com', {
+  appId: 'my-app',
+  preserveOriginalReferrer: true
+});
+```
+
+  </TabItem>
+  <TabItem value="browser" label="Browser (npm)">
+
+```javascript
+import { newTracker } from '@snowplow/browser-tracker';
+
+newTracker('sp', 'collector.example.com', {
+  appId: 'my-app',
+  preserveOriginalReferrer: true
+});
+```
+
+  </TabItem>
+</Tabs>
+
+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).