@newrelic/video-core 4.1.8-beta → 5.0.0

package/src/utils/qoeFilters.js

@@ -0,0 +1,149 @@
+/**
+ * QoE-related buffer + cycle helpers shared by both pipelines.
+ *
+ * All six helpers were previously duplicated between
+ *   - `browser/agent.js`           (`addEvent`, `refreshQoeKpis`)
+ *   - `browser/harvestScheduler.js` (cycle filter, dirty splice, _qoeKpisUnchanged, _saveQoeKpis)
+ *   - `connectedDevice/connectedDeviceHarvester.js` (same six)
+ *
+ * They're pure helpers — no class state. Callers pass in the buffer / snapshot
+ * map / event array. Keeping them shared makes the QoE behavior one source of
+ * truth across pipelines, so a fix landed once applies to both Browser and
+ * Vega (and any future CAF device pipeline).
+ *
+ * @module utils/qoeFilters
+ */
+
+import Constants from "../constants";
+import Tracker from "../tracker";
+
+/**
+ * Add an event to the buffer with QOE_AGGREGATE dedup. QOE_AGGREGATE events
+ * are deduplicated by `(actionName, viewId)` so multiple players sharing one
+ * harvester each get exactly one buffered QoE event per view. Non-QoE events
+ * are appended as-is, preserving the emit-time `timestamp` already set by
+ * `recordEvent.js`.
+ *
+ * @param {NrVideoEventAggregator} buffer
+ * @param {object} eventObject
+ * @returns {boolean} True if added/replaced.
+ */
+export function bufferEventWithQoeDedup(buffer, eventObject) {
+  if (!eventObject) return false;
+  if (eventObject.actionName === Tracker.Events.QOE_AGGREGATE) {
+    if (eventObject.viewId) {
+      return buffer.addOrReplaceByActionNameAndViewId(
+        Tracker.Events.QOE_AGGREGATE,
+        eventObject.viewId,
+        eventObject
+      );
+    }
+    return buffer.addOrReplaceByActionName(Tracker.Events.QOE_AGGREGATE, eventObject);
+  }
+  return buffer.add(eventObject);
+}
+
+/**
+ * Update QoE KPI fields on the buffered QOE_AGGREGATE event for a given viewId.
+ * Looks up the existing buffered event, merges the fresh KPI values for keys
+ * listed in `Constants.QOE_KPI_KEYS`, and replaces it in the buffer. No-op if
+ * no QOE_AGGREGATE event is currently buffered.
+ *
+ * @param {NrVideoEventAggregator} buffer
+ * @param {object} freshKpis
+ * @param {string} [viewId]
+ */
+export function refreshQoeKpisInBuffer(buffer, freshKpis, viewId) {
+  if (!buffer || !freshKpis) return;
+  const existing = viewId
+    ? buffer.findByActionNameAndViewId(Tracker.Events.QOE_AGGREGATE, viewId)
+    : buffer.findByActionName(Tracker.Events.QOE_AGGREGATE);
+  if (!existing) return;
+  const updated = { ...existing };
+  for (const key of Constants.QOE_KPI_KEYS) {
+    if (key in freshKpis) updated[key] = freshKpis[key];
+  }
+  if (viewId) {
+    buffer.addOrReplaceByActionNameAndViewId(Tracker.Events.QOE_AGGREGATE, viewId, updated);
+  } else {
+    buffer.addOrReplaceByActionName(Tracker.Events.QOE_AGGREGATE, updated);
+  }
+}
+
+/**
+ * Cross-cycle dirty check — true iff every KPI field on `event` equals the
+ * snapshot saved for that event's viewId.
+ *
+ * @param {Object<string, object>} snapshots - viewId → KPI snapshot
+ * @param {object} event
+ * @returns {boolean}
+ */
+export function qoeKpisUnchanged(snapshots, event) {
+  const snapshot = snapshots[event.viewId];
+  if (!snapshot) return false;
+  for (const key of Constants.QOE_KPI_KEYS) {
+    if (event[key] !== snapshot[key]) return false;
+  }
+  return true;
+}
+
+/**
+ * Save a snapshot of an event's QoE KPI fields, keyed by viewId, for the next
+ * cross-cycle dirty check.
+ *
+ * @param {Object<string, object>} snapshots - viewId → KPI snapshot (mutated in place)
+ * @param {object} event
+ */
+export function saveQoeKpiSnapshot(snapshots, event) {
+  const snapshot = {};
+  for (const key of Constants.QOE_KPI_KEYS) {
+    snapshot[key] = event[key];
+  }
+  snapshots[event.viewId] = snapshot;
+}
+
+/**
+ * Partition drained events by the QoE-cycle filter. On a QoE cycle, all events
+ * pass through. On a non-QoE cycle, QOE_AGGREGATE events are re-buffered (so
+ * they ship on the next QoE cycle) and only non-QoE events are returned.
+ *
+ * @param {object[]} drained
+ * @param {boolean} isQoeCycle
+ * @param {NrVideoEventAggregator} buffer
+ * @returns {object[]}
+ */
+export function partitionByQoeCycle(drained, isQoeCycle, buffer) {
+  if (isQoeCycle) return drained;
+  const filtered = [];
+  for (const e of drained) {
+    if (e.actionName === Tracker.Events.QOE_AGGREGATE) {
+      buffer.add(e);
+    } else {
+      filtered.push(e);
+    }
+  }
+  return filtered;
+}
+
+/**
+ * Cross-cycle dirty splice. Walks the array in reverse and drops any
+ * QOE_AGGREGATE event whose KPI fields are unchanged since the last send (so
+ * we don't waste bytes shipping identical aggregates). Saves a fresh snapshot
+ * for any QOE_AGGREGATE that does ship. Mutates `filtered` in place.
+ *
+ * @param {object[]} filtered
+ * @param {Object<string, object>} snapshots - viewId → KPI snapshot (read+written)
+ * @param {boolean} isForced - When true, skip the dirty check and ship every
+ *   QOE_AGGREGATE regardless of KPI sameness (final flush, CONTENT_END, etc.)
+ */
+export function applyQoeDirtyFilter(filtered, snapshots, isForced) {
+  for (let i = filtered.length - 1; i >= 0; i--) {
+    const e = filtered[i];
+    if (e.actionName !== Tracker.Events.QOE_AGGREGATE) continue;
+    if (!isForced && qoeKpisUnchanged(snapshots, e)) {
+      filtered.splice(i, 1);
+    } else {
+      saveQoeKpiSnapshot(snapshots, e);
+    }
+  }
+}

package/src/videoConfiguration.js

@@ -15,18 +15,42 @@ class VideoConfiguration {
    * @returns {boolean} True if configuration is valid and set
    */
 
-  setConfiguration(userInfo, config) {
-    if (!this.validateRequiredFields(userInfo)) {
+  setConfiguration(userInfo, config, src) {
+    const validated = src === "Vega"
+      ? this.validateVegaFields(userInfo)
+      : this.validateRequiredFields(userInfo);
+    if (!validated) {
       return false;
     }
     if (!this.validateConfigFields(config)) {
       return false;
     }
-    this.initializeGlobalConfig(userInfo, config);
+    this.initializeGlobalConfig(userInfo, config, src);
     Log.notice("Video analytics configuration initialized successfully");
     return true;
   }
 
+  /**
+   * Validates required Vega configuration fields.
+   * @param {object} info
+   * @returns {boolean} True if valid
+   */
+  validateVegaFields(info) {
+    if (!info || typeof info !== "object") {
+      Log.error("Configuration must be an object");
+      return false;
+    }
+    if (!info.applicationToken) {
+      Log.error("applicationToken is required");
+      return false;
+    }
+    if (!["US", "EU", "staging", "GOV"].includes(info.endpoint)) {
+      Log.error("Invalid endpoint (must be US, EU, staging, or GOV)");
+      return false;
+    }
+    return true;
+  }
+
   /**
    * Validates required configuration fields.
    * @param {object} config - Configuration to validate
@@ -92,22 +116,79 @@ class VideoConfiguration {
       return false;
     }
 
-    const { qoeAggregate } = config;
+    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 Constants.DEFAULT_QOE_INTERVAL_FACTOR
+   * if the value is not a positive integer.
+   * @param {*} value
+   * @returns {number}
+   */
+  sanitizeQoeIntervalFactor(value) {
+    if (value === undefined || value === null) return Constants.DEFAULT_QOE_INTERVAL_FACTOR;
+    if (typeof value === "number" && Number.isInteger(value) && value >= 1) return value;
+    Log.warn(`Invalid qoeIntervalFactor "${value}" — must be a positive integer. Defaulting to ${Constants.DEFAULT_QOE_INTERVAL_FACTOR}.`);
+    return Constants.DEFAULT_QOE_INTERVAL_FACTOR;
+  }
+
   /**
    * Initializes the global NRVIDEO configuration object.
    * @param {object} userInfo - User provided configuration
    * @param {object} [config] - Optional configuration object
    */
-  initializeGlobalConfig(userInfo, config) {
+  initializeGlobalConfig(userInfo, config, src) {
+    // Vega path: write `globalThis.__NRVIDEO_CD__` with info+config only.
+    // The harvester is owned by `connectedDeviceAgent.js` as a module singleton — no
+    // harvester field on this global.
+    if (src === "Vega") {
+      globalThis.__NRVIDEO_CD__ = {
+        info: {
+          accountId: userInfo.accountId,
+          applicationToken: userInfo.applicationToken,
+          endpoint: userInfo.endpoint,
+          ...(userInfo.appName ? { appName: userInfo.appName } : {}),
+          ...(userInfo.applicationID ? { applicationID: userInfo.applicationID } : {}),
+          ...(userInfo.deviceInfo ? { deviceInfo: userInfo.deviceInfo } : {}),
+        },
+        config: {
+          qoeAggregate: config?.qoeAggregate ?? true,
+          qoeIntervalFactor: this.sanitizeQoeIntervalFactor(config?.qoeIntervalFactor),
+          obfuscate: this.filterObfuscateRules(config?.obfuscate),
+        },
+      };
+      return;
+    }
 
     let { licenseKey, appName, region, beacon, applicationID } = userInfo;
 
@@ -128,6 +209,8 @@ class VideoConfiguration {
       },
       config: {
         qoeAggregate: config?.qoeAggregate ?? true,
+        qoeIntervalFactor: this.sanitizeQoeIntervalFactor(config?.qoeIntervalFactor),
+        obfuscate: this.filterObfuscateRules(config?.obfuscate),
       }
     };
   }
@@ -142,8 +225,8 @@ const videoConfiguration = new VideoConfiguration();
  * @param {object} [config] - Optional configuration object
  * @returns {boolean} True if configuration was set successfully
  */
-export function setVideoConfig(info, config) {
-  return videoConfiguration.setConfiguration(info, config);
+export function setVideoConfig(info, config, src) {
+  return videoConfiguration.setConfiguration(info, config, src);
 }
 
 export { videoConfiguration };

package/src/videotracker.js

@@ -44,6 +44,7 @@ class VideoTracker extends Tracker {
      */
     this._lastBufferType = null;
     this._userId = null;
+    this._src = null;
 
     options = options || {};
     this.setOptions(options);
@@ -83,6 +84,16 @@ class VideoTracker extends Tracker {
       if (typeof options.isAd === "boolean") {
         this.setIsAd(options.isAd);
       }
+      if (options.src !== undefined) {
+        if (this._src !== null && this._src !== options.src) {
+          Log.warn(`setOptions: src is locked to '${this._src}'. Ignoring override '${options.src}'.`);
+        } else {
+          this._src = options.src;
+          if (this.adsTracker && this.adsTracker._src == null) {
+            this.adsTracker._src = this._src;
+          }
+        }
+      }
       Tracker.prototype.setOptions.apply(this, arguments);
     }
   }
@@ -134,6 +145,12 @@ class VideoTracker extends Tracker {
       this.adsTracker = tracker;
       this.adsTracker.setIsAd(true);
       this.adsTracker.parentTracker = this;
+      // Propagate src so ads events route to the same pipeline as content events.
+      // Covers the case where setAdsTracker is called after the content tracker
+      // is fully initialised and this._src is already set.
+      if (this._src != null && tracker._src == null) {
+        tracker._src = this._src;
+      }
       this.adsTracker.on("*", funnelAdEvents.bind(this));
     }
   }
@@ -239,6 +256,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) {
@@ -273,7 +305,7 @@ class VideoTracker extends Tracker {
    * saving the current rendition and thus preventing interferences with RENDITION_CHANGE events.
    */
   getRenditionShift(saveNewRendition) {
-    let current = this.getRenditionBitrate();
+    let current = this.getManifestBitrate();
     let last;
     if (this.isAd()) {
       last = this._lastAdRendition;
@@ -449,7 +481,7 @@ class VideoTracker extends Tracker {
     att["instrumentation.name"] = this.getInstrumentationName();
     att["instrumentation.version"] = this.getInstrumentationVersion();
     att["enduser.id"] = this._userId;
-    att["src"] = "Browser";
+    att["src"] = this._src || "Browser";
 
     if (type === "customAction") return att;
 
@@ -465,12 +497,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 +526,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();
@@ -523,26 +560,24 @@ class VideoTracker extends Tracker {
 
     if(this.state.isStarted && !this.isAd()) {
       this.state.trackContentBitrateState(att.contentBitrate);
+      this.state.trackDownloadRate(att.contentNetworkDownloadBitrate);
+      this.state.addPlayedRendition(att.contentRenditionHeight, att.contentRenditionWidth);
     }
 
     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);
+    // Add QOE v1.1 attributes (for content only, not ads)
+    if (!this.isAd()) {
+      this.state.getQoeAttributes(att);
       const qoe = att.qoe;
       for (let key in this.customData) {
-          qoe[key] = this.customData[key];
+        qoe[key] = this.customData[key];
       }
+    }
+
+    return att;
   }
 
   /**
@@ -610,15 +645,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);
+
+        const harvester = this.getHarvester?.();
+        harvester?.setBeforeDrainCallback(() => {
+          if (this.state) {
+            const freshKpis = this.state.getQoeAttributes({}).qoe;
+            harvester.refreshQoeKpis(freshKpis, this.getViewId());
+          }
+        });
       }
       //this.send(ev, att);
       this.startHeartbeat();
@@ -640,7 +683,10 @@ class VideoTracker extends Tracker {
         ev = VideoTracker.Events.AD_END;
         att.timeSinceAdRequested = this.state.timeSinceRequested.getDeltaTime();
         att.timeSinceAdStarted = this.state.timeSinceStarted.getDeltaTime();
-        if (this.parentTracker) this.parentTracker.state.isPlaying = true;
+        if (this.parentTracker) {
+          this.parentTracker.state.isPlaying = true;
+          this.parentTracker.state.timeSincePaused.reset();
+        }
         this.state.stopAdsTime();
       } else {
         ev = VideoTracker.Events.CONTENT_END;
@@ -658,9 +704,15 @@ class VideoTracker extends Tracker {
       this.state.goViewCountUp();
       this.state.totalPlaytime = 0;
       if(!this.isAd()) {
+        const harvester = this.getHarvester?.();
+        // Force QoE to be included in the next harvest cycle at content end
+        harvester?.forceNextQoeCycle?.();
+        // Clear the before-drain callback so the next harvest doesn't overwrite
+        // the final QoE (already in buffer) with zeroed-out state values
+        harvester?.setBeforeDrainCallback?.(null);
         // reset the states after the view count is up
-          if(this.adsTracker) this.adsTracker.state.clearTotalAdsTime();
-          this.state.resetViewIdTrackedState();
+        if(this.adsTracker) this.adsTracker.state.clearTotalAdsTime();
+        this.state.resetViewIdTrackedState();
       }
     }
   }
@@ -679,8 +731,6 @@ class VideoTracker extends Tracker {
       this.isAd()
         ? this.sendVideoAdAction(ev, att)
         : this.sendVideoAction(ev, att);
-
-      //this.send(ev, att);
     }
   }
 
@@ -865,7 +915,25 @@ class VideoTracker extends Tracker {
     att = att || {};
     att.timeSinceLastRenditionChange =
       this.state.timeSinceLastRenditionChange.getDeltaTime();
-    att.shift = this.getRenditionShift(true);
+
+    const {oldBitrate, newBitrate} = att;
+
+    if (!this.isAd() && oldBitrate !== undefined && newBitrate !== undefined) {
+      if (newBitrate > oldBitrate) {
+        att.shift = "up";
+        this.state.totalSwitchUps += 1;
+      } else if (newBitrate < oldBitrate) {
+        att.shift = "down";
+        this.state.totalSwitchDowns += 1;
+      } else {
+        att.shift = null;
+      }
+    }
+
+    // Remove internal tracking fields before sending to analytics
+    delete att.oldBitrate;
+    delete att.newBitrate;
+
     let ev;
     if (this.isAd()) {
       ev = VideoTracker.Events.AD_RENDITION_CHANGE;