@guardian/ophan-tracker-js 2.2.9 → 2.3.0

package/NPM-dist/click-path-capture.js

@@ -39,10 +39,38 @@ const getDataLinkNames = (el, dataLinkNames = []) => {
         dataLinkNames.push(dataLinkName);
     return getDataLinkNames(el.parentNode, dataLinkNames);
 };
+/**
+ * Manually track a click event on an element.
+ * Useful for elements that stop propagation or need explicit tracking.
+ *
+ * @param {Element} element - The element that was clicked.
+ */
+export const trackClickComponentEvent = (element) => {
+    if (!element)
+        return;
+    const info = {
+        from: [location.protocol, '//', location.host, location.pathname].join(''),
+        to: element.href || undefined,
+        referringComponent: getContainingComponent(element),
+        referringDataLinkNames: getDataLinkNames(element),
+        refPlatform: ophan.servingPlatform(),
+        refViewId: ophan.viewId,
+    };
+    if (info.referringDataLinkNames && info.referringDataLinkNames.length > 0) {
+        transmit.sendMore({
+            clickComponent: info.referringComponent,
+            clickLinkNames: info.referringDataLinkNames,
+        });
+    }
+    // If it's an anchor, store data for next page
+    const anchorTarget = validAncestorAnchorElement(element);
+    if (anchorTarget) {
+        ophan.storeDataToSendOnNextEvent(info);
+    }
+};
 if (typeof document.addEventListener === 'function') {
     document.addEventListener('click', function (e) {
         let target = e.target;
-        let info;
         // For anchors, use validAncestorAnchorElement
         const anchorTarget = validAncestorAnchorElement(target);
         const nonTrackableElements = [
@@ -62,26 +90,10 @@ if (typeof document.addEventListener === 'function') {
         }
         // If it's an anchor, use anchorTarget, otherwise use the original target
         const trackingTarget = anchorTarget || target;
-        info = {
-            from: [location.protocol, '//', location.host, location.pathname].join(''),
-            to: trackingTarget.href || undefined,
-            referringComponent: getContainingComponent(trackingTarget),
-            referringDataLinkNames: getDataLinkNames(trackingTarget),
-            refPlatform: ophan.servingPlatform(),
-            refViewId: ophan.viewId,
-        };
-        if (info.referringDataLinkNames && info.referringDataLinkNames.length > 0) {
-            transmit.sendMore({
-                clickComponent: info.referringComponent,
-                clickLinkNames: info.referringDataLinkNames,
-            });
-        }
-        if (anchorTarget) {
-            // If it's an anchor, we may be about to navigate away from this page, so store to send on next request
-            return ophan.storeDataToSendOnNextEvent(info);
-        }
+        trackClickComponentEvent(trackingTarget);
     }, false);
 }
 export default {
     getDataLinkNames: getDataLinkNames,
+    trackClickComponentEvent: trackClickComponentEvent,
 };

package/NPM-dist/ng.js

@@ -20,6 +20,7 @@ export * from './types/consent.js';
 export * from './types/component-type.js';
 export * from './types/component-event.js';
 export * from './types/event.js';
+import { trackClickComponentEvent } from "./click-path-capture.js";
 let ng;
 if (window.guardian && window.guardian.ophan) {
     ng = window.guardian.ophan;
@@ -40,6 +41,7 @@ else {
         record: transmit.sendMore,
         viewId: transmit.viewId,
         pageViewId: transmit.viewId,
+        trackClickComponentEvent: trackClickComponentEvent,
     };
     ng = window.guardian.ophan;
 }

package/NPM-dist/tests/click-path-capture.test.js

@@ -1,4 +1,4 @@
-import clickPathCapture, { getContainingComponent, validAncestorAnchorElement, } from '../click-path-capture.js';
+import clickPathCapture, { getContainingComponent, validAncestorAnchorElement, trackClickComponentEvent, } from '../click-path-capture.js';
 import ophan from '../core.js';
 import transmit from '../transmit.js';
 const { getDataLinkNames } = clickPathCapture;
@@ -115,4 +115,213 @@ describe('click-path-capture.js', () => {
             expect(ophanStoreDataToSendOnNextEventSpy).not.toHaveBeenCalled();
         });
     });
+    describe('trackClickComponentEvent', () => {
+        let transmitSendMoreSpy, ophanStoreDataToSendOnNextEventSpy;
+        beforeEach(() => {
+            jest.clearAllMocks();
+            transmitSendMoreSpy = jest
+                .spyOn(transmit, 'sendMore')
+                .mockImplementation(() => { });
+            ophanStoreDataToSendOnNextEventSpy = jest
+                .spyOn(ophan, 'storeDataToSendOnNextEvent')
+                .mockImplementation(() => { });
+            jest.spyOn(ophan, 'servingPlatform').mockReturnValue('web');
+            ophan.viewId = 'test-view-id';
+        });
+        afterEach(() => {
+            jest.clearAllMocks();
+        });
+        test('should handle null or undefined element gracefully', () => {
+            trackClickComponentEvent(null);
+            trackClickComponentEvent(undefined);
+            expect(transmitSendMoreSpy).not.toHaveBeenCalled();
+            expect(ophanStoreDataToSendOnNextEventSpy).not.toHaveBeenCalled();
+        });
+        test('should track clicks on buttons with nested elements (play button scenario)', () => {
+            document.body.innerHTML = `
+                <div data-component="looping-video">
+                    <button id="playButton" data-link-name="video-play-pause">
+                        <div class="play-icon">
+                            <svg id="playIcon">...</svg>
+                        </div>
+                    </button>
+                </div>
+            `;
+            const button = document.getElementById('playButton');
+            trackClickComponentEvent(button);
+            expect(transmitSendMoreSpy).toHaveBeenCalledWith({
+                clickComponent: 'looping-video',
+                clickLinkNames: ['video-play-pause'],
+            });
+            expect(ophanStoreDataToSendOnNextEventSpy).not.toHaveBeenCalled();
+        });
+        test('should track clicks with stopPropagation (mute button scenario)', () => {
+            document.body.innerHTML = `
+                <div data-component="looping-video">
+                    <button id="muteButton" data-link-name="video-mute-toggle">
+                        <div class="audio-icon-container">
+                            <span>Mute</span>
+                        </div>
+                    </button>
+                </div>
+            `;
+            const button = document.getElementById('muteButton');
+            // Simulate a click handler that stops propagation
+            button.addEventListener('click', (e) => {
+                e.stopPropagation();
+                // Manually track the click since propagation is stopped
+                trackClickComponentEvent(e.currentTarget);
+            });
+            button.click();
+            expect(transmitSendMoreSpy).toHaveBeenCalledWith({
+                clickComponent: 'looping-video',
+                clickLinkNames: ['video-mute-toggle'],
+            });
+            expect(ophanStoreDataToSendOnNextEventSpy).not.toHaveBeenCalled();
+        });
+        test('should collect multiple data-link-names from nested components', () => {
+            document.body.innerHTML = `
+                <div data-component="outer-component" data-link-name="outer-link">
+                    <div data-link-name="middle-link">
+                        <button id="nestedButton" data-link-name="button-link">
+                            Click Me
+                        </button>
+                    </div>
+                </div>
+            `;
+            const button = document.getElementById('nestedButton');
+            trackClickComponentEvent(button);
+            expect(transmitSendMoreSpy).toHaveBeenCalledWith({
+                clickComponent: 'outer-component',
+                clickLinkNames: ['button-link', 'middle-link', 'outer-link'],
+            });
+        });
+        test('should handle anchor elements and store data for next event', () => {
+            document.body.innerHTML = `
+                <div data-component="navigation">
+                    <a id="testAnchor" href="/next-page" data-link-name="nav-link">
+                        Next Page
+                    </a>
+                </div>
+            `;
+            const anchor = document.getElementById('testAnchor');
+            trackClickComponentEvent(anchor);
+            expect(transmitSendMoreSpy).toHaveBeenCalledWith({
+                clickComponent: 'navigation',
+                clickLinkNames: ['nav-link'],
+            });
+            expect(ophanStoreDataToSendOnNextEventSpy).toHaveBeenCalledWith({
+                from: 'http://localhost/',
+                to: 'http://localhost/next-page',
+                referringComponent: 'navigation',
+                referringDataLinkNames: ['nav-link'],
+                refPlatform: 'web',
+                refViewId: 'test-view-id',
+            });
+        });
+        test('should handle nested anchors correctly', () => {
+            document.body.innerHTML = `
+                <div data-component="content">
+                    <a id="outerAnchor" href="/outer" data-link-name="outer-anchor">
+                        <span id="innerSpan" data-link-name="inner-span">Click me</span>
+                    </a>
+                </div>
+            `;
+            const span = document.getElementById('innerSpan');
+            trackClickComponentEvent(span);
+            expect(transmitSendMoreSpy).toHaveBeenCalledWith({
+                clickComponent: 'content',
+                clickLinkNames: ['inner-span', 'outer-anchor'],
+            });
+            expect(ophanStoreDataToSendOnNextEventSpy).toHaveBeenCalledWith({
+                from: 'http://localhost/',
+                to: undefined, // span elements don't have href
+                referringComponent: 'content',
+                referringDataLinkNames: ['inner-span', 'outer-anchor'],
+                refPlatform: 'web',
+                refViewId: 'test-view-id',
+            });
+        });
+        test('should not send data if no data-link-names are present', () => {
+            document.body.innerHTML = `
+                <div data-component="empty-component">
+                    <button id="emptyButton">No tracking data</button>
+                </div>
+            `;
+            const button = document.getElementById('emptyButton');
+            trackClickComponentEvent(button);
+            expect(transmitSendMoreSpy).not.toHaveBeenCalled();
+            expect(ophanStoreDataToSendOnNextEventSpy).not.toHaveBeenCalled();
+        });
+        test('should handle elements without component correctly', () => {
+            document.body.innerHTML = `
+                <button id="orphanButton" data-link-name="orphan-link">
+                    Orphan Button
+                </button>
+            `;
+            const button = document.getElementById('orphanButton');
+            trackClickComponentEvent(button);
+            expect(transmitSendMoreSpy).toHaveBeenCalledWith({
+                clickComponent: null,
+                clickLinkNames: ['orphan-link'],
+            });
+        });
+        test('should handle real-world scenario with video controls (auto-looping videos in dotcom)', () => {
+            document.body.innerHTML = `
+                <div data-component="video-player" data-link-name="main-video">
+                    <div class="video-container" data-link-name="video-container">
+                        <video id="video" src="video.mp4"></video>
+                        <div class="controls">
+                            <button id="playPauseBtn" data-link-name="play-pause">
+                                <div class="icon-wrapper">
+                                    <svg class="play-icon">...</svg>
+                                </div>
+                            </button>
+                            <button id="muteBtn" data-link-name="mute-toggle">
+                                <div class="icon-wrapper">
+                                    <svg class="mute-icon">...</svg>
+                                </div>
+                            </button>
+                        </div>
+                    </div>
+                </div>
+            `;
+            // Test play button tracking
+            const playButton = document.getElementById('playPauseBtn');
+            trackClickComponentEvent(playButton);
+            expect(transmitSendMoreSpy).toHaveBeenCalledWith({
+                clickComponent: 'video-player',
+                clickLinkNames: ['play-pause', 'video-container', 'main-video'],
+            });
+            transmitSendMoreSpy.mockClear();
+            // Test mute button tracking
+            const muteButton = document.getElementById('muteBtn');
+            trackClickComponentEvent(muteButton);
+            expect(transmitSendMoreSpy).toHaveBeenCalledWith({
+                clickComponent: 'video-player',
+                clickLinkNames: ['mute-toggle', 'video-container', 'main-video'],
+            });
+        });
+        test('should handle currentTarget from event objects', () => {
+            document.body.innerHTML = `
+                <div data-component="interactive-element">
+                    <button id="eventButton" data-link-name="event-button">
+                        <span>Click Target</span>
+                    </button>
+                </div>
+            `;
+            const button = document.getElementById('eventButton');
+            const span = button.querySelector('span');
+            // Simulate clicking the span but tracking the button (currentTarget)
+            const mockEvent = new MouseEvent('click', { bubbles: true });
+            Object.defineProperty(mockEvent, 'target', { value: span });
+            Object.defineProperty(mockEvent, 'currentTarget', { value: button });
+            // This mimics: trackClickComponentEvent(event.currentTarget)
+            trackClickComponentEvent(button);
+            expect(transmitSendMoreSpy).toHaveBeenCalledWith({
+                clickComponent: 'interactive-element',
+                clickLinkNames: ['event-button'],
+            });
+        });
+    });
 });

package/NPM-dist/types/click-path-capture.d.ts

@@ -1,7 +1,9 @@
 export function validAncestorAnchorElement(el: Element): Element | null;
 export function getContainingComponent(el: Element): string | null;
+export function trackClickComponentEvent(element: Element): void;
 declare namespace _default {
     export { getDataLinkNames };
+    export { trackClickComponentEvent };
 }
 export default _default;
 /**

package/NPM-dist/types/ng.d.ts

@@ -21,6 +21,7 @@ interface NG {
     viewId: string;
     trackComponentAttention: (name: string, el: HTMLElement, visibilityThreshold: number) => void;
     setEventEmitter: (event: Object) => void;
+    trackClickComponentEvent: (element: Element) => void;
 }
 declare let ng: NG;
 export default ng;

package/NPM-dist/types/types/component-event.d.ts

@@ -51,7 +51,7 @@ export type TAction =
 /**
  * User Consent
  **/
- | 'ACCEPT_DEFAULT_CONSENT' | 'MANAGE_CONSENT' | 'CONSENT_ACCEPT_ALL' | 'CONSENT_REJECT_ALL'
+ | 'ACCEPT_DEFAULT_CONSENT' | 'MANAGE_CONSENT' | 'CONSENT_ACCEPT_ALL' | 'CONSENT_REJECT_ALL' | 'CONSENT_GEOLOCATION_MISMATCH'
 /**
  * The component sticks in the screen
  **/

package/NPM-dist/types/types/component-type.d.ts

@@ -1 +1 @@
-export type TComponentType = "READERS_QUESTIONS_ATOM" | "QANDA_ATOM" | "PROFILE_ATOM" | "GUIDE_ATOM" | "TIMELINE_ATOM" | "NEWSLETTER_SUBSCRIPTION" | "SURVEYS_QUESTIONS" | "ACQUISITIONS_EPIC" | "ACQUISITIONS_ENGAGEMENT_BANNER" | "ACQUISITIONS_THANK_YOU_EPIC" | "ACQUISITIONS_HEADER" | "ACQUISITIONS_FOOTER" | "ACQUISITIONS_INTERACTIVE_SLICE" | "ACQUISITIONS_NUGGET" | "ACQUISITIONS_STANDFIRST" | "ACQUISITIONS_THRASHER" | "ACQUISITIONS_EDITORIAL_LINK" | "ACQUISITIONS_MANAGE_MY_ACCOUNT" | "ACQUISITIONS_BUTTON" | "ACQUISITIONS_OTHER" | "APP_ADVERT" | "APP_AUDIO" | "APP_BUTTON" | "APP_CARD" | "APP_CROSSWORDS" | "APP_ENGAGEMENT_BANNER" | "APP_EPIC" | "APP_GALLERY" | "APP_LINK" | "APP_NAVIGATION_ITEM" | "APP_SCREEN" | "APP_THRASHER" | "APP_VIDEO" | "AUDIO_ATOM" | "CHART_ATOM" | "ACQUISITIONS_MERCHANDISING" | "ACQUISITIONS_HOUSE_ADS" | "SIGN_IN_GATE" | "ACQUISITIONS_SUBSCRIPTIONS_BANNER" | "MOBILE_STICKY_AD" | "IDENTITY_AUTHENTICATION" | "RETENTION_ENGAGEMENT_BANNER" | "ACQUISITION_SUPPORT_SITE" | "RETENTION_EPIC" | "CONSENT" | "LIVE_BLOG_PINNED_POST" | "STICKY_VIDEO" | "KEY_EVENT_CARD" | "RETENTION_HEADER" | "SLIDESHOW" | "APP_FEATURE" | "CARD" | "CAROUSEL" | "CONTAINER" | "MENU" | "ACQUISITIONS_GUTTER";
+export type TComponentType = "READERS_QUESTIONS_ATOM" | "QANDA_ATOM" | "PROFILE_ATOM" | "GUIDE_ATOM" | "TIMELINE_ATOM" | "NEWSLETTER_SUBSCRIPTION" | "SURVEYS_QUESTIONS" | "ACQUISITIONS_EPIC" | "ACQUISITIONS_ENGAGEMENT_BANNER" | "ACQUISITIONS_THANK_YOU_EPIC" | "ACQUISITIONS_HEADER" | "ACQUISITIONS_FOOTER" | "ACQUISITIONS_INTERACTIVE_SLICE" | "ACQUISITIONS_NUGGET" | "ACQUISITIONS_STANDFIRST" | "ACQUISITIONS_THRASHER" | "ACQUISITIONS_EDITORIAL_LINK" | "ACQUISITIONS_MANAGE_MY_ACCOUNT" | "ACQUISITIONS_BUTTON" | "ACQUISITIONS_OTHER" | "APP_ADVERT" | "APP_AUDIO" | "APP_BUTTON" | "APP_CARD" | "APP_CROSSWORDS" | "APP_ENGAGEMENT_BANNER" | "APP_EPIC" | "APP_GALLERY" | "APP_LINK" | "APP_NAVIGATION_ITEM" | "APP_SCREEN" | "APP_THRASHER" | "APP_VIDEO" | "AUDIO_ATOM" | "CHART_ATOM" | "ACQUISITIONS_MERCHANDISING" | "ACQUISITIONS_HOUSE_ADS" | "SIGN_IN_GATE" | "ACQUISITIONS_SUBSCRIPTIONS_BANNER" | "MOBILE_STICKY_AD" | "IDENTITY_AUTHENTICATION" | "RETENTION_ENGAGEMENT_BANNER" | "ACQUISITION_SUPPORT_SITE" | "RETENTION_EPIC" | "CONSENT" | "LIVE_BLOG_PINNED_POST" | "STICKY_VIDEO" | "KEY_EVENT_CARD" | "RETENTION_HEADER" | "SLIDESHOW" | "APP_FEATURE" | "CARD" | "CAROUSEL" | "CONTAINER" | "MENU" | "ACQUISITIONS_GUTTER" | "INTERACTIVE_ATOM" | 'LOOP_VIDEO';

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@guardian/ophan-tracker-js",
-	"version": "2.2.9",
+	"version": "2.3.0",
 	"type": "module",
 	"engines": {
 		"node": ">=16"

package/readme.md

@@ -20,7 +20,7 @@ Tracker JS contains multiple entry point files tailored to specific platforms. T
 **Default Behaviour**
 
 The [default entry point](https://github.com/guardian/ophan/blob/main/tracker-js/package.json#L12) for the library is `ng.js`. With this entry point, the library automatically initializes itself on the global window object and provides a suite of functionalities to monitor user interactions, visibility, and more. 
-The library will send an initial [page view event](./types/event.ts#L15) on page load. You are then in control of sending other events to Ophan.
+The library will send an initial [page view event](/tracker-js/src/types/event.ts#L15) on page load. You are then in control of sending other events to Ophan.
 
 You can see example usage of the library on theguardian.com [here](https://github.com/guardian/dotcom-rendering/blob/main/dotcom-rendering/src/client/ophan/ophan.ts)
 
@@ -42,7 +42,7 @@ You can see example usage of the library on theguardian.com [here](https://githu
 
 ### Usage with Typescript
 
-Refer to the type definitions within the library for the structure of valid tracking events.  The `ophan.record()` function accepts a type of `EventPayload` found [here]("https://github.com/guardian/ophan/blob/main/tracker-js/src/types/event.ts#L90"). 
+Refer to the type definitions within the library for the structure of valid tracking events.  The `ophan.record()` function accepts a type of `EventPayload` found [here](/tracker-js/src/types/event.ts#L90). 
 
 #### Example Usage