@salesforcedevs/dx-components 1.38.0 → 1.39.0

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@salesforcedevs/dx-components",
-    "version": "1.38.0",
+    "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": "fc9d953dd79b76e37578fc43691fa56d6c4dd028"
+    "gitHead": "055e2a716cf3e946add92e953e136835730bc5fc"
 }

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

@@ -38,6 +38,47 @@ function archTrack(
     }
 }
 
+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) {
@@ -54,13 +95,14 @@ interface TrackEventListener {
 }
 
 /**
- * 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.
+ * 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 }[] = []
+    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");
@@ -73,16 +115,15 @@ export function instrumentationTrackEventListener(
     };
 
     const attachEventListener = () => {
-        document.addEventListener(DX_TRACKING_EVENT_NAME, handleTrackEvent);
-        document.addEventListener(ARCH_TRACKING_EVENT_NAME, handleTrackEvent);
+        eventNames.forEach((eventName) => {
+            document.addEventListener(eventName, handleTrackEvent);
+        });
     };
 
     const removeEventListener = () => {
-        document.removeEventListener(DX_TRACKING_EVENT_NAME, handleTrackEvent);
-        document.removeEventListener(
-            ARCH_TRACKING_EVENT_NAME,
-            handleTrackEvent
-        );
+        eventNames.forEach((eventName) => {
+            document.removeEventListener(eventName, handleTrackEvent);
+        });
     };
 
     return {
@@ -93,49 +134,54 @@ export function instrumentationTrackEventListener(
 
 /**
  * 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.
+ * 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);
+        this.tracker = instrumentationTrackEventListener(
+            trackerFunctions,
+            configs.map((c) => c.eventName)
+        );
         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;
+        // 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() {
-        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);
+        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);
+                }
             }
-        }
-
-        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() {