@newrelic/video-core 4.0.1 → 4.1.0-beta

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@newrelic/video-core",
-  "version": "4.0.1",
+  "version": "4.1.0-beta",
   "description": "New Relic video tracking core library",
   "main": "./dist/cjs/index.js",
   "module": "./dist/esm/index.js",
@@ -51,6 +51,7 @@
     "LICENSE",
     "README.md",
     "src",
+    "__mock__.js",
     "!test"
   ],
   "publishConfig": {

package/src/agent.js

@@ -1,6 +1,7 @@
 import { HarvestScheduler } from "./harvestScheduler.js";
 import { NrVideoEventAggregator } from "./eventAggregator.js";
 import Log from "./log.js";
+import Tracker from "./tracker";
 
 /**
  * Enhanced video analytics agent with HarvestScheduler only.
@@ -47,6 +48,10 @@ class VideoAnalyticsAgent {
     }
 
     try {
+      if(eventObject.actionName && eventObject.actionName === Tracker.Events.QOE_AGGREGATE) {
+          // This makes sure that there is only one QOE aggregate event for a harvest cycle
+          return this.eventBuffer.addOrReplaceByActionName(Tracker.Events.QOE_AGGREGATE, eventObject);
+      }
       return this.eventBuffer.add(eventObject);
     } catch (error) {
       Log.error("Failed to add event to harvesting system:", error.message);

package/src/chrono.js

@@ -17,6 +17,9 @@ class Chrono {
     /** Stop time */
     this.stopTime = 0;
 
+    /** accumulation of all the start and stop intervals */
+    this.accumulator = 0;
+
     /**
      * If you set an offset in a chrono, its value will be added getDeltaTime and stop.
      *
@@ -59,9 +62,20 @@ class Chrono {
    */
   stop() {
     this.stopTime = new Date().getTime();
+    if(this.startTime < this.stopTime) {
+      this.accumulator += (this.stopTime - this.startTime);
+    }
     return this.getDeltaTime();
   }
 
+  getDuration() {
+    if(this.stopTime) {
+      return this.accumulator + this.offset;
+    } else {
+      return this.accumulator + (this.getDeltaTime() ?? 0)
+    }
+  }
+
   /**
    * Creates a copy of the chrono.
    * @returns {Chrono} Cloned chrono
@@ -71,6 +85,7 @@ class Chrono {
     chrono.startTime = this.startTime;
     chrono.stopTime = this.stopTime;
     chrono.offset = this.offset;
+    chrono.accumulator = this.accumulator;
     return chrono;
   }
 }

package/src/constants.js

@@ -42,4 +42,10 @@ Constants.MAX_BEACON_SIZE = 61440; // 60KB = 60 × 1024 bytes
 Constants.MAX_EVENTS_PER_BATCH = 1000;
 Constants.INTERVAL = 10000; //10 seconds
 
+Constants.QOE_AGGREGATE_KEYS = [
+    "coreVersion", "instrumentation.name",
+    "instrumentation.provider", "instrumentation.version", "isBackgroundEvent", "playerName", "playerVersion",
+    "src", "viewId", "viewSession", "contentIsAutoplayed"
+]
+
 export default Constants;

package/src/eventAggregator.js

@@ -32,12 +32,37 @@ export class NrVideoEventAggregator {
     this.onSmartHarvestTrigger = null;
   }
 
+  /**
+   * If an event with the specified actionName already exists in the buffer, it will be replaced.
+   * Otherwise, the event will be added as a new entry.
+   * @param {string} actionName - The actionName to search for in the buffer
+   * @param {object} eventObject - The event object to add or use as replacement. Should contain an actionName property.
+   * @returns {boolean} True if the operation succeeded, false if an error occurred
+   */
+  addOrReplaceByActionName(actionName, eventObject) {
+      const i = this.buffer.findIndex(e => e.actionName === actionName);
+
+      try {
+          if(i === -1) {
+              this.add(eventObject);
+          } else {
+              this.add(eventObject, i);
+          }
+          return true;
+      } catch (error) {
+          Log.error("Failed to set or replace the event to buffer:", error.message);
+          return false;
+      }
+      return false;
+    }
+
   /**
    * Adds an event to the unified buffer.
    * All events are treated equally in FIFO order.
    * @param {object} eventObject - The event to add
+   * @param {number} index - index at which the event should be replaced with
    */
-  add(eventObject) {
+  add(eventObject, index) {
     try {
       // Calculate event payload size
       const eventSize = dataSize(eventObject);
@@ -52,10 +77,18 @@ export class NrVideoEventAggregator {
         this.makeRoom(eventSize);
       }
 
-      // Add to unified buffer
-      this.buffer.push(eventObject);
-      this.totalEvents++;
-      this.currentPayloadSize += eventSize;
+      if(index !== undefined && index !== null && index > -1) {
+          // replace in unified buffer
+          const previousPayloadSize = dataSize(this.buffer[index]);
+          this.buffer[index] = eventObject;
+          // Updating the payload size for the replaced event
+          this.currentPayloadSize += eventSize - previousPayloadSize;
+      } else {
+          // Add to unified buffer
+          this.buffer.push(eventObject);
+          this.totalEvents++;
+          this.currentPayloadSize += eventSize;
+      }
 
       // Check if smart harvest should be triggered
       this.checkSmartHarvestTrigger();

package/src/recordEvent.js

@@ -1,6 +1,8 @@
 import { videoAnalyticsHarvester } from "./agent.js";
 import Constants from "./constants.js";
 import Log from "./log.js";
+import Tracker from "./tracker";
+import {getObjectEntriesForKeys} from "./utils";
 
 /**
  * Enhanced record event function with validation, enrichment, and unified handling.
@@ -21,18 +23,44 @@ export function recordEvent(eventType, attributes = {}) {
 
     const { appName, applicationID } = window.NRVIDEO.info;
 
+    const { qoe, ...eventAttributes } = attributes;
+    const qoeAttrs = qoe ? { ...qoe } : {};
+
+    const otherAttrs = {
+        ...(applicationID ? {} : { appName }), // Only include appName when no applicationID
+        timestamp: Date.now(),
+        timeSinceLoad: window.performance
+            ? window.performance.now() / 1000
+            : null,
+    }
+
     const eventObject = {
-      ...attributes,
+      ...eventAttributes,
       eventType,
-      ...(applicationID ? {} : { appName }), // Only include appName when no applicationID
-      timestamp: Date.now(),
-      timeSinceLoad: window.performance
-        ? window.performance.now() / 1000
-        : null,
+      ...otherAttrs,
     };
 
+    const metadataAttributes = getObjectEntriesForKeys(Constants.QOE_AGGREGATE_KEYS, attributes)
+
+    let qoeEventObject = null;
+    if(eventType === "VideoAction") {
+        qoeEventObject = {
+            eventType: "VideoAction",
+            actionName: Tracker.Events.QOE_AGGREGATE,
+            ...qoeAttrs,
+            ...metadataAttributes,
+            ...otherAttrs,
+        }
+    }
+
     // Send to video analytics harvester
     const success = videoAnalyticsHarvester.addEvent(eventObject);
+
+    if(qoeEventObject) {
+        const successQoe = videoAnalyticsHarvester.addEvent(qoeEventObject);
+        return success && successQoe;
+    }
+
     return success;
   } catch (error) {
     Log.error("Failed to record event:", error.message);

package/src/tracker.js

@@ -293,6 +293,7 @@ class Tracker extends Emitter {
 Tracker.Events = {
   /** The heartbeat event is sent once every 30 seconds while the video is playing. */
   HEARTBEAT: "HEARTBEAT",
+  QOE_AGGREGATE: "QOE_AGGREGATE",
 };
 
 export default Tracker;

package/src/utils.js

@@ -160,3 +160,27 @@ export async function decompressPayload(compressedData) {
     throw new Error(`Failed to decompress payload: ${error.message}`);
   }
 }
+
+/**
+ * Filters an object to include only the specified keys.
+ * Creates a new object containing only the key-value pairs from the source object
+ * that match the provided keys array.
+ * @param {string[]} keys - Array of keys to extract from the object. If empty, null, or not an array, returns the original object.
+ * @param {object} obj - The source object to extract entries from.
+ * @returns {object} A new object containing only the entries that match the specified keys. Returns an empty object if obj is invalid.
+ * @example
+ * const data = { name: 'John', age: 30, city: 'NYC', country: 'USA' };
+ * const filtered = getObjectEntriesForKeys(['name', 'city'], data);
+ * // Returns: { name: 'John', city: 'NYC' }
+ */
+export function getObjectEntriesForKeys(keys, obj) {
+    if(!keys || !Array.isArray(keys) || keys.length === 0) return obj;
+    if(!obj || typeof obj !== 'object') return {};
+
+    return keys.reduce((result, key) => {
+        if(key in obj) {
+            result[key] = obj[key];
+        }
+        return result;
+    }, {});
+}

package/src/videotracker.js

@@ -496,6 +496,7 @@ class VideoTracker extends Tracker {
         this.getBitrate() ||
         this.getWebkitBitrate() ||
         this.getRenditionBitrate();
+
       att.contentRenditionName = this.getRenditionName();
       att.contentRenditionBitrate = this.getRenditionBitrate();
       att.contentRenditionHeight = this.getRenditionHeight();
@@ -520,13 +521,30 @@ class VideoTracker extends Tracker {
 
     this.state.getStateAttributes(att);
 
+    if(this.state.isStarted && !this.isAd()) {
+      this.state.trackContentBitrateState(att.contentBitrate);
+    }
+
     for (let key in this.customData) {
       att[key] = this.customData[key];
     }
 
+    /**
+     * Adds all the attributes and custom attributes for qoe event
+     */
+    this.addQoeAttributes(att);
+
     return att;
   }
 
+  addQoeAttributes(att) {
+      att = this.state.getQoeAttributes(att);
+      const qoe = att.qoe;
+      for (let key in this.customData) {
+          qoe[key] = this.customData[key];
+      }
+  }
+
   /**
    * Sends custom event and registers a timeSince attribute.
    * @param {Object} [actionName] Custom action name.
@@ -585,8 +603,21 @@ class VideoTracker extends Tracker {
         ev = VideoTracker.Events.AD_START;
         if (this.parentTracker) this.parentTracker.state.isPlaying = false;
         this.sendVideoAdAction(ev, att);
+        this.state.startAdsTime();
       } else {
         ev = VideoTracker.Events.CONTENT_START;
+        let totalAdsTime = 0;
+        if(this.adsTracker) {
+          // If ads state is set to playing (ad error) after content start, reset the ad state.
+          if(this.adsTracker.state.isPlaying || this.adsTracker.state.isBuffering) {
+            totalAdsTime = this.adsTracker.state.stopAdsTime();
+            this.adsTracker.state.isPlaying = false;
+            this.adsTracker.state.isBuffering = false;
+          } else {
+            totalAdsTime = this.adsTracker.state.totalAdTime() ?? 0;
+          }
+        }
+        this.state.setStartupTime(totalAdsTime)
         this.sendVideoAction(ev, att);
       }
       //this.send(ev, att);
@@ -610,6 +641,7 @@ class VideoTracker extends Tracker {
         att.timeSinceAdRequested = this.state.timeSinceRequested.getDeltaTime();
         att.timeSinceAdStarted = this.state.timeSinceStarted.getDeltaTime();
         if (this.parentTracker) this.parentTracker.state.isPlaying = true;
+        this.state.stopAdsTime();
       } else {
         ev = VideoTracker.Events.CONTENT_END;
         att.timeSinceRequested = this.state.timeSinceRequested.getDeltaTime();
@@ -625,6 +657,11 @@ class VideoTracker extends Tracker {
         this.parentTracker.state.goLastAd();
       this.state.goViewCountUp();
       this.state.totalPlaytime = 0;
+      if(!this.isAd()) {
+        // reset the states after the view count is up
+          if(this.adsTracker) this.adsTracker.state.clearTotalAdsTime();
+          this.state.resetViewIdTrackedState();
+      }
     }
   }
 

package/src/videotrackerstate.js

@@ -61,6 +61,8 @@ class VideoTrackerState {
      */
     this.totalPlaytime = 0;
 
+    this.weightedAverageBitrate = 0;
+
     /**
      * The amount of ms the user has been watching ads during an ad break.
      */
@@ -72,6 +74,45 @@ class VideoTrackerState {
     /** True if initial buffering event already happened. */
     this.initialBufferingHappened = false;
 
+    /**
+     * New QoE KPIs - Content only
+     */
+
+    /**
+     * Startup Time: Time from CONTENT_REQUEST to CONTENT_START in milliseconds.
+     */
+    this.startupTime = null;
+
+    /**
+     * Peak Bitrate: Maximum contentBitrate observed across all content playback.
+     */
+    this.peakBitrate = 0;
+
+    /**
+     * Last tracked bitrate
+     */
+    this._lastBitrate = null;
+
+    /**
+     * total bitrate partial value for average weighted average bitrate
+     */
+    this.partialAverageBitrate = 0;
+
+    /**
+     * Had Startup Failure: TRUE if CONTENT_ERROR occurs before CONTENT_START.
+     */
+    this.hadStartupFailure = false;
+
+    /**
+     * Had Playback Failure: TRUE if CONTENT_ERROR occurs during content playback.
+     */
+    this.hadPlaybackFailure = false;
+
+    /**
+     * The amount of ms the user has been rebuffering during content playback.
+     */
+    this.totalRebufferingTime = 0;
+
     this.resetFlags();
     this.resetChronos();
   }
@@ -153,9 +194,12 @@ class VideoTrackerState {
     /** A dictionary containing the custom timeSince attributes. */
     this.customTimeSinceAttributes = {};
 
-    /** This are used to collect the time of buffred and pause resume between two heartbeats */
+    /** This are used to collect the time of buffered and pause resume between two heartbeats */
     this.elapsedTime = new Chrono();
     this.bufferElapsedTime = new Chrono();
+
+    /** tracks total ad play time  */
+    this._totalAdPlaytime = new Chrono();
   }
 
   /** Returns true if the tracker is currently on ads. */
@@ -293,6 +337,35 @@ class VideoTrackerState {
     return att;
   }
 
+  getQoeAttributes(att) {
+      att = att || {};
+      const kpi = {};
+
+      try {
+          // QoE KPIs - Content only
+          if (this.startupTime !== null) {
+              kpi["startupTime"] = this.startupTime;
+          }
+          if (this.peakBitrate > 0) {
+              kpi["peakBitrate"] = this.peakBitrate;
+          }
+          kpi["hadStartupFailure"] = this.hadStartupFailure;
+          kpi["hadPlaybackFailure"] = this.hadPlaybackFailure;
+          kpi["totalRebufferingTime"] = this.totalRebufferingTime;
+          // Calculate rebuffering ratio as percentage (avoid division by zero)
+          kpi["rebufferingRatio"] = this.totalPlaytime > 0
+              ? (this.totalRebufferingTime / this.totalPlaytime) * 100
+              : 0;
+          kpi["totalPlaytime"] = this.totalPlaytime;
+          kpi["averageBitrate"] = this.weightedBitrate;
+      } catch (error) {
+          Log.error("Failed to add attributes for QOE KPIs", error.message);
+      }
+
+      att.qoe = kpi;
+      return att;
+  }
+
   /**
    * Calculate the bufferType attribute.
    *
@@ -383,6 +456,7 @@ class VideoTrackerState {
       this.timeSinceRequested.stop();
       this.timeSinceStarted.stop();
       this.playtimeSinceLastEvent.stop();
+      this.isPlaying = false;
       return true;
     } else {
       return false;
@@ -468,6 +542,11 @@ class VideoTrackerState {
         this._bufferAcc += this.bufferElapsedTime.getDeltaTime();
       }
 
+      // Accumulate total rebuffering time for content only
+      if (!this.isAd() && this.initialBufferingHappened) {
+        this.totalRebufferingTime += this.timeSinceBufferBegin.getDeltaTime();
+      }
+
       return true;
     } else {
       return false;
@@ -584,6 +663,15 @@ class VideoTrackerState {
       this.timeSinceLastAdError.start();
     } else {
       this.timeSinceLastError.start();
+
+      // Track failure flags for content errors only
+      // Had Startup Failure: error before content started
+      if (!this.isStarted) {
+        this.hadStartupFailure = true;
+      } else {
+        // Had Playback Failure: any content error
+        this.hadPlaybackFailure = true;
+      }
     }
   }
 
@@ -593,6 +681,61 @@ class VideoTrackerState {
   goLastAd() {
     this.timeSinceLastAd.start();
   }
+
+  /**
+   * Updates peak bitrate with current bitrate value (content only).
+   * @param {number} bitrate Current content bitrate in bps.
+   */
+  trackContentBitrateState(bitrate) {
+    if (bitrate && typeof bitrate === "number") {
+      this.peakBitrate = Math.max(this.peakBitrate, bitrate);
+
+      if(this._lastBitrate === null || this._lastBitrate !== bitrate) {
+        const totalPlaytime = this.timeSinceLastRenditionChange.getDeltaTime() || this.totalPlaytime;
+        const currentWeightedBitrate = (bitrate * totalPlaytime);
+        this.partialAverageBitrate += currentWeightedBitrate;
+        this.weightedBitrate = currentWeightedBitrate / totalPlaytime;
+        this._lastBitrate = bitrate;
+      }
+    }
+  }
+
+  /**
+   * Resets tracked variable for view id change
+   * */
+  resetViewIdTrackedState() {
+    this.peakBitrate = 0;
+    this.partialAverageBitrate = 0;
+    this.startupTime = null;
+    this._lastBitrate = null;
+  }
+
+  /** Methods to manage total ads time chrono */
+  clearTotalAdsTime() {
+    console.log("clear total ads time", this.totalAdTime);
+    this._totalAdPlaytime.reset();
+  }
+
+  totalAdTime() {
+    return this._totalAdPlaytime.getDuration();
+  }
+
+  startAdsTime() {
+    console.log("startAdsTime");
+    return this._totalAdPlaytime.start();
+  }
+
+  stopAdsTime() {
+    console.log("stopAdsTime");
+    return this._totalAdPlaytime.stop();
+  }
+
+  setStartupTime(totalAdTime) {
+    if (this.startupTime === null) {
+      this.startupTime = Math.max(this.timeSinceRequested.getDeltaTime() - totalAdTime, 0)
+    }
+  }
+
 }
 
 export default VideoTrackerState;