@newrelic/video-core 3.1.1 → 3.2.0-beta-0

package/CHANGELOG.md

@@ -2,6 +2,11 @@
 
 All notable changes to this project will be documented in this file.
 
+## [3.2.1] - 2025/07/30
+
+### Breaking Change
+
+- Decoupled from browser agent, now uses its own harvesting system for independent data collection.
 
 ## [3.1.1] - 2025/06/09
 
@@ -13,11 +18,11 @@ All notable changes to this project will be documented in this file.
 
 ### Enhancements
 
-* **Publishing to npm:** The package can now be published to npm, making it easily accessible.
+- **Publishing to npm:** The package can now be published to npm, making it easily accessible.
 
 ### Build
 
-* **Distribution Formats:** Added `cjs`, `esm`, and `umd` builds to the `dist` folder, ensuring compatibility with CommonJS, ES Modules, and UMD module formats.
+- **Distribution Formats:** Added `cjs`, `esm`, and `umd` builds to the `dist` folder, ensuring compatibility with CommonJS, ES Modules, and UMD module formats.
 
 ## [3.0.0] - 2025/02/20
 

package/README.md

@@ -2,6 +2,9 @@
 
 # New Relic Video Core - JavaScript
 
+> **⚠️ BETA VERSION NOTICE**  
+> This version is currently in **beta phase** and is under active development. Features and APIs may change without notice. Use with caution in production environments and expect potential breaking changes in future releases.
+
 The New Relic video tracking core library is the base for all video trackers in the browser platform. It contains the classes and core mechanisms used by the player specific trackers.
 It segregates the events into different event types based on action, such as video-related events going to `VideoAction`, ad-related events to `VideoAdAction`, errors to `VideoErrorAction`, and custom actions to `VideoCustomAction`.
 
@@ -36,10 +39,20 @@ Add **scripts** inside `dist` folder to your page.
 `nrvideo` provides a class called `VideoTracker` that will serve as an interface with
 _Browser Agent_, allowing you to manage and send events to New Relic.
 
-First of all, you have to add a tracker in the core class:
+First, configure the authentication options and initialize a tracker:
 
 ```javascript
-var tracker = new VideoTracker(player);
+const options = {
+  info: {
+    beacon: "your-beacon-url.nr-data.net",
+    errorBeacon: "your-beacon-url.nr-data.net",
+    licenseKey: "your-license-key",
+    applicationID: "your-application-id",
+    sa: 1,
+  },
+};
+
+const tracker = new VideoTracker(player, options);
 ```
 
 Once the tracker is added, any event it emits will be sent to New Relic and processed by the following functions:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@newrelic/video-core",
-  "version": "3.1.1",
+  "version": "3.2.0-beta-0",
   "description": "New Relic video tracking core library",
   "main": "./dist/cjs/index.js",
   "module": "./dist/esm/index.js",
@@ -45,12 +45,13 @@
   "files": [
     "THIRD_PARTY_NOTICES.md",
     "dist",
+    "src",
     "CHANGELOG.md",
     "LICENSE",
     "README.md",
     "!test"
   ],
-   "publishConfig": {
+  "publishConfig": {
     "access": "public"
   }
 }

package/src/agent.js

@@ -0,0 +1,6 @@
+import { NRVideoEventAggregator } from "./eventAggregator.js";
+import { NRVideoHarvester } from "./harvester.js";
+
+export const customEventAggregator = new NRVideoEventAggregator();
+const harvester = new NRVideoHarvester(customEventAggregator);
+harvester.startTimer();

package/src/authConfiguration.js

@@ -0,0 +1,138 @@
+import Constants from "./constants";
+
+const { COLLECTOR } = Constants;
+
+/**
+ * Validates and initializes New Relic video tracking information.
+ * @param {object} info - The options object containing authentication information.
+ * @param {string} info.licenseKey - The New Relic license key.
+ * @param {string} [info.appName] - The name of the application (required if no applicationID).
+ * @param {string} [info.region] - The region for the New Relic collector (required if no beacon).
+ * @param {string} [info.beacon] - Custom beacon URL (optional, overrides region-based beacon).
+ * @param {string} [info.sa] - Security attributes (optional).
+ * @param {string} [info.applicationID] - Application ID for beacon-based configuration (optional).
+ * @returns {boolean} True if configuration was set successfully, false otherwise.
+ * @throws {Error} Throws error for invalid configuration parameters.
+ */
+export function setAuthConfig(info) {
+  try {
+    // Input validation
+    if (!info || typeof info !== "object" || Array.isArray(info)) {
+      throw new Error("setAuthConfig: info parameter must be a valid object");
+    }
+
+    if (isAuthorised(info)) {
+      const { licenseKey, appName, region, beacon, sa, applicationID } = info;
+
+      // Initialize NRVIDEO global object
+      window.NRVIDEO = window.NRVIDEO || {};
+
+      // Determine beacon URL with fallback
+      let beaconUrl = beacon;
+      if (!beaconUrl && region) {
+        if (!COLLECTOR[region]) {
+          throw new Error(
+            `setAuthConfig: Invalid region '${region}'. Valid regions: ${Object.keys(
+              COLLECTOR
+            ).join(", ")}`
+          );
+        }
+        beaconUrl = COLLECTOR[region];
+      }
+
+      window.NRVIDEO.info = {
+        beacon: beaconUrl,
+        licenseKey,
+        applicationID: applicationID || null,
+        appName: appName || null,
+        sa: sa || 0,
+      };
+
+      return true;
+    } else {
+      const validationError = getValidationError(info);
+      throw new Error(`setAuthConfig: ${validationError}`);
+    }
+  } catch (error) {
+    console.error("setAuthConfig:", error.message);
+    return false;
+  }
+}
+
+/**
+ * Checks if the provided information contains valid authentication parameters.
+ * @param {object} info - The options object.
+ * @returns {boolean} True if authorized, false otherwise.
+ */
+function isAuthorised(info) {
+  if (!info || typeof info !== "object") {
+    return false;
+  }
+
+  const { licenseKey, appName, region, applicationID, beacon } = info;
+
+  // License key is always required
+  if (
+    !licenseKey ||
+    typeof licenseKey !== "string" ||
+    licenseKey.trim().length === 0
+  ) {
+    return false;
+  }
+
+  // Two valid configuration modes:
+  // 1. applicationID + beacon (for direct beacon configuration)
+  // 2. appName + region (for region-based beacon resolution)
+  if (applicationID) {
+    return !!(beacon && typeof beacon === "string" && beacon.trim().length > 0);
+  }
+
+  return !!(
+    appName &&
+    typeof appName === "string" &&
+    appName.trim().length > 0 &&
+    region &&
+    typeof region === "string" &&
+    region.trim().length > 0
+  );
+}
+
+/**
+ * Provides detailed validation error message for debugging.
+ * @param {object} info - The options object.
+ * @returns {string} Detailed error message.
+ */
+function getValidationError(info) {
+  if (!info || typeof info !== "object") {
+    return "info parameter must be a valid object";
+  }
+
+  const { licenseKey, appName, region, applicationID, beacon } = info;
+
+  if (
+    !licenseKey ||
+    typeof licenseKey !== "string" ||
+    licenseKey.trim().length === 0
+  ) {
+    return "licenseKey is required and must be a non-empty string";
+  }
+
+  if (applicationID) {
+    if (!beacon || typeof beacon !== "string" || beacon.trim().length === 0) {
+      return "beacon URL is required when using applicationID";
+    }
+  } else {
+    if (
+      !appName ||
+      typeof appName !== "string" ||
+      appName.trim().length === 0
+    ) {
+      return "appName is required when not using applicationID";
+    }
+    if (!region || typeof region !== "string" || region.trim().length === 0) {
+      return "region is required when not using applicationID";
+    }
+  }
+
+  return "configuration validation failed";
+}

package/src/chrono.js

@@ -0,0 +1,78 @@
+/**
+ * This class calculates time lapses between two points on time.
+ */
+class Chrono {
+  /**
+   * Constructor
+   */
+  constructor() {
+    this.reset();
+  }
+
+  /** Reset chrono values. */
+  reset() {
+    /** Start time */
+    this.startTime = 0;
+
+    /** Stop time */
+    this.stopTime = 0;
+
+    /**
+     * If you set an offset in a chrono, its value will be added getDeltaTime and stop.
+     *
+     * @example
+     * let chrono = new Chrono()
+     * chrono.offset = 500
+     * chrono.start()
+     * process.sleep(500)
+     * chrono.stop() // Will return 1000
+     *
+     * @type {number}
+     */
+    this.offset = 0;
+  }
+
+  /**
+   * Returns the time between start() and the last stop() in ms. Returns null if start wasn't
+   * called.
+   * @return {(number|null)} Time lapse in ms.
+   */
+  getDeltaTime() {
+    if (this.startTime) {
+      return this.offset + (new Date().getTime() - this.startTime);
+    } else {
+      return null;
+    }
+  }
+
+  /**
+   * Starts the chrono.
+   */
+  start() {
+    this.startTime = new Date().getTime();
+    this.stopTime = 0;
+  }
+
+  /**
+   * Stops the timer and returns delta time.
+   * @return {(number|null)} Returns the delta time
+   */
+  stop() {
+    this.stopTime = new Date().getTime();
+    return this.getDeltaTime();
+  }
+
+  /**
+   * Creates a copy of the chrono.
+   * @returns {Chrono} Cloned chrono
+   */
+  clone() {
+    var chrono = new Chrono();
+    chrono.startTime = this.startTime;
+    chrono.stopTime = this.stopTime;
+    chrono.offset = this.offset;
+    return chrono;
+  }
+}
+
+export default Chrono;

package/src/constants.js

@@ -0,0 +1,43 @@
+/**
+ * Constants for the library.
+ * @class Constants
+ * @static
+ */
+class Constants {}
+
+/**
+ * Enum for types/positions of ads.
+ * @example var type = Constants.AdPositions.PRE
+ * @enum {String}
+ */
+Constants.AdPositions = {
+  /** For ads shown before the content. */
+  PRE: "pre",
+  /** For ads shown during the content. */
+  MID: "mid",
+  /** For ads shown after the content. */
+  POST: "post",
+};
+
+Constants.INTERVAL = 10000;
+Constants.MAX_EVENTS_PER_BATCH = 1000;
+Constants.MAX_PAYLOAD_SIZE = 1; // 1mb
+Constants.MAX_BEACON_SIZE = 0.0625; // 64kb
+Constants.MAX_EVENT_SIZE = 0.0625; // 64kb
+Constants.VALID_EVENT_TYPES = [
+  "VideoAction",
+  "VideoAdAction",
+  "VideoErrorAction",
+  "VideoCustomAction",
+];
+
+Constants.COLLECTOR = {
+  US: "bam-cell.nr-data.net",
+  EU: "bam.eu01.nr-data.net",
+  Stage: "staging-bam-cell.nr-data.net",
+  GOV: "gov-bam.nr-data.net",
+};
+
+// "bam.nr-data.net",
+
+export default Constants;

package/src/core.js

@@ -0,0 +1,100 @@
+import Log from "./log";
+import { recordEvent } from "./recordEvent";
+import { setAuthConfig } from "./authConfiguration";
+
+/**
+ * Static class that sums up core functionalities of the library.
+ * @static
+ */
+class Core {
+  /**
+   * Add a tracker to the system. Trackers added will start reporting its events to NR's backend.
+   *
+   * @param {(Emitter|Tracker)} tracker Tracker instance to add.
+   */
+  static addTracker(tracker, options) {
+    setAuthConfig(options.info);
+    if (tracker.on && tracker.emit) {
+      trackers.push(tracker);
+      tracker.on("*", eventHandler);
+      if (typeof tracker.trackerInit == "function") {
+        tracker.trackerInit();
+      }
+    } else {
+      Log.error("Tried to load a non-tracker.", tracker);
+    }
+  }
+
+  /**
+   * Disposes and remove given tracker. Removes its listeners.
+   *
+   * @param {Tracker} tracker Tracker to remove.
+   */
+  static removeTracker(tracker) {
+    tracker.off("*", eventHandler);
+    tracker.dispose();
+    let index = trackers.indexOf(tracker);
+    if (index !== -1) trackers.splice(index, 1);
+  }
+
+  /**
+   * Returns the array of trackers.
+   *
+   * @returns {Tracker[]} Array of trackers.
+   */
+  static getTrackers() {
+    return trackers;
+  }
+
+  static send(eventType, actionName, data) {
+    data["timeSinceLoad"] = window.performance.now() / 1000;
+    recordEvent(eventType, { actionName, ...data });
+  }
+
+  /**
+   * Sends an error event. This may be used for external errors launched by the app, the network or
+   * any external factor. Note that errors within the player are normally reported with
+   * tracker.sendError, so this method should not be used to report those.
+   *
+   * @param {object} att attributes to be sent along the error.
+   */
+  static sendError(att) {
+    Core.send("ERROR", att);
+  }
+}
+
+let trackers = [];
+let isErrorShown = false;
+
+/**
+ * Logs and sends given event.
+ *
+ * @private
+ * @param {Event} e Event
+ */
+function eventHandler(e) {
+  let data = cleanData(e.data);
+  if (Log.level <= Log.Levels.DEBUG) {
+    Log.notice("Sent", e.type, data);
+  } else {
+    Log.notice("Sent", e.type);
+  }
+
+  Core.send(e.eventType, e.type, data);
+}
+
+/**
+ * Cleans given object, removing all items with value === null.
+ * @private
+ * @param {Object} data Data to clean
+ * @returns {Object} Cleaned object
+ */
+function cleanData(data) {
+  let ret = {};
+  for (let i in data) {
+    if (data[i] !== null && typeof data[i] !== "undefined") ret[i] = data[i];
+  }
+  return ret;
+}
+
+export default Core;

package/src/emitter.js

@@ -0,0 +1,81 @@
+/**
+ * This base class implements a basic behavior of listeners and events. Extend this object to have
+ * this feature built-in inside your classes.
+ *
+ * @class Emitter
+ */
+class Emitter {
+  /**
+   * Sets a listener to a given event. Use {@link emit} to trigger those events.
+   * Pass '*' to listen ALL events.
+   *
+   * @param {string} event Name of the event.
+   * @param {function} callback Callback of the event. Receives event and data.
+   * @return this
+   */
+  on(event, callback) {
+    this._listeners = this._listeners || {};
+    if (typeof callback === "function") {
+      this._listeners[event] = this._listeners[event] || [];
+      this._listeners[event].push(callback);
+      return this;
+    }
+  }
+
+  /**
+   * Removes given callback from the listeners of this object.
+   *
+   * @param {string} event Name of the event.
+   * @param {function} callback Callback of the event.
+   * @return this
+   */
+  off(event, callback) {
+    this._listeners = this._listeners || {};
+
+    if (this._listeners[event]) {
+      var index = this._listeners[event].indexOf(callback);
+      if (index !== -1) {
+        this._listeners[event].splice(index, 1);
+      }
+    }
+    return this;
+  }
+
+  /**
+   * Emits given event, triggering all the associated callbacks.
+   *
+   * @param {string} event Name of the event.
+   * @param {object} [data] Custom data to be sent to the callbacks.
+   * @return this
+   */
+  emit(eventType, event, data) {
+    this._listeners = this._listeners || {};
+    data = data || {};
+
+    if (Array.isArray(this._listeners[event])) {
+      this._listeners[event].forEach((callback) => {
+        callback.call(this, {
+          eventType,
+          type: event,
+          data: data,
+          target: this,
+        });
+      });
+    }
+
+    if (Array.isArray(this._listeners["*"])) {
+      this._listeners["*"].forEach((callback) => {
+        callback.call(this, {
+          eventType,
+          type: event,
+          data: data,
+          target: this,
+        });
+      });
+    }
+
+    return this;
+  }
+}
+
+export default Emitter;

package/src/eventAggregator.js

@@ -0,0 +1,66 @@
+import { getPayloadSize } from "./utils";
+import Constants from "./constants";
+const { MAX_EVENTS_PER_BATCH, MAX_PAYLOAD_SIZE } = Constants;
+
+/**
+ * A simple aggregator that queues raw events without any statistical aggregation.
+ * It includes the necessary save/reload logic for the harvester's retry mechanism.
+ */
+export class NRVideoEventAggregator {
+  #queue = [];
+  #retryQueue = [];
+
+  /**
+   * Checks if the event queue is empty.
+   * @returns {boolean}
+   */
+  isEmpty() {
+    return this.#queue.length === 0 && this.#retryQueue.length === 0;
+  }
+
+  /**
+   * Drains the entire queue and returns all events.
+   * Called by the harvester to begin the chunking process.
+   */
+  drain() {
+    const allEvents = [...this.#retryQueue, ...this.#queue];
+    this.#queue = []; // Clear the active queue
+    this.#retryQueue = []; // Clear the retry queue
+
+    return allEvents;
+  }
+
+  /**
+   * Adds a complete, enriched event object to the queue.
+   * @param {object} eventObject - The event to queue.
+   */
+  add(eventObject) {
+    this.#queue.push(eventObject);
+  }
+
+  // --- Methods for the Harvester ---
+
+  /**
+   * Cleans up the queue after a harvest attempt, based on the result.
+   * @param {object} result - The result from the harvester, containing a 'retry' flag.
+   */
+  postHarvestCleanup(result) {
+    if (!result.retry || !result.chunk?.length) {
+      this.#retryQueue = [];
+      return;
+    }
+
+    while (
+      this.#retryQueue.length > 0 &&
+      (getPayloadSize(this.#retryQueue) + getPayloadSize(result.chunk) >
+        MAX_PAYLOAD_SIZE ||
+        this.#retryQueue.length + result.chunk.length > MAX_EVENTS_PER_BATCH)
+    ) {
+      // Removes the oldest item from the retry queue to make space
+      this.#retryQueue.shift();
+    }
+
+    // Add the entire failed chunk to the retry queue.
+    this.#retryQueue.push(...result.chunk); // result.chunk will be never greater than 1mb or 1000
+  }
+}