@newrelic/video-core 4.1.3-beta → 4.1.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@newrelic/video-core",
-  "version": "4.1.3-beta",
+  "version": "4.1.3",
   "description": "New Relic video tracking core library",
   "main": "./dist/cjs/index.js",
   "module": "./dist/esm/index.js",

package/src/agent.js

@@ -1,5 +1,6 @@
 import { HarvestScheduler } from "./harvestScheduler.js";
 import { NrVideoEventAggregator } from "./eventAggregator.js";
+import Constants from "./constants.js";
 import Log from "./log.js";
 import Tracker from "./tracker";
 
@@ -49,7 +50,8 @@ 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
+          // Ensure only one QOE_AGGREGATE event exists in buffer per harvest cycle.
+          // Dirty-check dedup happens at drain time in HarvestScheduler._qoeKpisUnchanged().
           return this.eventBuffer.addOrReplaceByActionName(Tracker.Events.QOE_AGGREGATE, eventObject);
       }
       return this.eventBuffer.add(eventObject);
@@ -71,6 +73,45 @@ class VideoAnalyticsAgent {
 
     this.harvestScheduler.updateHarvestInterval(interval);
   }
+
+  /**
+   * Forces the next harvest cycle to include QOE_AGGREGATE events.
+   * Called at CONTENT_END to ensure final QoE is sent.
+   */
+  forceNextQoeCycle() {
+    if (this.harvestScheduler) {
+      this.harvestScheduler.forceNextQoeCycle = true;
+    }
+  }
+
+  /**
+   * Sets a callback to be called before each drain to refresh QoE KPIs.
+   * @param {Function|null} callback - Function that refreshes QoE data in the buffer, or null to clear
+   */
+  setBeforeDrainCallback(callback) {
+    if (this.harvestScheduler) {
+      this.harvestScheduler.beforeDrainCallback = callback;
+    }
+  }
+
+  /**
+   * Updates QoE KPI fields on the existing QOE_AGGREGATE event in the buffer.
+   * Uses addOrReplaceByActionName to keep payload size tracking accurate.
+   * @param {object} freshKpis - Object with latest KPI values
+   */
+  refreshQoeKpis(freshKpis) {
+    if (!this.eventBuffer || !freshKpis) return;
+    const existing = this.eventBuffer.findByActionName(Tracker.Events.QOE_AGGREGATE);
+    if (existing) {
+      const updated = { ...existing };
+      for (const key of Constants.QOE_KPI_KEYS) {
+        if (key in freshKpis) {
+          updated[key] = freshKpis[key];
+        }
+      }
+      this.eventBuffer.addOrReplaceByActionName(Tracker.Events.QOE_AGGREGATE, updated);
+    }
+  }
 }
 
 // Create singleton instance

package/src/constants.js

@@ -42,10 +42,20 @@ Constants.MAX_BEACON_SIZE = 61440; // 60KB = 60 × 1024 bytes
 Constants.MAX_EVENTS_PER_BATCH = 1000;
 Constants.INTERVAL = 10000; //10 seconds
 
+Constants.QOE_KPI_KEYS = [
+    "startupTime", "peakBitrate", "averageBitrate", "totalPlaytime",
+    "totalRebufferingTime", "rebufferingRatio", "hadStartupError",
+    "hadPlaybackError", "numberOfErrors"
+];
+
 Constants.QOE_AGGREGATE_KEYS = [
     "coreVersion", "instrumentation.name",
     "instrumentation.provider", "instrumentation.version", "isBackgroundEvent", "playerName", "playerVersion",
-    "src", "viewId", "viewSession", "contentIsAutoplayed"
+    "src", "viewId", "viewSession", "contentIsAutoplayed", "contentIsMuted", "contentRenditionHeight", "contentRenditionWidth",
+    "contentSrc", "numberOfVideos", "pageUrl", "trackerName", "trackerVersion", "contentDuration", "contentPlayrate", "contentPlayhead",
+    "contentPreload", "elapsedTime", "contentTitle", "contentId", "contentIsLive", "deviceType", "deviceGroup", "deviceManufacturer",
+    "deviceModel", "deviceName", "deviceSize", "deviceUuid", "contentRenditionName", "contentIsFullscreen", "contentCdn",
+    "contentFps", "asnOrganization", "asnLongitude", "asnLatitude", "asn", "timeSinceRequested", "timeSinceStarted"
 ]
 
 export default Constants;

package/src/core.js

@@ -16,7 +16,7 @@ class Core {
   static addTracker(tracker, options) {
     // Set video analytics configuration
     if (options?.info) {
-      setVideoConfig(options.info);
+      setVideoConfig(options.info, options?.config);
     }
     
     if (tracker.on && tracker.emit) {

package/src/eventAggregator.js

@@ -55,6 +55,16 @@ export class NrVideoEventAggregator {
       }
     }
 
+  /**
+   * Returns the existing event in buffer matching the given actionName, or null.
+   * @param {string} actionName
+   * @returns {object|null}
+   */
+  findByActionName(actionName) {
+      const event = this.buffer.find(e => e.actionName === actionName);
+      return event || null;
+  }
+
   /**
    * Adds an event to the unified buffer.
    * All events are treated equally in FIFO order.

package/src/harvestScheduler.js

@@ -3,6 +3,7 @@ import { RetryQueueHandler } from "./retryQueueHandler";
 import { OptimizedHttpClient } from "./optimizedHttpClient";
 import { buildUrl, dataSize } from "./utils";
 import Constants from "./constants";
+import Tracker from "./tracker";
 import Log from "./log";
 
 /**
@@ -31,6 +32,10 @@ export class HarvestScheduler {
     this.currentTimerId = null;
     this.harvestCycle = Constants.INTERVAL;
     this.isHarvesting = false;
+    this.qoeCycleCount = 1;
+    this.forceNextQoeCycle = false;
+    this.beforeDrainCallback = null;
+    this._lastSentQoeKpis = null;
 
     // Page lifecycle handling
     this.setupPageLifecycleHandlers();
@@ -237,15 +242,65 @@ export class HarvestScheduler {
   /**
    * Drains events from the event buffer and optionally includes retry queue data.
    * Uses fresh-events-first approach with payload limits.
+   * Filters out QOE_AGGREGATE events based on the harvest interval multiplier,
+   * always including them on the first and final harvest cycles.
    * @param {object} options - Harvest options
    * @returns {Array} Drained events
    * @private
    */
-  drainEvents() {
+  drainEvents(options = {}) {
+    // Determine if this cycle should include the QOE_AGGREGATE event
+    const multiplier = window.NRVIDEO?.config?.qoeIntervalFactor ?? 1;
+    const isForced = !!options.isFinalHarvest || this.forceNextQoeCycle;
+    const isQoeCycle =
+      (this.qoeCycleCount - 1) % multiplier === 0 || isForced;
+
+    // Reset force flag after use
+    if (this.forceNextQoeCycle) this.forceNextQoeCycle = false;
+
+    // Refresh QoE KPIs with latest tracker state before draining
+    if (this.beforeDrainCallback && typeof this.beforeDrainCallback === 'function') {
+      try {
+        this.beforeDrainCallback();
+      } catch (e) {
+        Log.error("Before drain callback failed:", e.message);
+      }
+    }
+
     // Always drain fresh events first (priority approach)
     const freshEvents = this.eventBuffer.drain();
-    let events = [...freshEvents];
-    let currentPayloadSize = dataSize(freshEvents);
+    let filteredFreshEvents;
+    if (isQoeCycle) {
+      filteredFreshEvents = freshEvents;
+    } else {
+      // On non-QoE cycles, put QoE events back into buffer instead of losing them
+      filteredFreshEvents = [];
+      for (const e of freshEvents) {
+        if (e.actionName === Tracker.Events.QOE_AGGREGATE) {
+          this.eventBuffer.add(e);
+        } else {
+          filteredFreshEvents.push(e);
+        }
+      }
+    }
+
+    this.qoeCycleCount++;
+
+    // Cross-cycle dirty check: skip QoE if KPIs unchanged since last send
+    // Forced cycles (CONTENT_END, page unload) always send QoE
+    for (let i = filteredFreshEvents.length - 1; i >= 0; i--) {
+      const e = filteredFreshEvents[i];
+      if (e.actionName === Tracker.Events.QOE_AGGREGATE) {
+        if (!isForced && this._qoeKpisUnchanged(e)) {
+          filteredFreshEvents.splice(i, 1);
+        } else {
+          this._saveQoeKpis(e);
+        }
+      }
+    }
+
+    let events = [...filteredFreshEvents];
+    let currentPayloadSize = dataSize(filteredFreshEvents);
 
     // Always check retry queue if it has data - no flags needed
     if (this.retryQueueHandler && this.retryQueueHandler.getQueueSize() > 0) {
@@ -413,4 +468,30 @@ export class HarvestScheduler {
       triggerFinalHarvest();
     });
   }
+
+  /**
+   * Checks if QoE KPIs are unchanged since last send.
+   * @param {object} event - QoE event to compare
+   * @returns {boolean} True if KPIs are identical to last sent
+   * @private
+   */
+  _qoeKpisUnchanged(event) {
+    if (!this._lastSentQoeKpis) return false;
+    for (const key of Constants.QOE_KPI_KEYS) {
+      if (event[key] !== this._lastSentQoeKpis[key]) return false;
+    }
+    return true;
+  }
+
+  /**
+   * Saves QoE KPI values after sending.
+   * @param {object} event - QoE event that was sent
+   * @private
+   */
+  _saveQoeKpis(event) {
+    this._lastSentQoeKpis = {};
+    for (const key of Constants.QOE_KPI_KEYS) {
+      this._lastSentQoeKpis[key] = event[key];
+    }
+  }
 }

package/src/recordEvent.js

@@ -57,7 +57,7 @@ export function recordEvent(eventType, attributes = {}) {
     // Send to video analytics harvester
     const success = videoAnalyticsHarvester.addEvent(eventObject);
 
-    if(qoeEventObject) {
+    if(qoeEventObject && window?.NRVIDEO?.config?.qoeAggregate) {
         const successQoe = videoAnalyticsHarvester.addEvent(qoeEventObject);
         return success && successQoe;
     }

package/src/videoConfiguration.js

@@ -10,15 +10,19 @@ const { COLLECTOR } = Constants;
 class VideoConfiguration {
   /**
    * Validates and sets the video analytics configuration.
-   * @param {object} userConfig - User provided configuration
+   * @param {object} userInfo - User provided configuration
+   * @param {object} [config] - Optional configuration object
    * @returns {boolean} True if configuration is valid and set
    */
 
-  setConfiguration(userInfo) {
+  setConfiguration(userInfo, config) {
     if (!this.validateRequiredFields(userInfo)) {
       return false;
     }
-    this.initializeGlobalConfig(userInfo);
+    if (!this.validateConfigFields(config)) {
+      return false;
+    }
+    this.initializeGlobalConfig(userInfo, config);
     Log.notice("Video analytics configuration initialized successfully");
     return true;
   }
@@ -73,10 +77,49 @@ class VideoConfiguration {
     return true;
   }
 
+  /**
+   * Validates optional config fields.
+   * @param {object} config - Config to validate
+   * @returns {boolean} True if valid
+   */
+  validateConfigFields(config) {
+    if (config === null || config === undefined) {
+      return true;
+    }
+
+    if (typeof config !== "object" || Array.isArray(config)) {
+      Log.error("config must be an object");
+      return false;
+    }
+
+    const { qoeAggregate } = config;
+
+    if (qoeAggregate !== undefined && typeof qoeAggregate !== "boolean") {
+      Log.error("qoeAggregate must be a boolean");
+      return false;
+    }
+
+    return true;
+  }
+
+  /**
+   * Sanitizes qoeIntervalFactor, defaulting to 1 if the value is not a positive integer.
+   * @param {*} value
+   * @returns {number}
+   */
+  sanitizeQoeIntervalFactor(value) {
+    if (value === undefined || value === null) return 1;
+    if (typeof value === "number" && Number.isInteger(value) && value >= 1) return value;
+    console.warn(`[nrvideo] Invalid qoeIntervalFactor "${value}" — must be a positive integer. Defaulting to 1.`);
+    return 1;
+  }
+
   /**
    * Initializes the global NRVIDEO configuration object.
+   * @param {object} userInfo - User provided configuration
+   * @param {object} [config] - Optional configuration object
    */
-  initializeGlobalConfig(userInfo) {
+  initializeGlobalConfig(userInfo, config) {
 
     let { licenseKey, appName, region, beacon, applicationID } = userInfo;
 
@@ -95,6 +138,10 @@ class VideoConfiguration {
         applicationID,
         ...(applicationID ? {} : { appName }), // Only include appName when no applicationID
       },
+      config: {
+        qoeAggregate: config?.qoeAggregate ?? false,
+        qoeIntervalFactor: this.sanitizeQoeIntervalFactor(config?.qoeIntervalFactor),
+      }
     };
   }
 }
@@ -104,11 +151,12 @@ const videoConfiguration = new VideoConfiguration();
 
 /**
  * Sets the video analytics configuration.
- * @param {object} config - Configuration object
+ * @param {object} info - Info configuration object
+ * @param {object} [config] - Optional configuration object
  * @returns {boolean} True if configuration was set successfully
  */
-export function setVideoConfig(info) {
-  return videoConfiguration.setConfiguration(info);
+export function setVideoConfig(info, config) {
+  return videoConfiguration.setConfiguration(info, config);
 }
 
 export { videoConfiguration };

package/src/videotracker.js

@@ -1,6 +1,7 @@
 import Log from "./log";
 import Tracker from "./tracker";
 import TrackerState from "./videotrackerstate";
+import { videoAnalyticsHarvester } from "./agent";
 import pkg from "../package.json";
 
 /**
@@ -239,6 +240,21 @@ class VideoTracker extends Tracker {
     return null;
   }
 
+  /** Override to return the manifest-declared bitrate in bps (Indicated Bitrate). */
+  getManifestBitrate() {
+    return null;
+  }
+
+  /** Override to return the measured network bitrate in bps (Observed Bitrate). */
+  getMeasuredBitrate() {
+    return null;
+  }
+
+  /** Override to return the download throughput in bps. */
+  getDownloadBitrate() {
+    return null;
+  }
+
   /** Calculates consumed bitrate using webkitVideoDecodedByteCount. */
   getWebkitBitrate() {
     if (this.tag && this.tag.webkitVideoDecodedByteCount) {
@@ -465,12 +481,15 @@ class VideoTracker extends Tracker {
       att.adTitle = this.getTitle();
       att.adSrc = this.getSrc();
       att.adCdn = this.getCdn();
-      att.adBitrate =
-        this.getBitrate() ||
-        this.getWebkitBitrate() ||
-        this.getRenditionBitrate();
+
+      // Only add bitrate attributes after ad has started
+      if (this.state.isStarted) {
+        att.adBitrate =
+          this.getBitrate() || 0;
+        att.adRenditionBitrate = this.getRenditionBitrate() || 0;
+      }
+
       att.adRenditionName = this.getRenditionName();
-      att.adRenditionBitrate = this.getRenditionBitrate();
       att.adRenditionHeight = this.getRenditionHeight();
       att.adRenditionWidth = this.getRenditionWidth();
       att.adDuration = this.getDuration();
@@ -492,13 +511,17 @@ class VideoTracker extends Tracker {
       att.contentPlayhead = this.getPlayhead();
 
       att.contentIsLive = this.isLive();
-      att.contentBitrate =
-        this.getBitrate() ||
-        this.getWebkitBitrate() ||
-        this.getRenditionBitrate();
+
+      // Only add bitrate attributes after content has started
+      if (this.state.isStarted) {
+        att.contentBitrate = this.getBitrate()|| 0;
+        att.contentRenditionBitrate = this.getRenditionBitrate() || 0;
+        att.contentManifestBitrate = this.getManifestBitrate() || 0;
+        att.contentMeasuredBitrate = this.getMeasuredBitrate() || 0;
+        att.contentDownloadBitrate = this.getDownloadBitrate() || 0;
+      }
 
       att.contentRenditionName = this.getRenditionName();
-      att.contentRenditionBitrate = this.getRenditionBitrate();
       att.contentRenditionHeight = this.getRenditionHeight();
       att.contentRenditionWidth = this.getRenditionWidth();
       att.contentDuration = this.getDuration();
@@ -610,15 +633,23 @@ class VideoTracker extends Tracker {
         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.stopAdsTime();
             this.adsTracker.state.isPlaying = false;
             this.adsTracker.state.isBuffering = false;
-          } else {
-            totalAdsTime = this.adsTracker.state.totalAdTime() ?? 0;
           }
+          // Always use totalAdTime() which includes accumulator across all ads
+          totalAdsTime = this.adsTracker.state.totalAdTime() ?? 0;
         }
         this.state.setStartupTime(totalAdsTime)
         this.sendVideoAction(ev, att);
+
+        // Register callback to refresh QoE KPIs with latest state before each drain
+        videoAnalyticsHarvester.setBeforeDrainCallback(() => {
+          if (this.state) {
+            const freshKpis = this.state.getQoeAttributes({}).qoe;
+            videoAnalyticsHarvester.refreshQoeKpis(freshKpis);
+          }
+        });
       }
       //this.send(ev, att);
       this.startHeartbeat();
@@ -658,6 +689,11 @@ class VideoTracker extends Tracker {
       this.state.goViewCountUp();
       this.state.totalPlaytime = 0;
       if(!this.isAd()) {
+        // Force QoE to be included in the next harvest cycle at content end
+          videoAnalyticsHarvester.forceNextQoeCycle();
+        // Clear the before-drain callback so the next harvest doesn't overwrite
+        // the final QoE (already in buffer) with zeroed-out state values
+          videoAnalyticsHarvester.setBeforeDrainCallback(null);
         // reset the states after the view count is up
           if(this.adsTracker) this.adsTracker.state.clearTotalAdsTime();
           this.state.resetViewIdTrackedState();

package/src/videotrackerstate.js

@@ -104,14 +104,19 @@ class VideoTrackerState {
     this.partialAverageBitrate = 0;
 
     /**
-     * Had Startup Failure: TRUE if CONTENT_ERROR occurs before CONTENT_START.
+     * Total duration (ms) of all closed bitrate segments for weighted average
      */
-    this.hadStartupFailure = false;
+    this._totalBitrateDuration = 0;
 
     /**
-     * Had Playback Failure: TRUE if CONTENT_ERROR occurs during content playback.
+     * Had Startup Error: TRUE if CONTENT_ERROR occurs before CONTENT_START.
      */
-    this.hadPlaybackFailure = false;
+    this.hadStartupError = false;
+
+    /**
+     * Had Playback Error: TRUE if CONTENT_ERROR occurs during content playback.
+     */
+    this.hadPlaybackError = false;
 
     /**
      * The amount of ms the user has been rebuffering during content playback.
@@ -354,8 +359,8 @@ class VideoTrackerState {
           if (this.peakBitrate > 0) {
               kpi["peakBitrate"] = this.peakBitrate;
           }
-          kpi["hadStartupFailure"] = this.hadStartupFailure;
-          kpi["hadPlaybackFailure"] = this.hadPlaybackFailure;
+          kpi["hadStartupError"] = this.hadStartupError;
+          kpi["hadPlaybackError"] = this.hadPlaybackError;
           kpi["totalRebufferingTime"] = this.totalRebufferingTime;
           // Calculate rebuffering ratio as percentage (avoid division by zero)
           kpi["rebufferingRatio"] = this.totalPlaytime > 0
@@ -549,8 +554,10 @@ class VideoTrackerState {
       }
 
       // Accumulate total rebuffering time for content only
+      // Use exact stopped duration (stopTime - startTime) instead of live getDeltaTime()
       if (!this.isAd() && this.initialBufferingHappened) {
-        this.totalRebufferingTime += this.timeSinceBufferBegin.getDeltaTime();
+        this.totalRebufferingTime +=
+            (this.timeSinceBufferBegin.stopTime - this.timeSinceBufferBegin.startTime);
       }
 
       return true;
@@ -670,13 +677,13 @@ class VideoTrackerState {
     } else {
       this.timeSinceLastError.start();
 
-      // Track failure flags for content errors only
-      // Had Startup Failure: error before content started
+      // Track error flags for content errors only
+      // Had Startup Error: error before content started
       if (!this.isStarted) {
-        this.hadStartupFailure = true;
+        this.hadStartupError = true;
       } else {
-        // Had Playback Failure: any content error
-        this.hadPlaybackFailure = true;
+        // Had Playback Error: any content error during playback
+        this.hadPlaybackError = true;
       }
     }
   }
@@ -696,14 +703,57 @@ class VideoTrackerState {
     if (bitrate && typeof bitrate === "number") {
       this.peakBitrate = Math.max(this.peakBitrate, bitrate);
 
-      if(this._lastBitrate === null || this._lastBitrate !== bitrate) {
-        const deltaPlaytime = this._lastBitrateChangeTimestamp === null ? this.totalPlaytime : Date.now() - this._lastBitrateChangeTimestamp;
-        const currentWeightedBitrate = (bitrate * deltaPlaytime);
-        this.partialAverageBitrate += currentWeightedBitrate;
-        this.weightedBitrate = currentWeightedBitrate / deltaPlaytime;
+      const now = Date.now();
+
+      // If not playing (buffering, paused, etc.), close the current segment
+      // so non-play time is excluded from the weighted average
+      if (!this.isPlaying) {
+        if (this._lastBitrate !== null && this._lastBitrateChangeTimestamp !== null) {
+          const segmentDuration = now - this._lastBitrateChangeTimestamp;
+          if (segmentDuration > 0) {
+            this.partialAverageBitrate += this._lastBitrate * segmentDuration;
+            this._totalBitrateDuration += segmentDuration;
+          }
+          this._lastBitrateChangeTimestamp = null; // Mark as paused
+        }
         this._lastBitrate = bitrate;
-        this._lastBitrateChangeTimestamp = Date.now();
+        return;
+      }
+
+      // Playing: restart timestamp if returning from non-play state
+      if (this._lastBitrateChangeTimestamp === null && this._lastBitrate !== null) {
+        this._lastBitrateChangeTimestamp = now;
+      }
+
+      // Close the PREVIOUS segment when bitrate changes
+      if (this._lastBitrate !== null && this._lastBitrate !== bitrate
+          && this._lastBitrateChangeTimestamp !== null) {
+        const segmentDuration = now - this._lastBitrateChangeTimestamp;
+        if (segmentDuration > 0) {
+          this.partialAverageBitrate += this._lastBitrate * segmentDuration;
+          this._totalBitrateDuration += segmentDuration;
+        }
+        this._lastBitrateChangeTimestamp = now;
+      }
+
+      // Initialize timestamp on first observation
+      if (this._lastBitrateChangeTimestamp === null) {
+        this._lastBitrateChangeTimestamp = now;
+      }
+
+      this._lastBitrate = bitrate;
+
+      // Compute weighted average including current in-progress segment
+      let totalWeighted = this.partialAverageBitrate;
+      let totalDuration = this._totalBitrateDuration;
+      const currentSegment = now - this._lastBitrateChangeTimestamp;
+      if (currentSegment > 0) {
+        totalWeighted += bitrate * currentSegment;
+        totalDuration += currentSegment;
       }
+      this.weightedBitrate = totalDuration > 0
+          ? Math.round(totalWeighted / totalDuration)
+          : bitrate;
     }
   }
 
@@ -713,6 +763,7 @@ class VideoTrackerState {
   resetViewIdTrackedState() {
     this.peakBitrate = 0;
     this.partialAverageBitrate = 0;
+    this._totalBitrateDuration = 0;
     this.startupTime = null;
     this._lastBitrate = null;
     this._lastBitrateChangeTimestamp = null;
@@ -720,7 +771,7 @@ class VideoTrackerState {
 
   /** Methods to manage total ads time chrono */
   clearTotalAdsTime() {
-    console.log("clear total ads time", this.totalAdTime);
+    Log.debug("clear total ads time", this.totalAdTime);
     this._totalAdPlaytime.reset();
   }
 
@@ -729,12 +780,12 @@ class VideoTrackerState {
   }
 
   startAdsTime() {
-    console.log("startAdsTime");
+    Log.debug("startAdsTime");
     return this._totalAdPlaytime.start();
   }
 
   stopAdsTime() {
-    console.log("stopAdsTime");
+    Log.debug("stopAdsTime");
     return this._totalAdPlaytime.stop();
   }