Add appVersion configuration option to track a context entity with the application version (#1373)

Author: matus-tomlein

api-docs/docs/browser-tracker/browser-tracker.api.md

@@ -523,6 +523,7 @@ export type TrackerConfiguration = {
     cookieLifetime?: number;
     sessionCookieTimeout?: number;
     appId?: string;
+    appVersion?: string;
     platform?: Platform;
     respectDoNotTrack?: boolean;
     crossDomainLinker?: (elt: HTMLAnchorElement | HTMLAreaElement) => boolean;

api-docs/docs/browser-tracker/markdown/browser-tracker.trackerconfiguration.md

@@ -18,6 +18,7 @@ type TrackerConfiguration = {
     cookieLifetime?: number;
     sessionCookieTimeout?: number;
     appId?: string;
+    appVersion?: string;
     platform?: Platform;
     respectDoNotTrack?: boolean;
     crossDomainLinker?: (elt: HTMLAnchorElement | HTMLAreaElement) => boolean;
@@ -44,6 +45,5 @@ newTracker('sp1', 'collector.my-website.com', {
  plugins: [ PerformanceTimingPlugin(), AdTrackingPlugin() ],
  stateStorageStrategy: 'cookieAndLocalStorage'
 });
-
 ```
 

common/changes/@snowplow/browser-tracker-core/issue-application_context_2024-11-08-11-09.json

@@ -0,0 +1,10 @@
+{
+  "changes": [
+    {
+      "packageName": "@snowplow/browser-tracker-core",
+      "comment": "Add appVersion configuration option to track a context entity with the application version",
+      "type": "none"
+    }
+  ],
+  "packageName": "@snowplow/browser-tracker-core"
+}

libraries/browser-tracker-core/src/tracker/index.ts

@@ -65,7 +65,7 @@ import {
   emptyIdCookie,
   eventIndexFromIdCookie,
 } from './id_cookie';
-import { CLIENT_SESSION_SCHEMA, WEB_PAGE_SCHEMA, BROWSER_CONTEXT_SCHEMA } from './schemata';
+import { CLIENT_SESSION_SCHEMA, WEB_PAGE_SCHEMA, BROWSER_CONTEXT_SCHEMA, APPLICATION_CONTEXT_SCHEMA } from './schemata';
 import { getBrowserProperties } from '../helpers/browser_props';
 import { asyncCookieStorage, syncCookieStorage } from './cookie_storage';
 
@@ -149,13 +149,13 @@ export function Tracker(
         if (typeof config.anonymousTracking === 'boolean') {
           return false;
         }
-        return config.anonymousTracking?.withSessionTracking === true ?? false;
+        return config.anonymousTracking?.withSessionTracking === true;
       },
       getAnonymousServerTracking = (config: TrackerConfiguration) => {
         if (typeof config.anonymousTracking === 'boolean') {
           return false;
         }
-        return config.anonymousTracking?.withServerAnonymisation === true ?? false;
+        return config.anonymousTracking?.withServerAnonymisation === true;
       },
       getAnonymousTracking = (config: TrackerConfiguration) => !!config.anonymousTracking,
       isBrowserContextAvailable = trackerConfiguration?.contexts?.browser ?? false,
@@ -203,6 +203,8 @@ export function Tracker(
       configPlatform = trackerConfiguration.platform ?? 'web',
       // Site ID
       configTrackerSiteId = trackerConfiguration.appId ?? '',
+      // Application version
+      configAppVersion = trackerConfiguration.appVersion,
       // Document URL
       configCustomUrl: string,
       // Document title
@@ -323,6 +325,20 @@ export function Tracker(
     core.addPayloadPair('cd', colorDepth);
     if (timeZone) core.addPayloadPair('tz', timeZone);
 
+    // Add the application version context entity
+    if (configAppVersion) {
+      core.addPlugin({
+        plugin: {
+          contexts: () => [
+            {
+              schema: APPLICATION_CONTEXT_SCHEMA,
+              data: { version: configAppVersion },
+            },
+          ],
+        },
+      });
+    }
+
     /*
      * Initialize tracker
      */

libraries/browser-tracker-core/src/tracker/schemata.ts

@@ -1,3 +1,4 @@
 export const WEB_PAGE_SCHEMA = 'iglu:com.snowplowanalytics.snowplow/web_page/jsonschema/1-0-0';
 export const BROWSER_CONTEXT_SCHEMA = 'iglu:com.snowplowanalytics.snowplow/browser_context/jsonschema/2-0-0';
 export const CLIENT_SESSION_SCHEMA = 'iglu:com.snowplowanalytics.snowplow/client_session/jsonschema/1-0-2';
+export const APPLICATION_CONTEXT_SCHEMA = 'iglu:com.snowplowanalytics.snowplow/application/jsonschema/1-0-0';

libraries/browser-tracker-core/src/tracker/types.ts

@@ -117,6 +117,12 @@ export type TrackerConfiguration = {
   sessionCookieTimeout?: number;
   /** The app id to send with each event */
   appId?: string;
+  /**
+   * Version of the application tracked as a context entity with all events.
+   * Can be a semver-like structure (e.g 1.1.0) or a Git commit SHA hash.
+   * Entity schema: iglu:com.snowplowanalytics.snowplow/application/jsonschema/1-0-0
+   */
+  appVersion?: string;
   /**
    * The platform the event is being sent from
    * @defaultValue web

libraries/browser-tracker-core/test/tracker/application_context.test.ts

@@ -0,0 +1,44 @@
+import { APPLICATION_CONTEXT_SCHEMA } from '../../src/tracker/schemata';
+import { createTracker } from '../helpers';
+
+describe('Application context:', () => {
+  it('Adds the entity when the appVersion option is configured', (done) => {
+    const tracker = createTracker({
+      appVersion: '1.0.2-beta.2',
+      plugins: [
+        {
+          filter: (payload) => {
+            const { data: payloadData } = JSON.parse(payload.co as string);
+            const appContext = payloadData.find((context: any) => context.schema.match(APPLICATION_CONTEXT_SCHEMA));
+            expect(appContext).toBeTruthy();
+            expect(appContext.data.version).toBe('1.0.2-beta.2');
+            done();
+            return false;
+          },
+        },
+      ],
+    });
+
+    tracker?.trackPageView();
+  });
+
+  it('Does not attach the entity if not configured', (done) => {
+    const tracker = createTracker({
+      plugins: [
+        {
+          filter: (payload) => {
+            const { data: payloadData } = JSON.parse(payload.co as string);
+            const applicationContext = payloadData.find((context: any) =>
+              context.schema.match(APPLICATION_CONTEXT_SCHEMA)
+            );
+            expect(applicationContext).toBeUndefined();
+            done();
+            return false
+          },
+        },
+      ],
+    });
+
+    tracker?.trackPageView();
+  });
+});