Add documentation for changes in the JS tracker 4.1 (#1091)

snowplow · Nov 28, 2024 · b77d221 · b77d221
1 parent 7a6351a
commit b77d221
Show file tree

Hide file tree

Showing 5 changed files with 108 additions and 1 deletion.
diff --git a/...s/javascript-trackers/web-tracker/tracker-setup/initialization-options/index.md b/...s/javascript-trackers/web-tracker/tracker-setup/initialization-options/index.md
@@ -26,6 +26,7 @@ Here is a simple example of how to initialise a tracker, setting a few configura
 ```javascript
 snowplow('newTracker', 'sp', '{{collector_url_here}}', {
   appId: 'my-app-id',
+  appVersion: '0.1.0',
   discoverRootDomain: true, // default, can be omitted
   cookieSameSite: 'Lax', // Recommended
   contexts: {
@@ -40,6 +41,7 @@ snowplow('newTracker', 'sp', '{{collector_url_here}}', {
 ```javascript
 newTracker('sp', '{{collector_url_here}}', {
   appId: 'my-app-id',
+  appVersion: '0.1.0',
   discoverRootDomain: true, // default, can be omitted
   cookieSameSite: 'Lax', // Recommended
   contexts: {
@@ -64,6 +66,7 @@ The following table shows all the various configuration parameters. Note that th
 | Property                                                                                                                                                                                      | Description                                                                                          | Default (if applicable) | Type          |
 |-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------|-------------------------|---------------|
 | [`appId`](/docs/collecting-data/collecting-from-own-applications/javascript-trackers/web-tracker/tracking-events/#setting-application-id)                                                     | Set the application ID.                                                                              |                         | `string`      |
+| [`appVersion`](/docs/collecting-data/collecting-from-own-applications/javascript-trackers/web-tracker/tracking-events/index.md#setting-application-version)                                                     | Set the application version.                                                                              |                         | `string`      |
 | [`platform`](/docs/collecting-data/collecting-from-own-applications/javascript-trackers/web-tracker/tracking-events/#setting-application-platform)                                            | Set the application platform.                                                                        | "web"                   | `string` enum |
 | [`cookieDomain`](/docs/collecting-data/collecting-from-own-applications/javascript-trackers/web-tracker/cookies-and-local-storage/configuring-cookies/#cookie-domain)                                                                                                                                                                                | Set the cookie domain.                                                                               |                         |               |
 | [`discoverRootDomain`](/docs/collecting-data/collecting-from-own-applications/javascript-trackers/web-tracker/cookies-and-local-storage/configuring-cookies/#cookie-domain)                                                                                                                                                                          | Automatic discovery and setting of the root domain, to facilitate tracking over multiple subdomains. | true                    | `boolean`     |
@@ -107,6 +110,7 @@ Here is a longer code example in which every tracker configuration parameter is
 ```javascript
 snowplow('newTracker', 'sp', '{{collector_url_here}}', {
   appId: 'my-app-id',
+  appVersion: '0.1.0',
   platform: 'web',
   cookieDomain: null,
   discoverRootDomain: true,
@@ -163,6 +167,7 @@ snowplow('newTracker', 'sp', '{{collector_url_here}}', {
 ```javascript
 newTracker('sp', '{{collector_url_here}}', {
   appId: 'my-app-id',
+  appVersion: '0.1.0',
   platform: 'web',
   cookieDomain: null,
   discoverRootDomain: true,

diff --git a/...lications/javascript-trackers/web-tracker/tracking-events/button-click/index.md b/...lications/javascript-trackers/web-tracker/tracking-events/button-click/index.md
@@ -212,6 +212,85 @@ enableButtonClickTracking({
 </TabItem>
 </Tabs>
 
+## Adding context entities to tracked events
+
+You can also attach context entities to the tracked button click events as either an array of self-describing JSON objects or a callback function that returns the entities dynamically.
+
+### Statically defined context entities
+
+To add a static list of context entities to the events, use the following configuration
+
+<Tabs groupId="platform" queryString>
+<TabItem value="js" label="JavaScript (tag)" default>
+
+```javascript
+window.snowplow('enableButtonClickTracking', {
+  context: [
+    {
+      schema: 'iglu:com.example_company/page/jsonschema/1-2-1',
+      data: { pageType: 'test' }
+    }
+  ],
+});
+```
+
+</TabItem>
+<TabItem value="browser" label="Browser (npm)">
+
+```javascript
+import { enableButtonClickTracking } from '@snowplow/browser-plugin-button-click-tracking';
+
+enableButtonClickTracking({
+  context: [
+    {
+      schema: 'iglu:com.example_company/page/jsonschema/1-2-1',
+      data: { pageType: 'test' }
+    }
+  ],
+});
+```
+
+</TabItem>
+</Tabs>
+
+### Dynamic context entities
+
+You can define a callback function that takes the click event and button element as parameters and returns a context entity for that specific event.
+
+
+<Tabs groupId="platform" queryString>
+<TabItem value="js" label="JavaScript (tag)" default>
+
+```javascript
+window.snowplow('enableButtonClickTracking', {
+  context: function (event, element) {
+    return {
+      schema: 'iglu:com.example_company/click/jsonschema/1-2-1',
+      data: { content: element.textContent }
+    };
+  },
+});
+```
+
+</TabItem>
+<TabItem value="browser" label="Browser (npm)">
+
+```javascript
+import { enableButtonClickTracking } from '@snowplow/browser-plugin-button-click-tracking';
+
+enableButtonClickTracking({
+  context: function (event, element) {
+    return {
+      schema: 'iglu:com.example_company/click/jsonschema/1-2-1',
+      data: { content: element.textContent }
+    };
+  },
+});
+```
+
+</TabItem>
+</Tabs>
+
 ## Tracked data
 
 The plugin will track the following data (if present on the element):

diff --git a/...-from-own-applications/javascript-trackers/web-tracker/tracking-events/index.md b/...-from-own-applications/javascript-trackers/web-tracker/tracking-events/index.md
@@ -205,6 +205,16 @@ All events also provide the option for setting a custom timestamp, called `trueT
 
 Set the application ID using the `appId` field of the [tracker configuration object](/docs/collecting-data/collecting-from-own-applications/javascript-trackers/web-tracker/tracker-setup/initialization-options/index.md). This will be attached to every event the tracker fires. You can set different application IDs on different parts of your site. You can then distinguish events that occur on different applications by grouping results based on `application_id`.
 
+### Setting application version
+
+:::info
+The option to track the application version was introduced in version 4.1 of the JavaScript tracker.
+:::
+
+Set the application ID using the `appVersion` field of the [tracker configuration object](/docs/collecting-data/collecting-from-own-applications/javascript-trackers/web-tracker/tracker-setup/initialization-options/index.md). This will be attached to every event the tracker fires using the [application context entity](/docs/collecting-data/collecting-from-own-applications/snowplow-tracker-protocol/ootb-data/app-information/index.md#application-context-entity-on-web-apps).
+
+The version of can be a semver-like structure (e.g 1.1.0) or a Git commit SHA hash.
+
 ### Setting application platform
 
 Set the application platform using the `platform` field of the [tracker configuration object](/docs/collecting-data/collecting-from-own-applications/javascript-trackers/web-tracker/tracker-setup/initialization-options/index.md). This will be attached to every event the tracker fires. Its default value is “web”. For a list of supported platforms, please see the [Snowplow Tracker Protocol](/docs/collecting-data/collecting-from-own-applications/snowplow-tracker-protocol/index.md#application-parameters).

diff --git a/...m-own-applications/snowplow-tracker-protocol/ootb-data/app-information/index.md b/...m-own-applications/snowplow-tracker-protocol/ootb-data/app-information/index.md
@@ -32,6 +32,19 @@ You can specify the tracker namespace and app ID when creating a new tracker ins
 The tracker platform is set automatically but can be overriden in most of our trackers.
 The tracker version is also set automatically.
 
+## Application context entity on Web apps
+
+This context entity is tracked with events tracked using the JavaScript tracker starting from version 4.1.0.
+The application version is provided in the tracker configuration, [see instructions here](/docs/collecting-data/collecting-from-own-applications/javascript-trackers/web-tracker/tracking-events/index.md#setting-application-version).
+
+<SchemaProperties
+  overview={{event: false, web: true, mobile: false, automatic: false}}
+  example={{
+    "version": "1.1.0"
+  }}
+  schema={{ "description": "Schema for an application context which tracks the app version.", "properties": { "version": { "type": "string", "description": "Version of the application. Can be a semver-like structure (e.g 1.1.0) or a Git commit SHA hash.", "maxLength": 255 } }, "additionalProperties": false, "type": "object", "required": [ "version" ], "self": { "vendor": "com.snowplowanalytics.snowplow", "name": "application", "format": "jsonschema", "version": "1-0-0" }, "$schema": "http://iglucentral.com/schemas/com.snowplowanalytics.self-desc/schema/jsonschema/1-0-0#" }} />
+
+
 ## Application context entity on mobile apps
 
 This context entity is automatically tracked with events on mobile apps and gives information about the app version and build number.

diff --git a/src/componentVersions.js b/src/componentVersions.js
@@ -8,7 +8,7 @@ export const versions = {
   googleAmpTracker: '1.1.0',
   iosTracker: '6.0.8',
   javaTracker: '2.1.0',
-  javaScriptTracker: '4.0.4',
+  javaScriptTracker: '4.1.0',
   luaTracker: '0.2.0',
   phpTracker: '0.7.1',
   pixelTracker: '0.3.0',