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

package/src/log.js

@@ -0,0 +1,323 @@
+/**
+ * Static Log class
+ *
+ * @class
+ * @static
+ */
+class Log {
+  /**
+   * Sends an error console log.
+   * @param {...any} [msg] Message to show
+   * @static
+   */
+  static error(...msg) {
+    _report(msg, Log.Levels.ERROR, "darkred");
+  }
+
+  /**
+   * Sends a warning console log.
+   * @method Log.warn
+   * @static
+   * @param {...any} msg Message to show
+   */
+  static warn(...msg) {
+    _report(msg, Log.Levels.WARNING, "darkorange");
+  }
+
+  /**
+   * Sends a notice console log.
+   * @method Log.notice
+   * @static
+   * @param {...any} msg Message to show
+   */
+  static notice(...msg) {
+    _report([].slice.call(arguments), Log.Levels.NOTICE, "darkcyan");
+  }
+
+  /**
+   * Sends a debug message to console.
+   * @method Log.debug
+   * @static
+   * @param {...any} msg Message to show
+   */
+  static debug(...msg) {
+    _report(msg, Log.Levels.DEBUG, "indigo");
+  }
+
+  /**
+   * This utility method will add most of the HTML5 common event listeners to the player sent.
+   * Events will be reported as DEBUG level messages.
+   *
+   * @example
+   * // Already included events:
+   * ['canplay', 'buffering', 'waiting', 'ended', 'play', 'playing', 'pause', 'resume', 'error',
+   * 'abort', 'seek', 'seeking', 'seeked', 'stalled', 'dispose', 'loadeddata', 'loadstart',
+   * 'loadedmetadata']
+   *
+   * @method Log.debugCommonVideoEvents
+   * @static
+   * @param {object|function} o Object to attach the events.
+   * @param {array} [extraEvents]
+   * An array of extra events to watch. ie:  ['timeupdate', 'progress'].
+   * If the first item is null, no common events will be added.
+   * @param {function} [report] Callback function called to report events.
+   * Default calls Log.debug()
+   */
+  static debugCommonVideoEvents(o, extraEvents, report) {
+    try {
+      if (Log.level <= Log.Levels.DEBUG) {
+        report =
+          report ||
+          function (e) {
+            Log.debug("Event: " + e.type);
+          };
+
+        var playerEvents = [
+          "canplay",
+          "buffering",
+          "waiting",
+          "ended",
+          "play",
+          "playing",
+          "pause",
+          "resume",
+          "error",
+          "abort",
+          "seek",
+          "seeking",
+          "seeked",
+          "stalled",
+          "dispose",
+          "loadeddata",
+          "loadstart",
+          "loadedmetadata",
+        ];
+        if (extraEvents) {
+          if (extraEvents[0] === null) {
+            extraEvents.shift();
+            playerEvents = extraEvents;
+          } else {
+            playerEvents = playerEvents.concat(extraEvents);
+          }
+        }
+
+        for (var i = 0; i < playerEvents.length; i++) {
+          if (typeof o === "function") {
+            o.call(window, playerEvents[i], report);
+          } else if (o.on) {
+            o.on(playerEvents[i], report);
+          } else if (o.addEventListener) {
+            o.addEventListener(playerEvents[i], report);
+          } else if (o.addEventHandler) {
+            o.addEventHandler(playerEvents[i], report);
+          } else {
+            Log.warn(
+              "debugCommonVideoEvents: No common listener function found for ",
+              o
+            );
+          }
+        }
+      }
+    } catch (err) {
+      Log.warn(err);
+    }
+  }
+}
+
+/**
+ * Enum for log levels
+ * @enum {integer}
+ * @static
+ * @var
+ */
+Log.Levels = {
+  /** No console outputs */
+  SILENT: 5,
+  /** Console will show errors */
+  ERROR: 4,
+  /** Console will show warnings */
+  WARNING: 3,
+  /** Console will show notices (ie: life-cyrcle logs) */
+  NOTICE: 2,
+  /** Console will show debug messages. */
+  DEBUG: 1,
+  /** Show all messages. */
+  ALL: 0,
+};
+
+/**
+ * Only logs of this imporance or higher will be shown.
+ * @example Log.level = Log.Levels.ALL
+ * @default Log.Levels.ERROR
+ * @static
+ */
+Log.level = Log.Levels.ERROR;
+
+/**
+ * If true, logs will be outputed with colors.
+ * @default true
+ * @static
+ */
+Log.colorful = true;
+
+/**
+ * If true, logs will include the time mark.
+ * @default true
+ * @static
+ */
+Log.includeTime = true;
+
+/**
+ * Prefix included at the start of every log.
+ * @default '[New Relic]'
+ * @static
+ */
+Log.prefix = "[nrvideo]";
+
+// PRIVATE MEMBERS
+
+/**
+ * Returns a console message
+ *
+ * @private
+ * @param {array} msg Message array, error object or array of messages.
+ * @param {Log.Level} [level=Log.Levels.NOTICE] Defines the level of the error sent.
+ * Only errors with higher or equal level than Log.logLevel will be displayed.
+ * @param {string} [color='darkgreen'] Color of the header
+ * @see {@link Log.level}
+ */
+function _report(msg, level, color) {
+  level = level || Log.Levels.NOTICE;
+  color = color || "darkcyan";
+
+  var prefix = Log.prefix;
+  if (Log.includeTime) prefix += _getCurrentTime() + " ";
+  prefix += _level2letter(level) + ":";
+
+  // Show messages in actual console if level is enought
+  if (Log.level <= level && level !== Log.Levels.SILENT) {
+    if (
+      !Log.colorful ||
+      (typeof document !== "undefined" && document.documentMode)
+    ) {
+      // document.documentMode exits only in IE
+      _plainReport(msg, prefix);
+    } else {
+      // choose log method
+      var logMethod;
+      if (level === Log.Levels.ERROR && console.error) {
+        logMethod = console.error;
+      } else if (level === Log.Levels.WARNING && console.warn) {
+        logMethod = console.warn;
+      } else if (level === Log.Levels.DEBUG && console.debug) {
+        // NOTE: for some reason console.debug doesn't work on CAF Receivers.
+        if (window.cast == undefined) {
+          logMethod = console.debug;
+        } else {
+          logMethod = console.log;
+        }
+      } else {
+        logMethod = console.log;
+      }
+
+      // print message
+      prefix = "%c" + prefix;
+      msg.splice(0, 0, prefix, "color: " + color);
+      logMethod.apply(console, msg);
+    }
+  }
+}
+
+/**
+ * Returns the current time in format hh:mm:ss.mmm (with trailing 0s)
+ * @private
+ * @return {string} Current time.
+ */
+function _getCurrentTime() {
+  var d = new Date();
+  var hh = ("0" + d.getDate()).slice(-2);
+  var mm = ("0" + d.getMinutes()).slice(-2);
+  var ss = ("0" + d.getSeconds()).slice(-2);
+  var mmm = ("00" + d.getMilliseconds()).slice(-3);
+  return "[" + hh + ":" + mm + ":" + ss + "." + mmm + "]";
+}
+
+/**
+ * Returns a console message without style
+ *
+ * @private
+ * @param {(string|object|array)} msg Message string, object or array of messages.
+ * @param {string} prefix Prefix of the message.
+ */
+function _plainReport(msg, prefix) {
+  if (msg instanceof Array) {
+    for (var m in msg) {
+      _plainReport(msg[m], prefix);
+    }
+  } else {
+    if (typeof msg === "string") {
+      console.log(prefix + " " + msg);
+    } else {
+      console.log(prefix + "↵");
+      console.log(msg);
+    }
+  }
+}
+
+const _letters = {
+  4: "e", // Error
+  3: "w", // Warning
+  2: "n", // Notice
+  1: "d", // Debug
+};
+
+/**
+ * Transforms a level to a letter to identify every message.
+ *
+ * @private
+ * @param {sLog.Level} level Level of the message
+ */
+function _level2letter(level) {
+  return _letters[level];
+}
+
+/**
+ * This function is automatically executed at load.
+ * Will search inside window.location.search for attribute 'nrvideo-debug=X'.
+ * X can have one of these values, that will modify Log.Levels.
+ * 5: SILENT,
+ * 4: ERROR,
+ * 3: WARNING,
+ * 2: NOTICE,
+ * 1: DEBUG,
+ *
+ * If nrvideo-colors=false is present, Log.colorful will be set to false.
+ *
+ * @private
+ */
+function _loadLevelFromUrl() {
+  if (
+    typeof window !== "undefined" &&
+    window.location &&
+    window.location.search
+  ) {
+    var m = /\?.*&*nrvideo-debug=(.+)/i.exec(window.location.search);
+    if (m !== null) {
+      if (m[1] === "true") {
+        Log.level = Log.Levels.ALL;
+      } else {
+        Log.level = m[1];
+      }
+    }
+
+    var m2 = /\?.*&*nrvideo-colors=false/i.exec(window.location.search);
+    if (m2 !== null) {
+      Log.colorful = false;
+    }
+  }
+}
+
+// Execute load level
+_loadLevelFromUrl();
+
+export default Log;

package/src/recordEvent.js

@@ -0,0 +1,68 @@
+import { customEventAggregator } from "./agent.js";
+import { getPayloadSize } from "./utils.js";
+import Constants from "./constants";
+
+const { VALID_EVENT_TYPES, MAX_EVENT_SIZE } = Constants;
+
+/**
+ * Records a video event with the specified type and attributes
+ * @param {string} eventType - The type of event to record
+ * @param {Object} attributes - Additional attributes to include with the event
+ * @returns {boolean} - True if event was recorded successfully, false otherwise
+ */
+export function recordEvent(eventType, attributes = {}) {
+  // Input validation
+  if (
+    typeof eventType !== "string" ||
+    eventType.length === 0 ||
+    !VALID_EVENT_TYPES.includes(eventType)
+  ) {
+    console.warn("recordEvent: Invalid eventType provided:", eventType);
+    return false;
+  }
+
+  // Validate attributes parameter
+  if (
+    attributes !== null &&
+    (typeof attributes !== "object" || Array.isArray(attributes))
+  ) {
+    console.warn("recordEvent: attributes must be a plain object");
+    return false;
+  }
+
+  // Ensure attributes is an object (handle null case)
+  attributes = attributes || {};
+
+  // Check if NRVIDEO is properly initialized
+  if (!window.NRVIDEO || !window.NRVIDEO.info) {
+    console.error("recordEvent: NRVIDEO not properly initialized");
+    return false;
+  }
+
+  try {
+    const { appName } = window.NRVIDEO.info;
+
+    const eventObject = {
+      ...attributes,
+      eventType,
+      appName,
+      timestamp: Date.now(),
+    };
+
+    // Check event size to prevent oversized payloads
+    const eventSize = getPayloadSize(eventObject);
+
+    if (eventSize > MAX_EVENT_SIZE) {
+      console.warn(
+        `recordEvent: Event size (${eventSize} bytes) exceeds maximum (${MAX_EVENT_SIZE} bytes)`
+      );
+      return false;
+    }
+
+    customEventAggregator.add(eventObject);
+    return true;
+  } catch (error) {
+    console.error("recordEvent: Error recording event:", error);
+    return false;
+  }
+}

package/src/tracker.js

@@ -0,0 +1,281 @@
+import pkg from "../package.json";
+import Emitter from "./emitter";
+import Chrono from "./chrono";
+import Constants from "./constants";
+
+/**
+ * Tracker class provides the basic logic to extend Newrelic's Browser Agent capabilities.
+ * Trackers are designed to listen third party elements (like video tags, banners, etc.) and send
+ * information over to Browser Agent. Extend this class to create your own tracker, override
+ * registerListeners and unregisterListeners for full coverage!
+ *
+ * @example
+ * Tracker instances should be added to Core library to start sending data:
+ * nrvideo.Core.addTracker(new Tracker())
+ *
+ * @extends Emitter
+ */
+class Tracker extends Emitter {
+  /**
+   * Constructor, receives options. You should call {@see registerListeners} after this.
+   *
+   * @param {Object} [options] Options for the tracker. See {@link setOptions}.
+   */
+  constructor(options) {
+    super();
+
+    /**
+     * If you add something to this custom dictionary it will be added to every action. If you set
+     * any value, it will always override the values returned by the getters.
+     *
+     * @example
+     * If you define tracker.customData.contentTitle = 'a' and tracker.getTitle() returns 'b'.
+     * 'a' will prevail.
+     */
+    this.customData = {};
+
+    /**
+     * Set time between hearbeats, in ms.
+     */
+    this.heartbeat = null;
+
+    /**
+     * Another Tracker instance. Useful to relate ad Trackers to their parent content Trackers.
+     * @type Tracker
+     */
+    this.parentTracker = null;
+
+    /**
+     * Chrono that counts time since this class was instantiated.
+     * @private
+     */
+    this._trackerReadyChrono = new Chrono();
+    this._trackerReadyChrono.start();
+
+    /**
+     * Store the initial table of actions with time 0 ms
+     */
+    this._actionTable = Constants.ACTION_TABLE;
+    this._actionAdTable = Constants.ACTION_AD_TABLE;
+
+    options = options || {};
+    this.setOptions(options);
+  }
+
+  /**
+   * Set options for the Tracker.
+   *
+   * @param {Object} [options] Options for the tracker.
+   * @param {number} [options.heartbeat] Set time between heartbeats. See {@link heartbeat}.
+   * @param {Object} [options.customData] Set custom data. See {@link customData}.
+   * @param {Tracker} [options.parentTracker] Set parent tracker. See {@link parentTracker}.
+   */
+  setOptions(options) {
+    if (options) {
+      if (options.parentTracker) this.parentTracker = options.parentTracker;
+      if (options.customData) this.customData = options.customData;
+      if (options.heartbeat) this.heartbeat = options.heartbeat;
+    }
+  }
+
+  /**
+   * Prepares tracker to dispose. Calls {@see unregisterListeners} and drops references.
+   */
+  dispose() {
+    this.unregisterListeners();
+  }
+
+  /**
+   * Override this method to register listeners to third party elements.
+   *
+   * @example
+   * class SpecificTracker extends Tracker {
+   *  registerListeners() {
+   *    this.player.on('play', () => this.playHandler)
+   *  }
+   *
+   *  playHandler() {
+   *    this.emit(Tracker.Events.REQUESTED)
+   *  }
+   * }
+   */
+  registerListeners() {}
+
+  /**
+   * Override this method to unregister listeners to third party elements created with
+   * {@see registerListeners}.
+   *
+   * @example
+   * class SpecificTracker extends Tracker {
+   *  registerListeners() {
+   *    this.player.on('play', () => this.playHandler)
+   *  }
+   *
+   *  unregisterListeners() {
+   *    this.player.off('play', () => this.playHandler)
+   *  }
+   *
+   *  playHandler() {
+   *    this.emit(Tracker.Events.REQUESTED)
+   *  }
+   * }
+   */
+  unregisterListeners() {}
+
+  /**
+   * Returns heartbeat time interval. 30000 (30s) if not set. See {@link setOptions}.
+   * @return {number} Heartbeat interval in ms.
+   * @final
+   */
+  getHeartbeat() {
+    if (this.state._isAd) {
+      // modifying heartbeat for Ad Tracker
+      return 2000;
+    } else {
+      if (this.heartbeat) {
+        return this.heartbeat;
+      } else if (this.parentTracker && this.parentTracker.heartbeat) {
+        return this.parentTracker.heartbeat;
+      } else {
+        return 30000;
+      }
+    }
+  }
+
+  /**
+   * Starts heartbeating. Interval period set by options.heartbeat. Min 2000 ms.
+   * This method is automaticaly called by the tracker once sendRequest is called.
+   */
+  startHeartbeat() {
+    this._heartbeatInterval = setInterval(
+      this.sendHeartbeat.bind(this),
+      Math.max(this.getHeartbeat(), 2000)
+    );
+  }
+
+  /**
+   * Stops heartbeating. This method is automaticaly called by the tracker.
+   */
+  stopHeartbeat() {
+    if (this._heartbeatInterval) {
+      clearInterval(this._heartbeatInterval);
+    }
+  }
+
+  /**
+   * Heartbeating allows you to call this function each X milliseconds, defined by
+   * {@link getHeartbeat}. This is useful to send regular events to track changes.
+   *
+   * By default it will send {@link Tracker.Events.HEARTBEAT}.
+   * To start heartbeating use {@link startHeartbeat} and to stop them use {@link stopHeartbeat}.
+   *
+   * @example
+   * Override this method to define your own Heartbeat reporting.
+   *
+   * class TrackerChild extends Tracker {
+   *  sendHeartbeat (att) {
+   *    this.send('MY_HEARBEAT_EVENT')
+   *  }
+   * }
+   *
+   * @param {Object} [att] Collection of key:value attributes to send with the request.
+   */
+  sendHeartbeat(att) {
+    this.sendVideoAction(Tracker.Events.HEARTBEAT, att);
+  }
+
+  /**
+   * Override this method to return attributes for actions.
+   *
+   * @example
+   * class SpecificTracker extends Tracker {
+   *  getAttributes(att) {
+   *    att = att || {}
+   *    att.information = 'something'
+   *    return att
+   *  }
+   * }
+   *
+   * @param {object} [att] Collection of key value attributes
+   * @return {object} Filled attributes
+   * @final
+   */
+  getAttributes(att, eventType) {
+    att = att || {};
+    att.trackerName = this.getTrackerName();
+    att.trackerVersion = this.getTrackerVersion();
+    att.coreVersion = pkg.version;
+    att.timeSinceTrackerReady = this._trackerReadyChrono.getDeltaTime();
+
+    for (let key in this.customData) {
+      att[key] = this.customData[key];
+    }
+
+    if (document.hidden != undefined) {
+      att.isBackgroundEvent = document.hidden;
+    }
+
+    return att;
+  }
+
+  /** Override to change of the Version of tracker. ie: '1.0.1' */
+  getTrackerVersion() {
+    return pkg.version;
+  }
+
+  /** Override to change of the Name of the tracker. ie: 'custom-html5' */
+  getTrackerName() {
+    return "base-tracker";
+  }
+
+  /**
+   * Send given event. Will automatically call {@see getAttributes} to fill information.
+   * Internally, this will call {@see Emitter#emit}, so you could listen any event fired.
+   *
+   * @example
+   * tracker.send('BANNER_CLICK', { url: 'http....' })
+   *
+   * @param {string} event Event name
+   * @param {object} [att] Key:value dictionary filled with attributes.
+   */
+
+  /**
+   * getElapsedTime: Calculate the time elapsed between two same actions
+   *
+   */
+
+  sendVideoAction(event, att) {
+    this.emit("VideoAction", event, this.getAttributes(att));
+  }
+
+  sendVideoAdAction(event, att) {
+    this.emit("VideoAdAction", event, this.getAttributes(att));
+  }
+
+  sendVideoErrorAction(event, att) {
+    let ev = this.isAd() ? "adError" : "videoError";
+    this.emit("VideoErrorAction", event, this.getAttributes(att, ev));
+  }
+
+  sendVideoCustomAction(event, att) {
+    this.emit(
+      "VideoCustomAction",
+      event,
+      this.getAttributes(att, "customAction")
+    );
+  }
+}
+
+/**
+ * Enumeration of events fired by this class.
+ *
+ * @static
+ * @memberof Tracker
+ * @enum {string}
+ */
+Tracker.Events = {
+  /** The heartbeat event is sent once every 30 seconds while the video is playing. */
+  HEARTBEAT: "HEARTBEAT",
+};
+
+export default Tracker;