@guardian/ophan-tracker-js 2.3.1 → 2.4.0

package/NPM-dist/attention.js

@@ -38,11 +38,13 @@ let unrecordedAttentionStarted = null;
 let reportedTotalAttentionMs = null; // setting null here forces a first report of attention time, even if it's only 0ms
 // the decay timer if we've set one
 let decayTimerId = null;
-// is video currently playing?
+// is a video currently playing?
 let videoPlaying = false;
-// Helper function to check if any video components are tracking and video is not playing
-const shouldBlockVideoTracking = () => {
-    return components.some(component => component.isTrackingVideo && component.visible) && !videoPlaying;
+// Helper function to check if any video components are tracking, is that video in view and not playing
+const shouldBlockVideoComponentTracking = () => {
+    const isTrackedVideoInView = components.some(component => component.isTrackingVideo && component.visible);
+    const shouldBlockVideoTracking = isTrackedVideoInView && !videoPlaying;
+    return shouldBlockVideoTracking;
 };
 const cancelDecayTimer = () => {
     if (decayTimerId != null) {
@@ -51,20 +53,25 @@ const cancelDecayTimer = () => {
     decayTimerId = null;
 };
 const makeActive = () => {
-    // if we have video components that are visible and video is not playing, do not start monitoring
-    if (shouldBlockVideoTracking()) {
-        return;
-    }
+    // Always update global attention
     if (unrecordedAttentionStarted == null) {
         unrecordedAttentionStarted = performance.now();
     }
-    componentUtils.startMonitoring();
+    // reset decay time as the page has been considered "active"
     cancelDecayTimer();
     decayTimerId = window.setTimeout(() => {
         if (!videoPlaying) {
             makeInactive();
         }
     }, ATTENTIONDECAY);
+    // Only start component monitoring if allowed
+    const blockVideoComponentTracking = shouldBlockVideoComponentTracking();
+    if (blockVideoComponentTracking) {
+        componentUtils.stopVideoComponentMonitoring();
+    }
+    else {
+        componentUtils.startMonitoring(videoPlaying);
+    }
 };
 const incrementTotalAttentionTimeByUnrecordedAmount = () => {
     if (unrecordedAttentionStarted != null) {
@@ -113,13 +120,13 @@ const initAttention = (visibility) => {
         videoPlaying = true;
         makeActive();
     });
-    document.addEventListener('videoEnded', () => {
+    document.addEventListener('videoPause', () => {
         videoPlaying = false;
-        makeInactive();
+        componentUtils.stopVideoComponentMonitoring();
     });
-    document.addEventListener('videoPause', () => {
+    document.addEventListener('videoEnded', () => {
         videoPlaying = false;
-        makeInactive();
+        componentUtils.stopVideoComponentMonitoring();
     });
     window.setTimeout(reporter, 100);
     window.setInterval(reporter, REPORTINGINTERVAL);

package/NPM-dist/components.js

@@ -3,12 +3,33 @@
  */
 export const components = [];
 /**
- * theguardian.com uses a custom scroll event for performance reasons.
- * We pass in the event emitter so that we can listen to this custom scroll event.
- * If not on theguardian.com, we default to the native scroll event
- * @type {Object|null}
+ * Map from threshold value to its corresponding IntersectionObserver
+ * Each observer handles all components that share the same threshold.
+ * This allows us to support multiple thresholds.
  */
-let eventEmitter = null;
+const observerMap = new Map();
+/**
+ * Returns (or creates) a shared IntersectionObserver for the given threshold.
+ * @param {number} threshold - The visibility ratio required
+ * @returns {IntersectionObserver}
+ */
+const getOrCreateObserver = (threshold) => {
+    if (observerMap.has(threshold))
+        return observerMap.get(threshold);
+    const observer = new IntersectionObserver((entries) => {
+        for (const entry of entries) {
+            const component = components.find(c => c.element === entry.target);
+            if (!component)
+                continue;
+            const isVisible = entry.intersectionRatio >= component.visibilityThreshold;
+            component.handleVisibilityChange(isVisible);
+        }
+    }, {
+        threshold: [threshold],
+    });
+    observerMap.set(threshold, observer);
+    return observer;
+};
 // Tracks attention time of elements on the page with data-component attributes.
 // This should always be less than or equal to the page attention time.
 // If the page does not have attention, no component has attention.
@@ -19,19 +40,19 @@ class Component {
      * Component constructor.
      * @param {string} name - The name of the component.
      * @param {HTMLElement} element - The DOM element of the component.
-     * @param {number} visibilityThreshold1 -
+     * @param {number} visibilityThreshold -
      *    visibilityThreshold represents the fraction of each component that must
      *    be in the viewport before it is considered visible.
      *    e.g. 0.5 means that half the height or width must be in the viewport
      *    1 means that the entire element must be in the viewport
-     * @param {number} reportingInterval1 - ??
-     * @param {boolean} isTrackingVideo - Whether this component is tracking video attention
+     * @param {number} reportingInterval - How often attention is reported.
+     * @param {boolean} isTrackingVideo - Whether this component is a video.
      */
-    constructor(name, element, visibilityThreshold1, reportingInterval1, isTrackingVideo = false) {
+    constructor(name, element, visibilityThreshold, reportingInterval, isTrackingVideo = false) {
         this.name = name;
         this.element = element;
-        this.visibilityThreshold = visibilityThreshold1;
-        this.reportingInterval = reportingInterval1;
+        this.visibilityThreshold = visibilityThreshold;
+        this.reportingInterval = reportingInterval;
         this.isTrackingVideo = isTrackingVideo;
         this.visible = false;
         // total attention time so far for this element
@@ -43,72 +64,28 @@ class Component {
         this.unrecordedAttentionStarted = null;
         // the attention time when getAttentionTime() was last called
         this.reportedTotalAttentionMs = 0;
-        this.usingEmitter = false;
-        this.visCheck = this.checkVisibility.bind(this);
-        if (eventEmitter != null) {
-            this.usingEmitter = true;
-            eventEmitter.on('window:throttledScroll', this.visCheck);
-        }
-        else {
-            window.addEventListener('scroll', this.visCheck);
-        }
-        window.addEventListener('resize', this.visCheck);
+        getOrCreateObserver(this.visibilityThreshold).observe(this.element);
     }
-    isVisible(threshold = 1) {
-        if (!this.element.offsetParent) {
-            // exclude hidden elements
-            // will also exclude position: fixed elements but we don't care about these
-            // (because their attention time would always be the same as the whole page)
-            // https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/offsetParent
-            return false;
-        }
-        const box = this.element.getBoundingClientRect();
-        const width = box.width;
-        const height = box.height;
-        const windowHeight = window.innerHeight || document.documentElement.clientHeight;
-        const windowWidth = window.innerWidth || document.documentElement.clientWidth;
-        return (box.left >= -(width * (1 - threshold)) &&
-            box.top >= -(height * (1 - threshold)) &&
-            box.right <= windowWidth + width * (1 - threshold) &&
-            box.bottom <= windowHeight + height * (1 - threshold));
-    }
-    visibilityHasChanged() {
+    handleVisibilityChange(isNowVisible) {
         const wasVisible = this.visible;
-        this.visible = this.isVisible(this.visibilityThreshold);
-        return wasVisible !== this.visible;
-    }
-    rebindToEventEmitter() {
-        if (!this.usingEmitter && eventEmitter != null) {
-            window.removeEventListener('scroll', this.visCheck);
-            this.usingEmitter = true;
-            return eventEmitter.on('window:throttledScroll', this.visCheck);
-        }
-    }
-    checkVisibility() {
-        this.rebindToEventEmitter();
-        if (this.visibilityHasChanged()) {
-            return this.visible ? this.makeActive() : this.makeInactive();
+        this.visible = isNowVisible;
+        if (wasVisible !== isNowVisible) {
+            if (isNowVisible) {
+                this.makeActive();
+            }
+            else {
+                this.makeInactive();
+            }
         }
     }
     makeActive() {
-        // mark when the latest period of attention began,
-        // if we're not already in an attention period
-        return this.unrecordedAttentionStarted != null
-            ? this.unrecordedAttentionStarted
-            : (this.unrecordedAttentionStarted = performance.now());
+        if (this.unrecordedAttentionStarted == null) {
+            this.unrecordedAttentionStarted = performance.now();
+        }
     }
     makeInactive() {
         this.incrementTotalAttentionTimeByUnrecordedAmount();
-        return (this.unrecordedAttentionStarted = null);
-    }
-    hadAttentionSinceLastGet() {
-        this.incrementTotalAttentionTimeByUnrecordedAmount();
-        return this.totalAttentionMs !== this.reportedTotalAttentionMs;
-    }
-    getAttentionTime() {
-        this.incrementTotalAttentionTimeByUnrecordedAmount();
-        this.reportedTotalAttentionMs = this.totalAttentionMs;
-        return this.totalAttentionMs;
+        this.unrecordedAttentionStarted = null;
     }
     incrementTotalAttentionTimeByUnrecordedAmount() {
         if (this.unrecordedAttentionStarted != null) {
@@ -118,17 +95,29 @@ class Component {
             // crazy big values!
             const unrecordedMs = Math.min(now - this.unrecordedAttentionStarted, this.reportingInterval);
             this.totalAttentionMs += unrecordedMs;
-            return (this.unrecordedAttentionStarted = now);
+            this.unrecordedAttentionStarted = now;
         }
     }
+    hadAttentionSinceLastGet() {
+        this.incrementTotalAttentionTimeByUnrecordedAmount();
+        return this.totalAttentionMs !== this.reportedTotalAttentionMs;
+    }
+    getAttentionTime() {
+        this.incrementTotalAttentionTimeByUnrecordedAmount();
+        this.reportedTotalAttentionMs = this.totalAttentionMs;
+        return this.totalAttentionMs;
+    }
 }
 /**
  * Begins monitoring the components on the page for attention time.
+ * We begin monitoring if the following conditions are met
+ * 1. the component is visible within the threshold set.
+ * 2. the component is not a video OR is a video which is playing
  * @returns {Array} Array of results from makeActive() for each visible component.
  */
-const startMonitoring = () => {
+const startMonitoring = (videoPlaying = false) => {
     return components
-        .filter((component) => component.isVisible())
+        .filter((component) => component.visible && (!component.isTrackingVideo || videoPlaying))
         .map((component) => component.makeActive());
 };
 /**
@@ -138,6 +127,24 @@ const startMonitoring = () => {
 const stopMonitoring = () => {
     return components.map((component) => component.makeInactive());
 };
+/**
+ * Stops monitoring a video on the page for attention time.
+ * This allows us to bypass the decay timer and explicitly stop monitoring video
+ * when the user is not playing the video (ie on video pause or video end) if
+ * the user is explicitly tracking a video component.
+ * @returns {Array} Array of results from makeInactive() for each component.
+ */
+const stopVideoComponentMonitoring = () => {
+    return components
+        .filter(component => component.isTrackingVideo)
+        .map(component => {
+        if (component.unrecordedAttentionStarted != null) {
+            return component.makeInactive();
+        }
+        return null;
+    })
+        .filter(result => result !== null);
+};
 /**
  * Retrieves the attention times for all components.
  * @returns {Object}
@@ -153,17 +160,13 @@ const getAttentionTimes = () => {
     return obj;
 };
 export default {
-    /**
-     * @param {Object} emitter - The event emitter to set.
-     * @returns {Object}
-     */
-    setEventEmitter: function (emitter) {
-        return (eventEmitter = emitter);
-    },
     startMonitoring,
     stopMonitoring,
+    stopVideoComponentMonitoring,
     getAttentionTimes,
-    /** @type {(...args: ConstructorParameters<typeof Component>) => void} */
+    /**
+     * @type {(...args: ConstructorParameters<typeof Component>) => void}
+     */
     registerComponent: function (name, el, visibilityThreshold, reportingInterval, isTrackingVideo = false) {
         return components.push(new Component(name, el, visibilityThreshold, reportingInterval, isTrackingVideo));
     },

package/NPM-dist/tests/attention.test.js

@@ -176,7 +176,7 @@ describe('attention.js', () => {
             const videoEndedHandler = document.addEventListener.mock.calls.find(call => call[0] === 'videoEnded')[1];
             videoEndedHandler();
             // Should stop monitoring
-            expect(componentUtils.stopMonitoring).toHaveBeenCalled();
+            expect(componentUtils.stopVideoComponentMonitoring).toHaveBeenCalled();
         });
         test('should stop monitoring when video is paused', () => {
             // Initialize attention system
@@ -192,7 +192,7 @@ describe('attention.js', () => {
             const videoPauseHandler = document.addEventListener.mock.calls.find(call => call[0] === 'videoPause')[1];
             videoPauseHandler();
             // Should stop monitoring
-            expect(componentUtils.stopMonitoring).toHaveBeenCalled();
+            expect(componentUtils.stopVideoComponentMonitoring).toHaveBeenCalled();
         });
     });
     describe('mixed component scenarios', () => {

package/NPM-dist/tests/components.test.js

@@ -6,7 +6,7 @@ describe('components.js', () => {
         components.length = 0;
         components.push({
             name: 'comp1',
-            isVisible: jest.fn().mockReturnValue(true),
+            visible: true,
             makeActive: jest.fn(),
             makeInactive: jest.fn(),
             hadAttentionSinceLastGet: jest.fn().mockReturnValue(true),
@@ -14,7 +14,7 @@ describe('components.js', () => {
         });
         components.push({
             name: 'comp2',
-            isVisible: jest.fn().mockReturnValue(true),
+            visible: false,
             makeActive: jest.fn(),
             makeInactive: jest.fn(),
             hadAttentionSinceLastGet: jest.fn().mockReturnValue(true),
@@ -22,8 +22,6 @@ describe('components.js', () => {
         });
     });
     test('startMonitoring activates visible components', () => {
-        components[0].isVisible.mockReturnValue(true);
-        components[1].isVisible.mockReturnValue(false);
         const results = startMonitoring();
         expect(components[0].makeActive).toHaveBeenCalled();
         expect(components[1].makeActive).not.toHaveBeenCalled();

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

@@ -3,11 +3,11 @@
  */
 export const components: Component[];
 declare namespace _default {
-    export function setEventEmitter(emitter: Object): Object;
     export { startMonitoring };
     export { stopMonitoring };
+    export { stopVideoComponentMonitoring };
     export { getAttentionTimes };
-    export let registerComponent: (...args: [name: string, element: HTMLElement, visibilityThreshold1: number, reportingInterval1: number, isTrackingVideo?: boolean | undefined]) => void;
+    export let registerComponent: (...args: [name: string, element: HTMLElement, visibilityThreshold: number, reportingInterval: number, isTrackingVideo?: boolean | undefined]) => void;
 }
 export default _default;
 declare class Component {
@@ -15,15 +15,15 @@ declare class Component {
      * Component constructor.
      * @param {string} name - The name of the component.
      * @param {HTMLElement} element - The DOM element of the component.
-     * @param {number} visibilityThreshold1 -
+     * @param {number} visibilityThreshold -
      *    visibilityThreshold represents the fraction of each component that must
      *    be in the viewport before it is considered visible.
      *    e.g. 0.5 means that half the height or width must be in the viewport
      *    1 means that the entire element must be in the viewport
-     * @param {number} reportingInterval1 - ??
-     * @param {boolean} isTrackingVideo - Whether this component is tracking video attention
+     * @param {number} reportingInterval - How often attention is reported.
+     * @param {boolean} isTrackingVideo - Whether this component is a video.
      */
-    constructor(name: string, element: HTMLElement, visibilityThreshold1: number, reportingInterval1: number, isTrackingVideo?: boolean);
+    constructor(name: string, element: HTMLElement, visibilityThreshold: number, reportingInterval: number, isTrackingVideo?: boolean);
     name: string;
     element: HTMLElement;
     visibilityThreshold: number;
@@ -33,28 +33,34 @@ declare class Component {
     totalAttentionMs: number;
     unrecordedAttentionStarted: number | null;
     reportedTotalAttentionMs: number;
-    usingEmitter: boolean;
-    visCheck: () => number | null | undefined;
-    isVisible(threshold?: number): boolean;
-    visibilityHasChanged(): boolean;
-    rebindToEventEmitter(): any;
-    checkVisibility(): number | null | undefined;
-    makeActive(): number;
-    makeInactive(): null;
+    handleVisibilityChange(isNowVisible: any): void;
+    makeActive(): void;
+    makeInactive(): void;
+    incrementTotalAttentionTimeByUnrecordedAmount(): void;
     hadAttentionSinceLastGet(): boolean;
     getAttentionTime(): number;
-    incrementTotalAttentionTimeByUnrecordedAmount(): number | undefined;
 }
 /**
  * Begins monitoring the components on the page for attention time.
+ * We begin monitoring if the following conditions are met
+ * 1. the component is visible within the threshold set.
+ * 2. the component is not a video OR is a video which is playing
  * @returns {Array} Array of results from makeActive() for each visible component.
  */
-declare function startMonitoring(): any[];
+declare function startMonitoring(videoPlaying?: boolean): any[];
 /**
  * Stops monitoring the components on the page for attention time.
  * @returns {Array} Array of results from makeInactive() for each component.
  */
 declare function stopMonitoring(): any[];
+/**
+ * Stops monitoring a video on the page for attention time.
+ * This allows us to bypass the decay timer and explicitly stop monitoring video
+ * when the user is not playing the video (ie on video pause or video end) if
+ * the user is explicitly tracking a video component.
+ * @returns {Array} Array of results from makeInactive() for each component.
+ */
+declare function stopVideoComponentMonitoring(): any[];
 /**
  * Retrieves the attention times for all components.
  * @returns {Object}

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

@@ -63,7 +63,11 @@ export type TAction =
 /**
  * The component is returned to its original location
  **/
- | 'RETURN';
+ | 'RETURN'
+/**
+ * The component has detected something
+ */
+ | 'DETECT';
 interface ComponentV2 {
     componentType: TComponentType;
     id?: string;

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" | "INTERACTIVE_ATOM" | 'LOOP_VIDEO';
+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' | 'AD_BLOCK_RECOVERY';

package/package.json

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