@salesforcedevs/dx-components 1.37.2 → 1.39.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.39.0",
     "description": "DX Lightning web components",
     "license": "MIT",
     "engines": {
@@ -44,5 +44,5 @@
         "luxon": "3.4.4",
         "msw": "^2.12.4"
     },
-    "gitHead": "ca79eefb9b9ec80bb48c96a091fd0ce558bda710"
+    "gitHead": "055e2a716cf3e946add92e953e136835730bc5fc"
 }

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

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

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

@@ -0,0 +1,200 @@
+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);
+    }
+}
+
+interface NamespaceConfig {
+    eventName: string;
+    queue: string;
+    indicator: string;
+    replay: (
+        element: EventTarget,
+        event: string,
+        payload: Record<string, unknown>
+    ) => void;
+}
+
+// The two tracking-event namespaces dx-instrumentation can bridge. Keyed by the
+// values accepted by the `namespaces` attribute.
+const NAMESPACE_CONFIGS: Record<"developer" | "architect", NamespaceConfig> = {
+    developer: {
+        eventName: DX_TRACKING_EVENT_NAME,
+        queue: DX_LISTENER_QUEUE,
+        indicator: DX_LISTENER_INDICATOR,
+        replay: dxTrack
+    },
+    architect: {
+        eventName: ARCH_TRACKING_EVENT_NAME,
+        queue: ARCH_LISTENER_QUEUE,
+        indicator: ARCH_LISTENER_INDICATOR,
+        replay: archTrack
+    }
+};
+
+// Maps the `namespaces` attribute to the configs it activates.
+function resolveNamespaceConfigs(namespaces: string): NamespaceConfig[] {
+    switch (namespaces) {
+        case "developer":
+            return [NAMESPACE_CONFIGS.developer];
+        case "architect":
+            return [NAMESPACE_CONFIGS.architect];
+        case "both":
+        default:
+            return [NAMESPACE_CONFIGS.developer, NAMESPACE_CONFIGS.architect];
+    }
+}
+
+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 each of the given tracking event names (e.g.
+ * `developerwebsite_track` and/or `architectssite_track`), forwarding every
+ * caught event to every tracker function. A single component can therefore
+ * bridge one or both event namespaces into the dataLayer.
+ */
+export function instrumentationTrackEventListener(
+    trackerFns: { track: (e: Event) => void }[] = [],
+    eventNames: string[] = [DX_TRACKING_EVENT_NAME, ARCH_TRACKING_EVENT_NAME]
+): TrackEventListener {
+    if (trackerFns.length === 0) {
+        throw new Error("No tracker functions passed");
+    }
+
+    const handleTrackEvent = (e: Event) => {
+        trackerFns.forEach((tracker) => {
+            tracker.track(e);
+        });
+    };
+
+    const attachEventListener = () => {
+        eventNames.forEach((eventName) => {
+            document.addEventListener(eventName, handleTrackEvent);
+        });
+    };
+
+    const removeEventListener = () => {
+        eventNames.forEach((eventName) => {
+            document.removeEventListener(eventName, handleTrackEvent);
+        });
+    };
+
+    return {
+        add: attachEventListener,
+        remove: removeEventListener
+    };
+}
+
+/**
+ * Unified instrumentation bridge. Mount a single <dx-instrumentation> to forward
+ * developer-website and/or architect-website tracking events into the GTM
+ * dataLayer. Renders nothing.
+ *
+ * By default (`namespaces="both"`) it bridges both the developer
+ * (`developerwebsite_track`) and architect (`architectssite_track`) namespaces,
+ * replacing the need to mount <dw-instrumentation> and <arch-instrumentation>
+ * separately. Set `namespaces="developer"` (or `"architect"`) to bridge only one
+ * — e.g. on a site whose header analytics already reach the dataLayer through
+ * another path, so draining the architect queue here would double-count.
+ */
+export default class Instrumentation extends LightningElement {
+    @api useGoogleTagManager = false;
+
+    // "both" (default) | "developer" | "architect"
+    @api namespaces = "both";
+
+    private tracker: TrackEventListener | null = null;
+
+    private setupTracker() {
+        const configs = resolveNamespaceConfigs(this.namespaces);
+        const trackerFunctions = this.useGoogleTagManager
+            ? [googleTagManager]
+            : [];
+        this.tracker = instrumentationTrackEventListener(
+            trackerFunctions,
+            configs.map((c) => c.eventName)
+        );
+        this.tracker.add();
+        // Mark each active namespace initialized so track() calls from that
+        // stack dispatch live events instead of queueing.
+        configs.forEach((c) => {
+            (window as any)[c.indicator] = true;
+        });
+    }
+
+    private dispatchQueuedEvents() {
+        resolveNamespaceConfigs(this.namespaces).forEach((config) => {
+            const queue = (window as any)[config.queue];
+            if (Array.isArray(queue)) {
+                while (queue.length > 0) {
+                    const event = queue.pop() as {
+                        event: string;
+                        payload: Record<string, unknown>;
+                    };
+                    config.replay(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;
+        }
+    }
+}