Skip to content

Commit

Permalink
Update docs for JavaScript tracker v3.17.0 (snowplow#670)
Browse files Browse the repository at this point in the history
  • Loading branch information
@adatzer
adatzer authored Nov 22, 2023
1 parent 78db2d1 commit 18ef742
Show file tree
Hide file tree
Showing 2 changed files with 93 additions and 7 deletions.
90 changes: 86 additions & 4 deletions ...om-own-applications/javascript-trackers/web-tracker/plugins/ga-cookies/index.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -12,7 +12,7 @@ import ReleaseBadge from '@site/docs/reusable/javascript-tracker-release-badge-v
<ReleaseBadge/>
```

If this plugin is used, the tracker will look for Google Analytics cookies (specifically the `__utma`, `__utmb`, `__utmc`, `__utmv`, `__utmz`, and `_ga` cookies) and combine their values into an event context which gets sent with every event.
If this plugin is used, the tracker will look for Google Analytics cookies (Universal Analytics and GA4 cookies) and combine their values into event contexts which gets sent with every event.

## Installation

Expand Down Expand Up @@ -43,11 +43,15 @@ If this plugin is used, the tracker will look for Google Analytics cookies (spec

## Initialization

<details>

<summary><i>pre-v3.17.0</i></summary>

<Tabs groupId="platform" queryString>
<TabItem value="js" label="JavaScript (tag)" default>

```javascript
window.snowplow('addPlugin',
window.snowplow('addPlugin',
"https://cdn.jsdelivr.net/npm/@snowplow/browser-plugin-ga-cookies@latest/dist/index.umd.min.js",
["snowplowGaCookies", "GaCookiesPlugin"]
);
Expand All @@ -60,19 +64,97 @@ window.snowplow('addPlugin',
import { newTracker, trackPageView } from '@snowplow/browser-tracker';
import { GaCookiesPlugin } from '@snowplow/browser-plugin-ga-cookies';

newTracker('sp1', '{{collector_url}}', {
appId: 'my-app-id',
newTracker('sp1', '{{collector_url}}', {
appId: 'my-app-id',
plugins: [ GaCookiesPlugin() ],
});
```

</TabItem>
</Tabs>

</details>

<Tabs groupId="platform" queryString>
<TabItem value="js" label="JavaScript (tag)" default>

```javascript
window.snowplow('addPlugin',
"https://cdn.jsdelivr.net/npm/@snowplow/browser-plugin-ga-cookies@latest/dist/index.umd.min.js",
["snowplowGaCookies", "GaCookiesPlugin"],
[pluginOptions]
);
```

</TabItem>
<TabItem value="browser" label="Browser (npm)">

```javascript
import { newTracker, trackPageView } from '@snowplow/browser-tracker';
import { GaCookiesPlugin } from '@snowplow/browser-plugin-ga-cookies';

newTracker('sp1', '{{collector_url}}', {
appId: 'my-app-id',
plugins: [ GaCookiesPlugin(pluginOptions) ],
});
```

</TabItem>
</Tabs>

The `pluginOptions` parameter allows to configure the plugin. It's type is:

```javascript
interface GACookiesPluginOptions {
ua?: boolean;
ga4?: boolean;
ga4MeasurementId?: string | string[];
cookiePrefix?: string | string[];
}
```

| Name | Default | Description |
|------------------|---------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| ua | `true` | Send Universal Analytics specific cookie values. |
| ga4 | `false` | Send Google Analytics 4 specific cookie values. |
| ga4MeasurementId | `""` | Measurement id(s) to search the Google Analytics 4 session cookie. Can be a single measurement id as a string or an array of measurement id strings. The cookie has the form of `<cookie_prefix>_ga_<container-id>` where `<container-id>` is the data stream container id and `<cookie_prefix>` is the optional `cookie_prefix` option of the gtag.js tracker. |
| cookiePrefix | `[]` | Cookie prefix set on the Google Analytics 4 cookies using the `cookie_prefix` option of the gtag.js tracker. |

### Context

<details>

<summary><i>pre-v3.17.0</i></summary>

Adding this plugin will automatically capture the following context:

| Context | Example |
|------------------------------------------------------------------------------------------------------------------------------------------------------------------|---------------------------------------------------|
| [iglu:com.google.analytics/cookies/jsonschema/1-0-0](https://github.com/snowplow/iglu-central/blob/master/schemas/com.google.analytics/cookies/jsonschema/1-0-0) | ![](images/Screenshot-2021-03-30-at-22.12.03.png) |

</details>

Adding this plugin will automatically capture the following contexts:

1. For Universal Analytics cookies: `iglu:com.google.analytics/cookies/jsonschema/1-0-0`, e.g.

```
{
"_ga": "GA1.2.3.4"
}
```

2. For GA4 cookies: `iglu:com.google.ga4/cookies/jsonschema/1-0-0`

```
{
"_ga": "G-1234",
"cookie_prefix": "prefix",
"session_cookies": [
{
"measurement_id": "G-1234",
"session_cookie": "567"
}
]
}
```
10 changes: 7 additions & 3 deletions ...s/javascript-trackers/web-tracker/tracker-setup/initialization-options/index.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -99,6 +99,7 @@ snowplow('newTracker', 'sp', '{{collector_url_here}}', {
},
retryStatusCodes: [],
dontRetryStatusCodes: [],
retryFailedRequests: true,
onSessionUpdateCallback: function(clientSession) { }, // Allows the addition of a callback, whenever a new session is generated. Available in v3.11+.
});
```
Expand Down Expand Up @@ -142,6 +143,7 @@ newTracker('sp', '{{collector_url_here}}', {
},
retryStatusCodes: [],
dontRetryStatusCodes: [],
retryFailedRequests: true,
onSessionUpdateCallback: function(clientSession) { }, // Allows the addition of a callback, whenever a new session is generated. Available in v3.11+.
});
```
Expand Down Expand Up @@ -216,7 +218,7 @@ The Snowplow JavaScript tracker offers two techniques where tracking can be done
Recommended configurations when using `anonymousTracking`:

```javascript
anonymousTracking: true,
anonymousTracking: true,
stateStorageStrategy: 'cookieAndLocalStorage'
```

Expand Down Expand Up @@ -392,7 +394,7 @@ The following context entities are only available as configuration options for t
If this context is enabled, the JavaScript Tracker will use the create a context JSON from the `window.performance.timing` object, along with the Chrome `firstPaintTime` field (renamed to `chromeFirstPaint`) if it exists. This data can be used to calculate page performance metrics.
Note that if you fire a page view event as soon as the page loads, the `domComplete`, `loadEventStart`, `loadEventEnd`, and `chromeFirstPaint` metrics in the Navigation Timing API may be set to zero. This is because those properties are only known once all scripts on the page have finished executing.
Note that if you fire a page view event as soon as the page loads, the `domComplete`, `loadEventStart`, `loadEventEnd`, and `chromeFirstPaint` metrics in the Navigation Timing API may be set to zero. This is because those properties are only known once all scripts on the page have finished executing.
<details>
<summary>Advanced PerformanceTiming usage</summary>
Expand Down Expand Up @@ -606,7 +608,7 @@ This value is configurable when initialising the tracker and is specified in mil
## Custom header values
From v3.2.0, you are able to set custom headers with an `eventMethod: "post"` and `eventMethod: "get"` (Except for IE9). This functionality should only be used in the case where a Proxy or other Collector type is being used which allows for custom headers to be set on the request.
From v3.2.0, you are able to set custom headers with an `eventMethod: "post"` and `eventMethod: "get"` (Except for IE9). This functionality should only be used in the case where a Proxy or other Collector type is being used which allows for custom headers to be set on the request.
:::caution
Adding additional headers without returning the appropriate CORS Headers on the OPTIONS request will cause events to fail to send.
Expand Down Expand Up @@ -641,6 +643,8 @@ dontRetryStatusCodes: [418] // force retry on 418
Please note that not retrying sending events to the Collector means that the events will be dropped when they fail to be sent. Take caution when choosing the `dontRetryStatusCodes`.
Starting with version 3.17 of the tracker, it is also possible to completely disable retry functionality, using the `retryFailedRequests` boolean option. This option takes precedence over `retryStatusCodes` and `dontRetryStatusCodes`.
## On session update callback
The `onSessionUpdateCallback` option, allows you to supply a callback function to be executed whenever a new session is generated on the tracker.
Expand Down

0 comments on commit 18ef742

Please sign in to comment.