Add setSessionId and setSessionIndex capability to Node.js tracker

close #1178

Author: igneel64

common/changes/@snowplow/node-tracker/feature-1178-nodejs-allow-setting-sessionid_2023-05-23-09-45.json

@@ -0,0 +1,10 @@
+{
+  "changes": [
+    {
+      "packageName": "@snowplow/node-tracker",
+      "comment": "Add setSessionId and setSessionIndex capability",
+      "type": "none"
+    }
+  ],
+  "packageName": "@snowplow/node-tracker"
+}

trackers/node-tracker/docs/node-tracker.api.md

@@ -360,6 +360,8 @@ export type Timestamp = TrueTimestamp | DeviceTimestamp | number;
 export interface Tracker extends TrackerCore {
     setDomainUserId: (userId: string) => void;
     setNetworkUserId: (userId: string) => void;
+    setSessionId: (sessionId: string) => void;
+    setSessionIndex: (sessionIndex: string | number) => void;
 }
 
 // @public

trackers/node-tracker/src/tracker.ts

@@ -46,6 +46,20 @@ export interface Tracker extends TrackerCore {
    * @param userId - The network user id
    */
   setNetworkUserId: (userId: string) => void;
+
+  /**
+   * Set the session ID (`domain_sessionid` in the atomic events)
+   *
+   * @param sessionId - The session id
+   */
+  setSessionId: (sessionId: string) => void;
+
+  /**
+   * Set the session index (`domain_sessionidx` in the atomic events)
+   *
+   * @param sessionIndex - The session index
+   */
+  setSessionIndex: (sessionIndex: string | number) => void;
 }
 
 /**
@@ -64,6 +78,8 @@ export function tracker(
 ): Tracker {
   let domainUserId: string;
   let networkUserId: string;
+  let sessionId: string;
+  let sessionIndex: string | number;
   let allEmitters: Array<Emitter>;
 
   if (Array.isArray(emitters)) {
@@ -77,6 +93,8 @@ export function tracker(
   const addUserInformation = (payload: PayloadBuilder): void => {
     payload.add('duid', domainUserId);
     payload.add('nuid', networkUserId);
+    payload.add('sid', sessionId);
+    payload.add('vid', Number(sessionIndex));
   };
 
   /**
@@ -107,9 +125,19 @@ export function tracker(
     networkUserId = userId;
   };
 
+  const setSessionId = function (currentSessionId: string) {
+    sessionId = currentSessionId;
+  };
+
+  const setSessionIndex = function (currentSessionIndex: string | number) {
+    sessionIndex = currentSessionIndex;
+  };
+
   return {
     setDomainUserId,
     setNetworkUserId,
+    setSessionId,
+    setSessionIndex,
     ...core,
   };
 }

trackers/node-tracker/test/tracker.ts

@@ -422,6 +422,8 @@ for (const method of testMethods) {
       refr: 'http://google.com',
       p: 'web',
       uid: 'jacob',
+      sid: 'sessionId',
+      vid: '10',
       res: '400x200',
       vp: '500x800',
       cd: '24',
@@ -449,6 +451,8 @@ for (const method of testMethods) {
 
       track.setPlatform('web');
       track.setUserId('jacob');
+      track.setSessionId('sessionId');
+      track.setSessionIndex(10);
       track.setScreenResolution('400', '200');
       track.setViewport('500', '800');
       track.setColorDepth('24');
@@ -604,4 +608,64 @@ for (const method of testMethods) {
       );
     });
   });
+
+  test(method + ' method: setSessionId should attach a sid property to event', async (t) => {
+    const expected = {
+      sid: 'sid-test-1234',
+    };
+
+    await new Promise((resolve, reject) => {
+      const e = gotEmitter(
+        endpoint,
+        HttpProtocol.HTTPS,
+        undefined,
+        method,
+        0,
+        undefined,
+        undefined,
+        function (error, response) {
+          checkPayload(extractPayload(response?.body, method), expected, t);
+          if (error) reject(error);
+          else resolve(response);
+        }
+      );
+
+      const track = tracker(e, 'cf', 'cfe35', false);
+      track.setSessionId(expected.sid);
+      track.track(
+        buildPageView({ pageUrl: 'http://www.example.com', pageTitle: 'example page', referrer: 'http://google.com' }),
+        context
+      );
+    });
+  });
+
+  test(method + ' method: setSessionIndex should attach a vid property to event', async (t) => {
+    const expected = {
+      vid: '1234',
+    };
+
+    await new Promise((resolve, reject) => {
+      const e = gotEmitter(
+        endpoint,
+        HttpProtocol.HTTPS,
+        undefined,
+        method,
+        0,
+        undefined,
+        undefined,
+        function (error, response) {
+          checkPayload(extractPayload(response?.body, method), expected, t);
+          if (error) reject(error);
+          else resolve(response);
+        }
+      );
+
+      const track = tracker(e, 'cf', 'cfe35', false);
+      track.setSessionIndex(expected.vid);
+      track.track(
+        buildPageView({ pageUrl: 'http://www.example.com', pageTitle: 'example page', referrer: 'http://google.com' }),
+        context
+      );
+    });
+  });
 }