diff --git a/docs/pipeline/enrichments/available-enrichments/cross-navigation-enrichment/index.md b/docs/pipeline/enrichments/available-enrichments/cross-navigation-enrichment/index.md
index 96df214a37..bd3f323d4f 100644
--- a/docs/pipeline/enrichments/available-enrichments/cross-navigation-enrichment/index.md
+++ b/docs/pipeline/enrichments/available-enrichments/cross-navigation-enrichment/index.md
@@ -1,22 +1,30 @@
---
-title: "Cross Navigation Enrichment"
+title: "Cross-navigation enrichment"
sidebar_position: 5
-sidebar_label: Cross Navigation
+sidebar_label: Cross-navigation
---
-This enrichment parses the extended cross navigation format in `_sp` querystring parameter and attaches the `cross_navigation` context to an event.
+This enrichment parses the extended cross-navigation format in the `_sp` querystring parameter, and attaches a `cross_navigation` entity to an event.
-The `_sp` parameter can be attached by our Web ([see cross-domain tracking](/docs/sources/trackers/javascript-trackers/web-tracker/cross-domain-tracking/index.md)) and [mobile trackers](/docs/sources/trackers/mobile-trackers/tracking-events/session-tracking/index.md#decorating-outgoing-links-using-cross-navigation-tracking) and contains user, session and app identifiers (e.g., domain user and session IDs, business user ID, source app ID). The information to include in the parameters is configurable in the trackers. This is useful for tracking the movement of users across different apps and platforms.
+To add the `_sp` querystring, configure cross-domain tracking in the [web](/docs/sources/trackers/javascript-trackers/web-tracker/cross-domain-tracking/index.md) or [mobile trackers](/docs/sources/trackers/mobile-trackers/tracking-events/session-tracking/index.md#decorating-outgoing-links-using-cross-navigation-tracking). The querystring contains user, session, and app identifiers, for example domain user and session IDs, business user ID, or source application ID. This is useful for tracking the movement of users across different apps and platforms. The information to include in the parameters is configurable in the trackers.
-The extended cross navigation format can be described by `_sp={domainUserId}.{timestamp}.{sessionId}.{subjectUserId}.{sourceId}.{platform}.{reason}`
+:::note Base64 encoding
+This enrichment expects the events to be base64-encoded. Configure this in the trackers.
+:::
-If this enrichment isn't enabled, Enrich parses `_sp` querystring parameter according to the old format, `_sp={domainUserId}.{timestamp}`
+The extended cross-navigation format is `_sp={domainUserId}.{timestamp}.{sessionId}.{subjectUserId}.{sourceId}.{platform}.{reason}`.
+
+If this enrichment isn't enabled, Enrich parses the `_sp` querystring parameter according to the short format `_sp={domainUserId}.{timestamp}`
## Configuration
- [Schema](https://github.com/snowplow/iglu-central/blob/master/schemas/com.snowplowanalytics.snowplow.enrichments/cross_navigation_config/jsonschema/1-0-0)
- [Example](https://github.com/snowplow/enrich/blob/master/config/enrichments/cross_navigation_config.json)
+```json reference
+https://github.com/snowplow/enrich/blob/master/config/enrichments/cross_navigation_config.json
+```
+
```mdx-code-block
import TestingWithMicro from "@site/docs/reusable/test-enrichment-with-micro/_index.md"
@@ -28,10 +36,10 @@ import TestingWithMicro from "@site/docs/reusable/test-enrichment-with-micro/_in
This enrichment extracts `_sp` querystring parameter from the following inputs:
- The `page_url` field from the Snowplow event
-- The referer uri extracted from corresponding HTTP header in the raw event
+- The `referer` URI extracted from corresponding HTTP header in the raw event
## Output
-This enrichment adds a new derived context to the enriched event with [this schema](https://github.com/snowplow/iglu-central/blob/master/schemas/com.snowplowanalytics.snowplow/cross_navigation/jsonschema/1-0-0).
+This enrichment adds a new derived entity to the enriched event based on [this schema](https://github.com/snowplow/iglu-central/blob/master/schemas/com.snowplowanalytics.snowplow/cross_navigation/jsonschema/1-0-0).
Also, it continues to populate `refr_domain_userid` and `refr_dvce_tstamp` enriched event fields as before.
diff --git a/docs/sources/trackers/javascript-trackers/web-tracker/cross-domain-tracking/index.md b/docs/sources/trackers/javascript-trackers/web-tracker/cross-domain-tracking/index.md
index 9cb27363fc..4618c01527 100644
--- a/docs/sources/trackers/javascript-trackers/web-tracker/cross-domain-tracking/index.md
+++ b/docs/sources/trackers/javascript-trackers/web-tracker/cross-domain-tracking/index.md
@@ -4,23 +4,351 @@ date: "2022-08-30"
sidebar_position: 2850
---
-# Cross-domain tracking
-
```mdx-code-block
import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';
-import CrossDomain from "@site/docs/reusable/javascript-tracker-cross-domain/_index.md"
```
+The JavaScript tracker can add an additional parameter named `_sp` to the querystring of outbound links. This process is called "link decoration".
+
+Configure cross-domain tracking using the `useExtendedCrossDomainLinker` or `crossDomainLinker` fields of the [configuration object](/docs/sources/trackers/javascript-trackers/web-tracker/tracker-setup/initialization-options/index.md). Choose between extended or short format for the `_sp` querystring parameter:
+
+* Short format: choose which links to decorate with the core parameters only
+* Extended format: the querystring can include more parameters, but the tracker will decorate all cross-domain links
+
+If you set both configuration options, the tracker will use the extended format.
+
+You can include the following properties in the `_sp` querystring:
+
+| Property | Description | Extended | Short |
+| --------------- | ---------------------------------------------- | -------- | ----- |
+| `domainUserId` | Current tracker-generated UUID user identifier | ✅ | ✅ |
+| `timestamp` | Current epoch timestamp, ms precision | ✅ | ✅ |
+| `sessionId` | Current session UUID identifier | ✅ | |
+| `subjectUserId` | Custom business user identifier | ✅ | |
+| `sourceId` | Application identifier | ✅ | |
+| `platform` | Platform of the current device | ✅ | |
+| `reason` | Link text or extra information | ✅ | |
+
+For example,
+
+```
+appSchema://path/to/page?_sp=domainUserId.timestamp.sessionId.subjectUserId.sourceId.platform.reason
+```
+
+Link decoration makes these values visible in the `url` field of events sent by the JavaScript tracker on the destination page. The enrichment process will use them to populate the `refr_domain_userid` and `refr_dvce_tstamp` fields for all events fired on the destination page, where the URL includes the `_sp` parameter.
+
+The querystring is added only to the events on the destination page: it doesn't persist throughout the user's session.
+
+:::tip
+
+If you enable link decoration, aim for at least one event to be tracked on the page. The tracker writes the `domain_userid` to a cookie when it tracks an event. If the cookie doesn't exist when the user leaves the page, the tracker will generate a new ID for them when they return, rather than keeping the old ID. This can make user stitching difficult.
+
+:::
+
+## Extended format
+
+The extended `_sp` value always includes `domainUserId` and `timestamp`. The other properties are configurable using the `ExtendedCrossDomainLinkerAttributes` object.
+
+By default, `reason` will be the link text from a cross-domain link.
+
+To decorate links with the full extended format:
+
+<Tabs groupId="platform" queryString>
+ <TabItem value="js" label="JavaScript (tag)" default>
+
+```javascript
+snowplow('newTracker', 'namespace', '{{collector_url_here}}', {
+ appId: 'my-app-id',
+ appVersion: '0.1.0',
+ cookieSameSite: 'Lax',
+ useExtendedCrossDomainLinker: true,
+});
+```
+
+ </TabItem>
+ <TabItem value="browser" label="Browser (npm)">
+
+```javascript
+newTracker('namespace', '{{collector_url_here}}', {
+ appId: 'my-app-id',
+ appVersion: '0.1.0',
+ cookieSameSite: 'Lax',
+ useExtendedCrossDomainLinker: true,
+});
+```
+
+ </TabItem>
+</Tabs>
+
+To include specific properties:
+
+<Tabs groupId="platform" queryString>
+ <TabItem value="js" label="JavaScript (tag)" default>
+
+```javascript
+snowplow('newTracker', 'namespace', '{{collector_url_here}}', {
+ appId: 'my-app-id',
+ appVersion: '0.1.0',
+ cookieSameSite: 'Lax',
+ useExtendedCrossDomainLinker: {
+ userId: true;
+ sessionId: true;
+ sourceId: true;
+ sourcePlatform: true;
+ reason: true; // can also be a callback
+ },
+});
+```
+
+ </TabItem>
+ <TabItem value="browser" label="Browser (npm)">
+
+```javascript
+newTracker('namespace', '{{collector_url_here}}', {
+ appId: 'my-app-id',
+ appVersion: '0.1.0',
+ cookieSameSite: 'Lax',
+ useExtendedCrossDomainLinker: {
+ userId: true;
+ sessionId: true;
+ sourceId: true;
+ sourcePlatform: true;
+ reason: true; // can also be a callback
+ },
+});
+```
+
+ </TabItem>
+</Tabs>
+
+Provide a callback to `reason` in the form `((evt: Event) => string)` to add custom information to the querystring.
+
+
+## Short format
+
+Provide a callback for the `crossDomainLinker` option to configure which links to decorate with the short `_sp` format. It should be a function taking one argument, the link element, that returns `true` if the tracker should decorate the link element and `false` otherwise.
+
+### Decorate some links
+
+For example, this function would only decorate those links whose destination is `http://acme.de/` or whose HTML ID is `crossDomainLink`:
+
+<Tabs groupId="platform" queryString>
+ <TabItem value="js" label="JavaScript (tag)" default>
+
+```javascript
+snowplow('newTracker', 'namespace', '{{collector_url_here}}', {
+ appId: 'my-app-id',
+ appVersion: '0.1.0',
+ cookieSameSite: 'Lax',
+ crossDomainLinker: function (linkElement) {
+ return (linkElement.href === 'http://acme.de' || linkElement.id === 'crossDomainLink');
+ }
+});
+```
+
+ </TabItem>
+ <TabItem value="browser" label="Browser (npm)">
+
+```javascript
+newTracker('namespace', '{{collector_url_here}}', {
+ appId: 'my-app-id',
+ appVersion: '0.1.0',
+ cookieSameSite: 'Lax',
+ crossDomainLinker: function (linkElement) {
+ return (linkElement.href === 'http://acme.de' || linkElement.id === 'crossDomainLink');
+ }
+});
+```
+
+ </TabItem>
+</Tabs>
+
+If you want to decorate every link to the domain `github.com`:
+
+```javascript
+{
+ crossDomainLinker: function (linkElement) {
+ return /^https:\/\/github\.com/.test(linkElement.href);
+ }
+}
+```
+
+You can also call the `crossDomainLinker` function directly:
+
<Tabs groupId="platform" queryString>
<TabItem value="js" label="JavaScript (tag)" default>
-<CrossDomain lang="javascript" />
+```javascript
+snowplow('crossDomainLinker', function(linkElement) {
+ return (linkElement.href === 'http://acme.de' || linkElement.id === 'crossDomainLink');
+});
+```
</TabItem>
<TabItem value="browser" label="Browser (npm)">
-<CrossDomain lang="browser" />
+```javascript
+crossDomainLinker(function(linkElement) {
+ return (linkElement.href === 'http://acme.de' || linkElement.id === 'crossDomainLink');
+});
+```
</TabItem>
</Tabs>
+
+
+### Decorate all links
+
+To decorate every link, regardless of its destination:
+
+```javascript
+{
+ crossDomainLinker: function (linkElement) {
+ return true;
+ }
+}
+```
+
+This will decorate "links" that are actually just JavaScript actions (with an `href` of `"javascript:void(0)"`), or links to email addresses or telephone numbers (`mailto:` or `tel:` schemes). To exclude these links, check them explicitly:
+
+<Tabs groupId="platform" queryString>
+ <TabItem value="js" label="JavaScript (tag)" default>
+
+```javascript
+snowplow('crossDomainLinker', function(linkElement) {
+ return linkElement.href.indexOf('javascript:') < 0;
+});
+```
+
+ </TabItem>
+ <TabItem value="browser" label="Browser (npm)">
+
+```javascript
+crossDomainLinker(function(linkElement) {
+ return linkElement.href.indexOf('javascript:') < 0;
+});
+```
+
+ </TabItem>
+</Tabs>
+
+Alternatively, only count links that parse as web URLs by checking the link's [`hostname`](https://developer.mozilla.org/en-US/docs/Web/API/HTMLAnchorElement/hostname). This should automatically exclude links that don't lead simply to other web pages.
+
+<Tabs groupId="platform" queryString>
+ <TabItem value="js" label="JavaScript (tag)" default>
+
+```javascript
+snowplow('crossDomainLinker', function(linkElement) {
+ return linkElement.hostname !== "";
+});
+```
+
+ </TabItem>
+ <TabItem value="browser" label="Browser (npm)">
+
+```javascript
+crossDomainLinker(function(linkElement) {
+ return linkElement.hostname !== "";
+});
+```
+
+ </TabItem>
+</Tabs>
+
+
+### Opt-in and opt-out
+
+Some of the examples will also decorate any links to the same site the user is currently on.
+
+We recommend explicitly allowing the list of domains you want to decorate. Only decorate links that are on a different domain to the current page.
+
+```javascript
+{
+ crossDomainLinker: function (linkElement) {
+ return linkElement.hostname !== location.hostname;
+ }
+}
+```
+
+If you have a shared configuration deployed across multiple sites, you may want to combine the approaches:
+
+```javascript
+{
+ crossDomainLinker: function (linkElement) {
+ var networkSites = [
+ "mysite.com",
+ "sistersite.com"
+ ];
+ return linkElement.hostname !== location.hostname && networkSites.indexOf(linkElement.hostname) > -1;
+ }
+}
+```
+
+Link decoration will only occur when links are to different sites within the list.
+
+### Update event listeners
+
+When the tracker loads it doesn't immediately decorate links. Instead, it adds event listeners to links which decorate them when a user clicks on them or navigates to them using the keyboard. This ensures that the timestamp added to the querystring is fresh.
+
+If further links get added to the page after the tracker has loaded, you can use the tracker's `crossDomainLinker` method to add listeners again. Listeners won't be added to links which already have them.
+
+<Tabs groupId="platform" queryString>
+ <TabItem value="js" label="JavaScript (tag)" default>
+
+```javascript
+snowplow('crossDomainLinker', function (linkElement) {
+ return (linkElement.href === 'http://acme.de' || linkElement.id === 'crossDomainLink');
+});
+```
+
+ </TabItem>
+ <TabItem value="browser" label="Browser (npm)">
+
+```javascript
+crossDomainLinker(function (linkElement) {
+ return (linkElement.href === 'http://acme.de' || linkElement.id === 'crossDomainLink');
+});
+```
+
+ </TabItem>
+</Tabs>
+
+## User IDs and shared pages
+
+If a user clicks a cross-site link, and the tracker decorates the URL with their `domain_userid`, and then they share that URL, other users will also have the parameters when they visit the shared page. This could cause problems if you are using `domain_userid` as a user identifier.
+
+You can choose to hide the parameter after the first event, e.g. page view, fires on the destination page. Because enrichment populates dedicated fields with the parameter, you won't need additional modeling to stitch the IDs. If the user copies the URL after the tracking code has fired, it may not include the `_sp` parameter and get copied to other users they share it with.
+
+You can do this using the [History API](https://developer.mozilla.org/en-US/docs/Web/API/History/replaceState).
+
+<Tabs groupId="platform" queryString>
+ <TabItem value="js" label="JavaScript (tag)" default>
+
+The URL-updating code runs in a [callback](/docs/sources/trackers/javascript-trackers/web-tracker/tracking-events/index.md#getting-user-id-once-set) to ensure it doesn't run before the page view event can capture the original URL.
+
+```javascript
+snowplow('trackPageView'); // page URL is https://example.com/?example=123&_sp=6de9024e-17b9-4026-bd4d-efec50ae84cb.1680681134458
+snowplow(function(){
+ if (/[?&]_sp=/.test(window.location.href)) {
+ history.replaceState(history.state, "", window.location.replace(/&?_sp=[^&]+/, "")); // page URL is now https://example.com/?example=123
+ }
+});
+```
+
+ </TabItem>
+ <TabItem value="browser" label="Browser (npm)">
+
+```javascript
+trackPageView(); // page URL is https://example.com/?example=123&_sp=6de9024e-17b9-4026-bd4d-efec50ae84cb.1680681134458
+if (/[?&]_sp=/.test(window.location.href)) {
+ history.replaceState(history.state, "", window.location.replace(/&?_sp=[^&]+/, "")); // page URL is now https://example.com/?example=123
+}
+```
+
+ </TabItem>
+</Tabs>
+
+This approach can work with other parameters, e.g. `utm_source`, but it's not recommended unless you are sure other systems have also already captured the parameter values.
+
+Some systems may consider the URL update a single page application page change, and automatically fire additional page view events with this implementation. Test this technique to ensure compatibility with your existing vendors.
diff --git a/docs/sources/trackers/javascript-trackers/web-tracker/tracker-setup/initialization-options/index.md b/docs/sources/trackers/javascript-trackers/web-tracker/tracker-setup/initialization-options/index.md
index 0e0dac6a3c..fe94814b13 100644
--- a/docs/sources/trackers/javascript-trackers/web-tracker/tracker-setup/initialization-options/index.md
+++ b/docs/sources/trackers/javascript-trackers/web-tracker/tracker-setup/initialization-options/index.md
@@ -12,10 +12,10 @@ import ReleaseBadge from '@site/docs/reusable/javascript-tracker-release-badge-v
<ReleaseBadge/>
```
-Tracker initialization is started by calling the `"newTracker"` function and takes three arguments:
+Initialize the tracker by calling the `"newTracker"` function. It takes three arguments:
-1. The tracker namespace (`sp` in the below example)
-2. The collector endpoint
+1. The tracker namespace
+2. The Collector endpoint
3. An optional configuration object containing other settings
Here is a simple example of how to initialise a tracker, setting a few configuration options:
@@ -24,6 +24,7 @@ Here is a simple example of how to initialise a tracker, setting a few configura
<TabItem value="js" label="JavaScript (tag)" default>
```javascript
+// The tracker namespace is 'sp' in this example
snowplow('newTracker', 'sp', '{{collector_url_here}}', {
appId: 'my-app-id',
appVersion: '0.1.0',
@@ -39,6 +40,7 @@ snowplow('newTracker', 'sp', '{{collector_url_here}}', {
<TabItem value="browser" label="Browser (npm)">
```javascript
+// The tracker namespace is 'sp' in this example
newTracker('sp', '{{collector_url_here}}', {
appId: 'my-app-id',
appVersion: '0.1.0',
@@ -53,54 +55,55 @@ newTracker('sp', '{{collector_url_here}}', {
</TabItem>
</Tabs>
-The tracker will be named `sp` (tracker namespace) and will send events to the a collector url you specify by replacing `{{collector_url_here}}`. The final argument is the configuration object. Here it is just used to set the app ID and the common webPage context for each event. Each event the tracker sends will have an app ID field set to “my-app-id”.
+The tracker will send events to the Collector URL you specify by replacing `{{collector_url_here}}`. The final argument is the configuration object. Here it's used to set the app ID and the webPage entity for each event. Each event the tracker sends will have an `app_id` field set to `my-app-id`.
-If `newTracker` is called multiple times with the same namespace, only the first call is taken into account.
+If your code calls `newTracker` multiple times with the same namespace, only the first call is taken into account.
:::tip For Single Page Apps
Initialize one tracker per initial page load.
:::
-The following table shows all the various configuration parameters. Note that these are all optional. In fact, you aren’t required to provide any configuration object at all.
-
-| Property | Description | Default (if applicable) | Type |
-|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------|-------------------------|---------------|
-| [`appId`](/docs/sources/trackers/javascript-trackers/web-tracker/tracking-events/index.md#setting-application-id) | Set the application ID. | | `string` |
-| [`appVersion`](/docs/sources/trackers/javascript-trackers/web-tracker/tracking-events/index.md#setting-application-version) | Set the application version. | | `string` |
-| [`platform`](/docs/sources/trackers/javascript-trackers/web-tracker/tracking-events/index.md#setting-application-platform) | Set the application platform. | "web" | `string` enum |
-| [`cookieDomain`](/docs/sources/trackers/javascript-trackers/web-tracker/cookies-and-local-storage/configuring-cookies/index.md#cookie-domain) | Set the cookie domain. | | |
-| [`discoverRootDomain`](/docs/sources/trackers/javascript-trackers/web-tracker/cookies-and-local-storage/configuring-cookies/index.md#cookie-domain) | Automatic discovery and setting of the root domain, to facilitate tracking over multiple subdomains. | true | `boolean` |
-| [`cookieName`](/docs/sources/trackers/javascript-trackers/web-tracker/cookies-and-local-storage/configuring-cookies/index.md#cookie-name) | Set the cookie name. | | `string` |
-| [`cookieSameSite`](/docs/sources/trackers/javascript-trackers/web-tracker/cookies-and-local-storage/configuring-cookies/index.md#cookie-samesite-and-secure-attributes) | Set the cookie samesite attribute. | null | `string` enum |
-| [`cookieSecure`](/docs/sources/trackers/javascript-trackers/web-tracker/cookies-and-local-storage/configuring-cookies/index.md#cookie-samesite-and-secure-attributes) | Set the cookie secure attribute. | true | `boolean` |
-| [`encodeBase64`](/docs/sources/trackers/javascript-trackers/web-tracker/configuring-how-events-sent/index.md#base64-encoding) | Enable Base64 encoding for JSONs (context entities and custom self-describing events). | true for GET, false for POST requests | `boolean` |
-| [`respectDoNotTrack`](/docs/sources/trackers/javascript-trackers/web-tracker/anonymous-tracking/index.md#respecting-do-not-track) | Choose to respect browser Do Not Track option. | false | `boolean` |
-| [`eventMethod`](/docs/sources/trackers/javascript-trackers/web-tracker/configuring-how-events-sent/index.md#network-protocol-and-method) | Choose to send events by GET, POST. | `post` | `string` enum |
-| [`bufferSize`](/docs/sources/trackers/javascript-trackers/web-tracker/configuring-how-events-sent/index.md#number-of-events-per-request) | How many events to send in one request. | 1 | `int` |
-| [`maxPostBytes`](/docs/sources/trackers/javascript-trackers/web-tracker/configuring-how-events-sent/index.md#maximum-payload-size) | Set a limit for the size of one request. | 40000 | `int` |
-| [`maxGetBytes`](/docs/sources/trackers/javascript-trackers/web-tracker/configuring-how-events-sent/index.md#maximum-payload-size) | Set a limit for the size of one request. | | `int` |
-| [`postPath`](/docs/sources/trackers/javascript-trackers/web-tracker/configuring-how-events-sent/index.md#custom-post-path) | Change the collector POST path. | | `string` |
-| [`crossDomainLinker`](/docs/sources/trackers/javascript-trackers/web-tracker/cross-domain-tracking/index.md) | Decorate links for cross-domain tracking. | | `function` |
-| [`cookieLifetime`](/docs/sources/trackers/javascript-trackers/web-tracker/cookies-and-local-storage/configuring-cookies/index.md#cookie-lifetime-and-duration) | Set the cookie lifetime. | 63072000 s (2 years) | `int` |
-| [`stateStorageStrategy`](/docs/sources/trackers/javascript-trackers/web-tracker/cookies-and-local-storage/configuring-cookies/index.md#storage-strategy) | How to store tracker state. | `cookieAndLocalStorage` | `string` enum |
-| [`maxLocalStorageQueueSize`](/docs/sources/trackers/javascript-trackers/web-tracker/cookies-and-local-storage/configuring-cookies/index.md#local-storage-queue-size) | How many events to queue in local storage when they are failing to send. | 1000 | `int` |
-| [`resetActivityTrackingOnPageView`](/docs/sources/trackers/javascript-trackers/web-tracker/tracking-events/activity-page-pings/index.md#reset-page-ping-on-page-view) | Choose to reset page ping timers when a page view is tracked. | true | `boolean` |
-| [`connectionTimeout`](/docs/sources/trackers/javascript-trackers/web-tracker/configuring-how-events-sent/index.md#connection-timeout) | Set request connection timeout. | 5000 ms | `int` |
-| [`anonymousTracking`](/docs/sources/trackers/javascript-trackers/web-tracker/anonymous-tracking/index.md) | Do not track user identifiers. | false | `boolean` |
-| [`customHeaders`](/docs/sources/trackers/javascript-trackers/web-tracker/configuring-how-events-sent/index.md#custom-request-headers) | Add custom headers to requests. | | `object` |
-| [`credentials`](/docs/sources/trackers/javascript-trackers/web-tracker/configuring-how-events-sent/index.md#disabling-sending-credentials-with-requests) | Choose whether to include cookies in certain collector requests. | `include` | `string` enum |
-| [`contexts`](/docs/sources/trackers/javascript-trackers/web-tracker/tracking-events/index.md#auto-tracked-entities) | Configure context entities to add to all events. | various | `object` |
-| [`retryStatusCodes`](/docs/sources/trackers/javascript-trackers/web-tracker/configuring-how-events-sent/index.md#custom-retry-http-codes) | Set HTTP response codes to retry requests on. | | `[int]` |
-| [`dontRetryStatusCodes`](/docs/sources/trackers/javascript-trackers/web-tracker/configuring-how-events-sent/index.md#custom-retry-http-codes) | Set HTTP response codes not to retry requests on. | | `[int]` |
-| [`retryFailedRequests`](/docs/sources/trackers/javascript-trackers/web-tracker/configuring-how-events-sent/index.md#retries) | Choose to retry failed requests or not. | true | `boolean` |
-| [`onSessionUpdateCallback`](/docs/sources/trackers/javascript-trackers/web-tracker/tracking-events/session/index.md#on-session-update-callback) | A callback to run every time the session updates. | | `function` |
-| [`onRequestSuccess`](/docs/sources/trackers/javascript-trackers/web-tracker/configuring-how-events-sent/index.md#onrequestsuccess-callback) | A callback to run every time a request is successfully sent to the collector. | | `function` |
-| [`onRequestFailure`](/docs/sources/trackers/javascript-trackers/web-tracker/configuring-how-events-sent/index.md#onrequestfailure-callback) | A callback to run every time a request fails to send. | | `function` |
-| [`preservePageViewIdForUrl`](/docs/sources/trackers/javascript-trackers/web-tracker/tracking-events/page-views/index.md#when-is-the-page-view-id-generated) | Option to change when a new page view ID is generated. Makes it possible to generate a new page view on URL change instead of when tracking a page view, which enables tracking events before the page view event with the same ID. | `false` | `false`, `true`, `full`, `pathname`, `pathnameAndSearch` |
-| [`customFetch`](/docs/sources/trackers/javascript-trackers/web-tracker/configuring-how-events-sent/index.md#custom-event-store) | Enables overriding the default fetch function with a custom implementation. | function | |
-| [`eventStore`](/docs/sources/trackers/javascript-trackers/web-tracker/configuring-how-events-sent/index.md#custom-event-store) | Enables providing a custom EventStore implementation to store events before sending them to the collector. | object | |
-| [`keepalive`](/docs/sources/trackers/javascript-trackers/web-tracker/configuring-how-events-sent/index.md#keepalive-option-for-collector-requests) | Indicates that the request should be allowed to outlive the webpage that initiated it. Enables collector requests to complete even if the page is closed or navigated away from. | boolean | false |
-| [`synchronousCookieWrite`](/docs/sources/trackers/javascript-trackers/web-tracker/configuring-how-events-sent/index.md#synchronous-cookie-writes) | Whether to write the cookies synchronously. | boolean | false |
+The following table shows all the configuration parameters. These are all optional. In fact, you aren't required to provide any configuration object at all.
+
+| Property | Description | Default (if applicable) | Type |
+| ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------- | -------------------------------------------------------- |
+| [`appId`](/docs/sources/trackers/javascript-trackers/web-tracker/tracking-events/index.md#setting-application-id) | Set the application ID. | | `string` |
+| [`appVersion`](/docs/sources/trackers/javascript-trackers/web-tracker/tracking-events/index.md#setting-application-version) | Set the application version. | | `string` |
+| [`platform`](/docs/sources/trackers/javascript-trackers/web-tracker/tracking-events/index.md#setting-application-platform) | Set the application platform. | "web" | `string` enum |
+| [`cookieDomain`](/docs/sources/trackers/javascript-trackers/web-tracker/cookies-and-local-storage/configuring-cookies/index.md#cookie-domain) | Set the cookie domain. | | |
+| [`discoverRootDomain`](/docs/sources/trackers/javascript-trackers/web-tracker/cookies-and-local-storage/configuring-cookies/index.md#cookie-domain) | Automatic discovery and setting of the root domain, to facilitate tracking over multiple subdomains. | true | `boolean` |
+| [`cookieName`](/docs/sources/trackers/javascript-trackers/web-tracker/cookies-and-local-storage/configuring-cookies/index.md#cookie-name) | Set the cookie name. | | `string` |
+| [`cookieSameSite`](/docs/sources/trackers/javascript-trackers/web-tracker/cookies-and-local-storage/configuring-cookies/index.md#cookie-samesite-and-secure-attributes) | Set the cookie same-site attribute. | null | `string` enum |
+| [`cookieSecure`](/docs/sources/trackers/javascript-trackers/web-tracker/cookies-and-local-storage/configuring-cookies/index.md#cookie-samesite-and-secure-attributes) | Set the cookie secure attribute. | true | `boolean` |
+| [`encodeBase64`](/docs/sources/trackers/javascript-trackers/web-tracker/configuring-how-events-sent/index.md#base64-encoding) | Enable Base64 encoding for entities and custom self-describing events (JSON objects). | true for GET, false for POST requests | `boolean` |
+| [`respectDoNotTrack`](/docs/sources/trackers/javascript-trackers/web-tracker/anonymous-tracking/index.md#respecting-do-not-track) | Choose to respect browser `Do Not` Track option. | false | `boolean` |
+| [`eventMethod`](/docs/sources/trackers/javascript-trackers/web-tracker/configuring-how-events-sent/index.md#network-protocol-and-method) | Choose to send events by GET or POST. | `post` | `string` enum |
+| [`bufferSize`](/docs/sources/trackers/javascript-trackers/web-tracker/configuring-how-events-sent/index.md#number-of-events-per-request) | How many events to send in one request. | 1 | `int` |
+| [`maxPostBytes`](/docs/sources/trackers/javascript-trackers/web-tracker/configuring-how-events-sent/index.md#maximum-payload-size) | Set a limit for the size of one request. | 40000 | `int` |
+| [`maxGetBytes`](/docs/sources/trackers/javascript-trackers/web-tracker/configuring-how-events-sent/index.md#maximum-payload-size) | Set a limit for the size of one request. | | `int` |
+| [`postPath`](/docs/sources/trackers/javascript-trackers/web-tracker/configuring-how-events-sent/index.md#custom-post-path) | Change the collector POST path. | | `string` |
+| [`useExtendedCrossDomainLinker`](/docs/sources/trackers/javascript-trackers/web-tracker/cross-domain-tracking/index.md) | Decorate links for cross-domain tracking using the extended format. | | `object` |
+| [`crossDomainLinker`](/docs/sources/trackers/javascript-trackers/web-tracker/cross-domain-tracking/index.md) | Decorate links for cross-domain tracking using the original, short format. | | `function` |
+| [`cookieLifetime`](/docs/sources/trackers/javascript-trackers/web-tracker/cookies-and-local-storage/configuring-cookies/index.md#cookie-lifetime-and-duration) | Set the cookie lifetime. | 63072000 s (2 years) | `int` |
+| [`stateStorageStrategy`](/docs/sources/trackers/javascript-trackers/web-tracker/cookies-and-local-storage/configuring-cookies/index.md#storage-strategy) | How to store tracker state. | `cookieAndLocalStorage` | `string` enum |
+| [`maxLocalStorageQueueSize`](/docs/sources/trackers/javascript-trackers/web-tracker/cookies-and-local-storage/configuring-cookies/index.md#local-storage-queue-size) | How many events to queue in local storage when they're failing to send. | 1000 | `int` |
+| [`resetActivityTrackingOnPageView`](/docs/sources/trackers/javascript-trackers/web-tracker/tracking-events/activity-page-pings/index.md#reset-page-ping-on-page-view) | Choose to reset page ping timers when a page view is tracked. | true | `boolean` |
+| [`connectionTimeout`](/docs/sources/trackers/javascript-trackers/web-tracker/configuring-how-events-sent/index.md#connection-timeout) | Set request connection timeout. | 5000 ms | `int` |
+| [`anonymousTracking`](/docs/sources/trackers/javascript-trackers/web-tracker/anonymous-tracking/index.md) | Don't track user identifiers. | false | `boolean` |
+| [`customHeaders`](/docs/sources/trackers/javascript-trackers/web-tracker/configuring-how-events-sent/index.md#custom-request-headers) | Add custom headers to requests. | | `object` |
+| [`credentials`](/docs/sources/trackers/javascript-trackers/web-tracker/configuring-how-events-sent/index.md#disabling-sending-credentials-with-requests) | Choose whether to include cookies in certain collector requests. | `include` | `string` enum |
+| [`contexts`](/docs/sources/trackers/javascript-trackers/web-tracker/tracking-events/index.md#auto-tracked-entities) | Configure context entities to add to all events. | various | `object` |
+| [`retryStatusCodes`](/docs/sources/trackers/javascript-trackers/web-tracker/configuring-how-events-sent/index.md#custom-retry-http-codes) | Set HTTP response codes to retry requests on. | | `[int]` |
+| [`dontRetryStatusCodes`](/docs/sources/trackers/javascript-trackers/web-tracker/configuring-how-events-sent/index.md#custom-retry-http-codes) | Set HTTP response codes not to retry requests on. | | `[int]` |
+| [`retryFailedRequests`](/docs/sources/trackers/javascript-trackers/web-tracker/configuring-how-events-sent/index.md#retries) | Choose to retry failed requests or not. | true | `boolean` |
+| [`onSessionUpdateCallback`](/docs/sources/trackers/javascript-trackers/web-tracker/tracking-events/session/index.md#on-session-update-callback) | A callback to run every time the session updates. | | `function` |
+| [`onRequestSuccess`](/docs/sources/trackers/javascript-trackers/web-tracker/configuring-how-events-sent/index.md#onrequestsuccess-callback) | A callback to run every time a request is successfully sent to the collector. | | `function` |
+| [`onRequestFailure`](/docs/sources/trackers/javascript-trackers/web-tracker/configuring-how-events-sent/index.md#onrequestfailure-callback) | A callback to run every time a request fails to send. | | `function` |
+| [`preservePageViewIdForUrl`](/docs/sources/trackers/javascript-trackers/web-tracker/tracking-events/page-views/index.md#when-is-the-page-view-id-generated) | Option to change when a new page view ID is generated. Makes it possible to generate a new page view on URL change instead of when tracking a page view, which enables tracking events before the page view event with the same ID. | `false` | `false`, `true`, `full`, `pathname`, `pathnameAndSearch` |
+| [`customFetch`](/docs/sources/trackers/javascript-trackers/web-tracker/configuring-how-events-sent/index.md#custom-event-store) | Enables overriding the default fetch function with a custom implementation. | function | |
+| [`eventStore`](/docs/sources/trackers/javascript-trackers/web-tracker/configuring-how-events-sent/index.md#custom-event-store) | Enables providing a custom EventStore implementation to store events before sending them to the collector. | object | |
+| [`keepalive`](/docs/sources/trackers/javascript-trackers/web-tracker/configuring-how-events-sent/index.md#keepalive-option-for-collector-requests) | Indicates that the request should be allowed to outlive the webpage that initiated it. Enables collector requests to complete even if the page is closed or navigated away from. | boolean | false |
+| [`synchronousCookieWrite`](/docs/sources/trackers/javascript-trackers/web-tracker/configuring-how-events-sent/index.md#synchronous-cookie-writes) | Whether to write the cookies synchronously. | boolean | false |
Here is a longer code example in which every tracker configuration parameter is set:
@@ -124,6 +127,9 @@ snowplow('newTracker', 'sp', '{{collector_url_here}}', {
maxPostBytes: 40000,
maxGetBytes: 1000, // available in v3.4+
postPath: '/custom/path', // Collector must be configured
+ useExtendedCrossDomainLinker: {
+ userId: true,
+ },
crossDomainLinker: function (linkElement) {
return (linkElement.href === 'http://acme.de' || linkElement.id === 'crossDomainLink');
},
@@ -181,6 +187,9 @@ newTracker('sp', '{{collector_url_here}}', {
maxPostBytes: 40000,
maxGetBytes: 1000, // available in v3.4+
postPath: '/custom/path', // Collector must be configured
+ useExtendedCrossDomainLinker: {
+ userId: true,
+ },
crossDomainLinker: function (linkElement) {
return (linkElement.href === 'http://acme.de' || linkElement.id === 'crossDomainLink');
},