Merge pull request #848 from ably/web-4381-track-route-changes-as-page-views

[WEB-4381] chore: conditionally allow gtm page view tracking

Author: jamiehenson

package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ably/ui",
-  "version": "17.5.0",
+  "version": "17.5.2",
   "description": "Home of the Ably design system library ([design.ably.com](https://design.ably.com)). It provides a showcase, development/test environment and a publishing pipeline for different distributables.",
   "repository": {
     "type": "git",

src/core/insights/command-queue.ts

@@ -3,6 +3,7 @@ import {
   Command,
   InsightsConfig,
   InsightsIdentity,
+  TrackPageViewOptions,
 } from "./types";
 import { InsightsService } from "./service";
 import * as logger from "./logger";
@@ -117,7 +118,7 @@ export class InsightsCommandQueue implements AnalyticsService {
   enableDebugMode(): void {}
   disableDebugMode(): void {}
   identify(_identity: InsightsIdentity): void {}
-  trackPageView(): void {}
+  trackPageView(_options?: TrackPageViewOptions): void {}
   track(_event: string, _properties?: Record<string, unknown>): void {}
   startSessionRecording(): void {}
   stopSessionRecording(): void {}

src/core/insights/datalayer.ts

@@ -17,3 +17,7 @@ export const track = (event: string, properties?: Record<string, unknown>) => {
     ...properties,
   });
 };
+
+export const trackPageView = () => {
+  track("client-side-route-change");
+};

src/core/insights/index.test.ts

@@ -2,7 +2,7 @@
  * @vitest-environment jsdom
  */
 
-import { describe, expect, beforeEach, afterEach, it, vi } from "vitest";
+import { describe, expect, beforeEach, afterEach, it, vi, Mock } from "vitest";
 
 import * as datalayer from "./datalayer";
 import * as mixpanel from "./mixpanel";
@@ -13,6 +13,7 @@ import * as insights from "./index";
 // Mock the dependencies
 vi.mock("./datalayer", () => ({
   track: vi.fn(),
+  trackPageView: vi.fn(),
 }));
 
 vi.mock("./mixpanel", () => ({
@@ -90,6 +91,7 @@ describe("Insights Command Queue", () => {
       expect(posthog.identify).not.toHaveBeenCalled();
       expect(mixpanel.trackPageView).not.toHaveBeenCalled();
       expect(posthog.trackPageView).not.toHaveBeenCalled();
+      expect(datalayer.trackPageView).not.toHaveBeenCalled();
 
       // Now initialize
       insights.initInsights(testConfig);
@@ -122,11 +124,12 @@ describe("Insights Command Queue", () => {
 
       expect(mixpanel.trackPageView).toHaveBeenCalled();
       expect(posthog.trackPageView).toHaveBeenCalled();
+      expect(datalayer.trackPageView).not.toHaveBeenCalled();
     });
 
     it("should handle errors in queued methods gracefully", async () => {
       // Setup an error for one of the methods
-      mixpanel.track.mockImplementationOnce(() => {
+      (mixpanel.track as Mock).mockImplementationOnce(() => {
         throw new Error("Mixpanel error");
       });
 
@@ -152,6 +155,14 @@ describe("Insights Command Queue", () => {
       });
       expect(mixpanel.trackPageView).toHaveBeenCalled();
       expect(posthog.trackPageView).toHaveBeenCalled();
+      expect(datalayer.trackPageView).not.toHaveBeenCalled();
+    });
+
+    it("should report page view to GTM as well when includeDataLayer is true", () => {
+      insights.trackPageView({ includeDataLayer: true });
+      expect(mixpanel.trackPageView).toHaveBeenCalled();
+      expect(posthog.trackPageView).toHaveBeenCalled();
+      expect(datalayer.trackPageView).toHaveBeenCalled();
     });
   });
 
@@ -188,6 +199,7 @@ describe("Insights Command Queue", () => {
       insights.trackPageView();
       expect(mixpanel.trackPageView).toHaveBeenCalled();
       expect(posthog.trackPageView).toHaveBeenCalled();
+      expect(datalayer.trackPageView).not.toHaveBeenCalled();
 
       insights.startSessionRecording();
       expect(mixpanel.startSessionRecording).toHaveBeenCalled();
@@ -205,6 +217,13 @@ describe("Insights Command Queue", () => {
       expect(mixpanel.disableDebugMode).toHaveBeenCalled();
       expect(posthog.disableDebugMode).toHaveBeenCalled();
     });
+
+    it("should report page view to GTM as well when includeDataLayer is true", () => {
+      insights.trackPageView({ includeDataLayer: true });
+      expect(mixpanel.trackPageView).toHaveBeenCalled();
+      expect(posthog.trackPageView).toHaveBeenCalled();
+      expect(datalayer.trackPageView).toHaveBeenCalled();
+    });
   });
 
   describe("Observer Setup", () => {
@@ -281,7 +300,7 @@ describe("Insights Command Queue", () => {
   describe("Error Handling", () => {
     it("should handle initialization errors gracefully", () => {
       // Setup an error in initialization
-      mixpanel.initMixpanel.mockImplementationOnce(() => {
+      (mixpanel.initMixpanel as Mock).mockImplementationOnce(() => {
         throw new Error("Mixpanel init error");
       });
 
@@ -303,11 +322,11 @@ describe("Insights Command Queue", () => {
       vi.clearAllMocks();
 
       // Setup errors in tracking
-      mixpanel.track.mockImplementationOnce(() => {
+      (mixpanel.track as Mock).mockImplementationOnce(() => {
         throw new Error("Mixpanel track error");
       });
 
-      posthog.track.mockImplementationOnce(() => {
+      (posthog.track as Mock).mockImplementationOnce(() => {
         throw new Error("Posthog track error");
       });
 

src/core/insights/index.ts

@@ -1,4 +1,8 @@
-import { InsightsConfig, InsightsIdentity } from "./types";
+import {
+  InsightsConfig,
+  InsightsIdentity,
+  TrackPageViewOptions,
+} from "./types";
 import { InsightsCommandQueue } from "./command-queue";
 export type { InsightsConfig };
 
@@ -32,7 +36,8 @@ export const enableDebugMode = () => insights.enableDebugMode();
 export const disableDebugMode = () => insights.disableDebugMode();
 export const identify = (identity: InsightsIdentity) =>
   insights.identify(identity);
-export const trackPageView = () => insights.trackPageView();
+export const trackPageView = (options?: TrackPageViewOptions) =>
+  insights.trackPageView(options);
 export const track = (event: string, properties?: Record<string, unknown>) =>
   insights.track(event, properties);
 export const startSessionRecording = () => insights.startSessionRecording();

src/core/insights/service.ts

@@ -2,6 +2,7 @@ import type {
   AnalyticsService,
   InsightsConfig,
   InsightsIdentity,
+  TrackPageViewOptions,
 } from "./types";
 import * as datalayer from "./datalayer";
 import * as mixpanel from "./mixpanel";
@@ -111,7 +112,7 @@ export class InsightsService implements AnalyticsService {
     }
   }
 
-  trackPageView(): void {
+  trackPageView(options?: TrackPageViewOptions): void {
     if (this.debugMode) {
       logger.info("Tracking page view");
     }
@@ -131,6 +132,16 @@ export class InsightsService implements AnalyticsService {
         logger.error("Failed to track page view in Posthog", e);
       }
     }
+
+    if (options?.includeDataLayer) {
+      try {
+        datalayer.trackPageView();
+      } catch (e) {
+        if (this.debugMode) {
+          logger.error("Failed to track page view in GTM", e);
+        }
+      }
+    }
   }
 
   track(event: string, properties?: Record<string, unknown>): void {

src/core/insights/types.ts

@@ -13,7 +13,7 @@ export interface AnalyticsService {
   enableDebugMode: () => void;
   disableDebugMode: () => void;
   identify: (identity: InsightsIdentity) => void;
-  trackPageView: () => void;
+  trackPageView: (options?: TrackPageViewOptions) => void;
   track: (event: string, properties?: Record<string, unknown>) => void;
   startSessionRecording: () => void;
   stopSessionRecording: () => void;
@@ -33,3 +33,7 @@ export type InsightsIdentity = {
   email?: string;
   name?: string;
 };
+
+export type TrackPageViewOptions = {
+  includeDataLayer?: boolean;
+};