@newrelic/video-core 4.1.5-beta → 4.1.5

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@newrelic/video-core",
-  "version": "4.1.5-beta",
+  "version": "4.1.5",
   "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,16 @@ 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 per (actionName + viewId) in buffer per harvest cycle.
+          // Each player has a unique viewId, so multi-player scenarios are handled correctly.
+          // Dirty-check dedup happens at drain time in HarvestScheduler._qoeKpisUnchanged().
+          if (eventObject.viewId) {
+              return this.eventBuffer.addOrReplaceByActionNameAndViewId(
+                  Tracker.Events.QOE_AGGREGATE,
+                  eventObject.viewId,
+                  eventObject
+              );
+          }
           return this.eventBuffer.addOrReplaceByActionName(Tracker.Events.QOE_AGGREGATE, eventObject);
       }
       return this.eventBuffer.add(eventObject);
@@ -71,6 +81,52 @@ 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.
+   * Scoped to a specific viewId to support multiple players on the same page.
+   * @param {object} freshKpis - Object with latest KPI values
+   * @param {string} [viewId] - The viewId of the player whose QoE event to update
+   */
+  refreshQoeKpis(freshKpis, viewId) {
+    if (!this.eventBuffer || !freshKpis) return;
+    const existing = viewId
+      ? this.eventBuffer.findByActionNameAndViewId(Tracker.Events.QOE_AGGREGATE, viewId)
+      : 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];
+        }
+      }
+      if (viewId) {
+        this.eventBuffer.addOrReplaceByActionNameAndViewId(Tracker.Events.QOE_AGGREGATE, viewId, updated);
+      } else {
+        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,54 @@ export class NrVideoEventAggregator {
       }
     }
 
+  /**
+   * If an event with the specified actionName and viewId 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 {string} viewId - The viewId to scope the lookup to
+   * @param {object} eventObject - The event object to add or use as replacement.
+   * @returns {boolean} True if the operation succeeded, false if an error occurred
+   */
+  addOrReplaceByActionNameAndViewId(actionName, viewId, eventObject) {
+      const i = this.buffer.findIndex(
+          e => e.actionName === actionName && e.viewId === viewId
+      );
+      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;
+      }
+  }
+
+  /**
+   * Returns the existing event in buffer matching the given actionName and viewId, or null.
+   * @param {string} actionName
+   * @param {string} viewId
+   * @returns {object|null}
+   */
+  findByActionNameAndViewId(actionName, viewId) {
+      const event = this.buffer.find(
+          e => e.actionName === actionName && e.viewId === viewId
+      );
+      return event || null;
+  }
+
+  /**
+   * 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 = {};
 
     // 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,32 @@ 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) {
+    const snapshot = this._lastSentQoeKpis[event.viewId];
+    if (!snapshot) return false;
+    for (const key of Constants.QOE_KPI_KEYS) {
+      if (event[key] !== snapshot[key]) return false;
+    }
+    return true;
+  }
+
+  /**
+   * Saves QoE KPI values after sending, keyed by viewId to support multiple players.
+   * @param {object} event - QoE event that was sent
+   * @private
+   */
+  _saveQoeKpis(event) {
+    const snapshot = {};
+    for (const key of Constants.QOE_KPI_KEYS) {
+      snapshot[key] = event[key];
+    }
+    this._lastSentQoeKpis[event.viewId] = snapshot;
+  }
 }

package/src/index.js

@@ -26,7 +26,7 @@ const nrvideo = {
   version,
 
   // Enhanced video analytics components (new)
-
+ 
   NrVideoEventAggregator,
   RetryQueueHandler,
   OptimizedHttpClient,
@@ -40,22 +40,4 @@ const nrvideo = {
 
 };
 
-// Named exports for better tree-shaking and interop
-export {
-  Core,
-  Constants,
-  Chrono,
-  Log,
-  Emitter,
-  Tracker,
-  VideoTracker,
-  VideoTrackerState,
-  NrVideoEventAggregator,
-  RetryQueueHandler,
-  OptimizedHttpClient,
-  HarvestScheduler,
-  recordEvent,
-  version
-};
-
 export default nrvideo;

package/src/obfuscate.js

@@ -0,0 +1,33 @@
+import Log from "./log";
+
+/**
+ * Applies obfuscation rules to a JSON string before sending to the collector.
+ * Each rule replaces matches of `regex` with `replacement` in the string.
+ *
+ * @param {string} jsonString - Serialized JSON payload
+ * @param {Array<{regex: string|RegExp, replacement: string}>} rules - Obfuscation rules
+ * @returns {string} Obfuscated string
+ */
+export function applyObfuscationRules(jsonString, rules) {
+  if (!rules || rules.length === 0) return jsonString;
+
+  return rules.reduce((str, rule) => {
+    let pattern;
+    try {
+      if (rule.regex instanceof RegExp) {
+        // Ensure global flag so all occurrences are replaced
+        const flags = rule.regex.flags.includes("g")
+          ? rule.regex.flags
+          : rule.regex.flags + "g";
+        pattern = new RegExp(rule.regex.source, flags);
+      } else {
+        pattern = new RegExp(rule.regex, "g");
+      }
+    } catch (e) {
+      Log.warn("applyObfuscationRules: invalid regex, skipping rule:", rule.regex, e.message);
+      return str;
+    }
+    let s = str.replace(pattern, rule.replacement);
+    return s;
+  }, jsonString);
+}

package/src/optimizedHttpClient.js

@@ -1,5 +1,6 @@
-import { dataSize, shouldRetry } from "./utils";
+import { shouldRetry } from "./utils";
 import Log from "./log";
+import { applyObfuscationRules } from "./obfuscate";
 
 /**
  * Optimized HTTP client for video analytics data transmission with
@@ -50,7 +51,10 @@ export class OptimizedHttpClient {
     const startTime = Date.now();
 
     try {
-      const requestBody = JSON.stringify(payload.body);
+      const requestBody = applyObfuscationRules(
+        JSON.stringify(payload.body),
+        window.NRVIDEO?.config?.obfuscate
+      );
 
       // Handle final harvest with sendBeacon
       if (options.isFinalHarvest && navigator.sendBeacon) {

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,72 @@ 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, obfuscate } = config;
+
+    if (qoeAggregate !== undefined && typeof qoeAggregate !== "boolean") {
+      Log.error("qoeAggregate must be a boolean");
+      return false;
+    }
+
+    if (obfuscate !== undefined && !Array.isArray(obfuscate)) {
+      Log.error("obfuscate must be an array");
+      return false;
+    }
+
+    return true;
+  }
+
+  /**
+   * Filters obfuscation rules, warning about and removing invalid ones.
+   * @param {Array} rules - Raw obfuscation rules
+   * @returns {Array} Valid rules only
+   */
+  filterObfuscateRules(rules) {
+    if (!rules) return [];
+    return rules.filter((rule) => {
+      const hasRegex = rule.regex !== undefined && (typeof rule.regex === "string" || rule.regex instanceof RegExp);
+      const hasReplacement = rule.replacement !== undefined && typeof rule.replacement === "string";
+      if (!hasRegex || !hasReplacement) {
+        Log.warn("obfuscate rule missing required 'regex' (string|RegExp) and/or 'replacement' (string), skipping:", rule);
+        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 +161,11 @@ class VideoConfiguration {
         applicationID,
         ...(applicationID ? {} : { appName }), // Only include appName when no applicationID
       },
+      config: {
+        qoeAggregate: config?.qoeAggregate ?? false,
+        qoeIntervalFactor: this.sanitizeQoeIntervalFactor(config?.qoeIntervalFactor),
+        obfuscate: this.filterObfuscateRules(config?.obfuscate),
+      }
     };
   }
 }
@@ -104,11 +175,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). */
+  getSegmentDownloadBitrate() {
+    return null;
+  }
+
+  /** Override to return the download throughput in bps. */
+  getNetworkDownloadBitrate() {
+    return null;
+  }
+
   /** Calculates consumed bitrate using webkitVideoDecodedByteCount. */
   getWebkitBitrate() {
     if (this.tag && this.tag.webkitVideoDecodedByteCount) {
@@ -465,12 +481,14 @@ 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.adRenditionName = this.getRenditionName();
-      att.adRenditionBitrate = this.getRenditionBitrate();
       att.adRenditionHeight = this.getRenditionHeight();
       att.adRenditionWidth = this.getRenditionWidth();
       att.adDuration = this.getDuration();
@@ -492,13 +510,16 @@ 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.contentManifestBitrate = this.getManifestBitrate() || 0;
+        att.contentSegmentDownloadBitrate = this.getSegmentDownloadBitrate() || 0;
+        att.contentNetworkDownloadBitrate = this.getNetworkDownloadBitrate() || 0;
+      }
 
       att.contentRenditionName = this.getRenditionName();
-      att.contentRenditionBitrate = this.getRenditionBitrate();
       att.contentRenditionHeight = this.getRenditionHeight();
       att.contentRenditionWidth = this.getRenditionWidth();
       att.contentDuration = this.getDuration();
@@ -610,15 +631,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.getViewId());
+          }
+        });
       }
       //this.send(ev, att);
       this.startHeartbeat();
@@ -658,6 +687,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();