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

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;

package/src/utils.js

@@ -0,0 +1,101 @@
+/**
+ * Makes an API call with retry logic and fallback to sendBeacon for final harvests
+ * @param {Object} params - Request parameters
+ * @param {string} params.url - The URL to send the request to
+ * @param {Object} params.payload - The payload object containing body data
+ * @param {Object} params.options - Request options
+ * @param {boolean} params.options.isFinalHarvest - Whether this is a final harvest on page unload
+ * @param {Function} callback - Callback function to handle the response
+ */
+export function callApi({ url, payload, options = {} }, callback) {
+  // Input validation
+  if (!url || !payload || !callback) {
+    console.error("callApi: Missing required parameters");
+    if (callback) callback({ retry: false, status: 0 });
+    return;
+  }
+
+  // The Browser Agent sends the 'body' part of the payload object as the actual request body.
+  let body;
+  try {
+    body = JSON.stringify(payload.body);
+  } catch (error) {
+    console.error("callApi: Error serializing payload", error);
+    callback({ retry: false, status: 0 });
+    return;
+  }
+
+  // For final harvests on page unload, use sendBeacon for reliability.
+  if (options.isFinalHarvest && navigator.sendBeacon) {
+    try {
+      const success = navigator.sendBeacon(url, body);
+      // sendBeacon returns true if the request was successfully queued
+      callback({ retry: !success, status: success ? 200 : 0 });
+    } catch (e) {
+      // sendBeacon can fail if the payload is too large.
+      callback({ retry: true, status: 0 });
+    }
+    return;
+  }
+
+  fetch(url, {
+    method: "POST",
+    body: body,
+    headers: {
+      "Content-Type": "application/json", // More accurate content type
+    },
+    keepalive: options.isFinalHarvest, // Important for final harvest fallback
+  })
+    .then((response) => {
+      // Check for statuses that indicate a retry is needed.
+      const isRetry = shouldRetry(response.status);
+      callback({
+        retry: isRetry,
+        status: response.status,
+        ok: response.ok,
+      });
+    })
+    .catch(() => {
+      // Any network failure (e.g., no internet) should also trigger a retry.
+      callback({ retry: true, status: 0 });
+    });
+}
+
+/**
+ * Determines if a request should be retried based on HTTP status code
+ * @param {number} status - HTTP status code
+ * @returns {boolean} - True if request should be retried
+ */
+function shouldRetry(status) {
+  switch (status) {
+    case 408: // Request Timeout
+    case 429: // Too Many Requests
+    case 500: // Internal Server Error
+      return true;
+    case 401: // Unauthorized - don't retry
+    case 403: // Forbidden - don't retry
+    case 404: // Not Found - don't retry
+      return false;
+  }
+  // Retry for 5xx server errors and specific ranges
+  return (status >= 502 && status <= 504) || (status >= 512 && status <= 530);
+}
+
+/**
+ * Calculates the size of a payload object in megabytes
+ * @param {Object} obj - The object to calculate size for
+ * @returns {number} - Size in megabytes, or 0 if calculation fails
+ */
+export function getPayloadSize(obj) {
+  if (!obj || typeof obj !== "object") {
+    return 0;
+  }
+
+  try {
+    const json = JSON.stringify(obj);
+    return new TextEncoder().encode(json).length / (1024 * 1024);
+  } catch (error) {
+    console.error("getPayloadSize: Error calculating payload size", error);
+    return 0;
+  }
+}