@salesforcedevs/dx-components 1.37.2 → 1.38.0

package/lwc.config.json

@@ -72,6 +72,7 @@
         "dx/iconBadge",
         "dx/imageAndLabel",
         "dx/input",
+        "dx/instrumentation",
         "dx/interactiveImage",
         "dx/logo",
         "dx/mainContentHeader",

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@salesforcedevs/dx-components",
-    "version": "1.37.2",
+    "version": "1.38.0",
     "description": "DX Lightning web components",
     "license": "MIT",
     "engines": {
@@ -44,5 +44,5 @@
         "luxon": "3.4.4",
         "msw": "^2.12.4"
     },
-    "gitHead": "ca79eefb9b9ec80bb48c96a091fd0ce558bda710"
+    "gitHead": "fc9d953dd79b76e37578fc43691fa56d6c4dd028"
 }

package/src/modules/dx/instrumentation/instrumentation.html

@@ -0,0 +1 @@
+<template></template>

package/src/modules/dx/instrumentation/instrumentation.ts

@@ -0,0 +1,154 @@
+import { LightningElement, api } from "lwc";
+import {
+    TRACKING_EVENT_NAME as DX_TRACKING_EVENT_NAME,
+    LISTENER_QUEUE as DX_LISTENER_QUEUE,
+    LISTENER_INDICATOR as DX_LISTENER_INDICATOR,
+    track as dxTrack
+} from "dxUtils/analytics";
+
+// Architect ("architectssite_track") namespace. These mirror the constants used
+// by <arch-instrumentation> in @salesforcedevs/arch-components. They are declared
+// locally rather than imported because dx-components does not depend on
+// arch-components.
+const ARCH_TRACKING_EVENT_NAME = "architectssite_track";
+const ARCH_LISTENER_QUEUE = "__TDS_INSTRUMENTATION_QUEUE__";
+const ARCH_LISTENER_INDICATOR = "__TDS_INSTRUMENTATION_IS_INITIALIZED__";
+
+// Arch-namespace equivalent of dxUtils/analytics `track`: either dispatch the
+// architect tracking event (once the listener is mounted) or queue it. Used to
+// replay events that were queued in __TDS_INSTRUMENTATION_QUEUE__ before this
+// component mounted.
+function archTrack(
+    element: EventTarget,
+    event: string,
+    payload: Record<string, unknown>
+): void {
+    const detail = { event, payload };
+    if ((window as any)[ARCH_LISTENER_INDICATOR] === undefined) {
+        (window as any)[ARCH_LISTENER_QUEUE] =
+            (window as any)[ARCH_LISTENER_QUEUE] || [];
+        (window as any)[ARCH_LISTENER_QUEUE].push(detail);
+    } else {
+        const e = new CustomEvent(ARCH_TRACKING_EVENT_NAME, {
+            bubbles: true,
+            composed: true,
+            detail
+        });
+        element.dispatchEvent(e);
+    }
+}
+
+const googleTagManager = {
+    track: function (e: Event) {
+        if ((window as any).dataLayer === undefined) {
+            (window as any).dataLayer = [];
+        }
+        const { event, payload } = (e as CustomEvent).detail;
+        (window as any).dataLayer.push({ ...payload, event });
+    }
+};
+
+interface TrackEventListener {
+    add: () => void;
+    remove: () => void;
+}
+
+/**
+ * Attaches a listener for BOTH the developer (`developerwebsite_track`) and
+ * architect (`architectssite_track`) tracking events, forwarding each caught
+ * event to every tracker function. A single component can therefore bridge both
+ * event namespaces into the dataLayer.
+ */
+export function instrumentationTrackEventListener(
+    trackerFns: { track: (e: Event) => void }[] = []
+): TrackEventListener {
+    if (trackerFns.length === 0) {
+        throw new Error("No tracker functions passed");
+    }
+
+    const handleTrackEvent = (e: Event) => {
+        trackerFns.forEach((tracker) => {
+            tracker.track(e);
+        });
+    };
+
+    const attachEventListener = () => {
+        document.addEventListener(DX_TRACKING_EVENT_NAME, handleTrackEvent);
+        document.addEventListener(ARCH_TRACKING_EVENT_NAME, handleTrackEvent);
+    };
+
+    const removeEventListener = () => {
+        document.removeEventListener(DX_TRACKING_EVENT_NAME, handleTrackEvent);
+        document.removeEventListener(
+            ARCH_TRACKING_EVENT_NAME,
+            handleTrackEvent
+        );
+    };
+
+    return {
+        add: attachEventListener,
+        remove: removeEventListener
+    };
+}
+
+/**
+ * Unified instrumentation bridge. Mount a single <dx-instrumentation> to forward
+ * both developer-website and architect-website tracking events into the GTM
+ * dataLayer — replacing the need to mount <dw-instrumentation> and
+ * <arch-instrumentation> separately. Renders nothing.
+ */
+export default class Instrumentation extends LightningElement {
+    @api useGoogleTagManager = false;
+
+    private tracker: TrackEventListener | null = null;
+
+    private setupTracker() {
+        const trackerFunctions = this.useGoogleTagManager
+            ? [googleTagManager]
+            : [];
+        this.tracker = instrumentationTrackEventListener(trackerFunctions);
+        this.tracker.add();
+        // Mark both namespaces initialized so track() calls from either the
+        // developer or architect stacks dispatch live events instead of queueing.
+        (window as any)[DX_LISTENER_INDICATOR] = true;
+        (window as any)[ARCH_LISTENER_INDICATOR] = true;
+    }
+
+    private dispatchQueuedEvents() {
+        const dxQueue = (window as any)[DX_LISTENER_QUEUE];
+        if (Array.isArray(dxQueue)) {
+            while (dxQueue.length > 0) {
+                const event = dxQueue.pop() as {
+                    event: string;
+                    payload: Record<string, unknown>;
+                };
+                dxTrack(this, event.event, event.payload);
+            }
+        }
+
+        const archQueue = (window as any)[ARCH_LISTENER_QUEUE];
+        if (Array.isArray(archQueue)) {
+            while (archQueue.length > 0) {
+                const event = archQueue.pop() as {
+                    event: string;
+                    payload: Record<string, unknown>;
+                };
+                archTrack(this, event.event, event.payload);
+            }
+        }
+    }
+
+    renderedCallback() {
+        if (this.tracker === null) {
+            this.setupTracker();
+            this.dispatchQueuedEvents();
+        }
+    }
+
+    disconnectedCallback() {
+        if (this.tracker !== null) {
+            this.tracker.remove();
+            this.tracker = null;
+        }
+    }
+}