@newrelic/browser-agent 1.276.0 → 1.277.0

package/CHANGELOG.md

@@ -3,6 +3,18 @@
 All notable changes to this project will be documented in this file.
 See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
 
+## [1.277.0](https://github.com/newrelic/newrelic-browser-agent/compare/v1.276.0...v1.277.0) (2024-12-18)
+
+
+### Features
+
+* Add custom events API ([#1263](https://github.com/newrelic/newrelic-browser-agent/issues/1263)) ([9395415](https://github.com/newrelic/newrelic-browser-agent/commit/9395415d942b55e88e89438aa203c6a1642d9e6b))
+
+
+### Bug Fixes
+
+* Soft navigation bug fixes and new soft navigation tests ([#1268](https://github.com/newrelic/newrelic-browser-agent/issues/1268)) ([7624928](https://github.com/newrelic/newrelic-browser-agent/commit/762492896a7b96564269aab1aadeb6e44a4da242))
+
 ## [1.276.0](https://github.com/newrelic/newrelic-browser-agent/compare/v1.275.0...v1.276.0) (2024-12-16)
 
 

package/dist/cjs/common/constants/env.cdn.js

@@ -12,7 +12,7 @@ exports.VERSION = exports.RRWEB_VERSION = exports.DIST_METHOD = exports.BUILD_EN
 /**
  * Exposes the version of the agent
  */
-const VERSION = exports.VERSION = "1.276.0";
+const VERSION = exports.VERSION = "1.277.0";
 
 /**
  * Exposes the build type of the agent

package/dist/cjs/common/constants/env.npm.js

@@ -12,7 +12,7 @@ exports.VERSION = exports.RRWEB_VERSION = exports.DIST_METHOD = exports.BUILD_EN
 /**
  * Exposes the version of the agent
  */
-const VERSION = exports.VERSION = "1.276.0";
+const VERSION = exports.VERSION = "1.277.0";
 
 /**
  * Exposes the build type of the agent

package/dist/cjs/features/generic_events/aggregate/index.js

@@ -38,12 +38,20 @@ class Aggregate extends _aggregateBase.AggregateBase {
         return;
       }
       this.trackSupportabilityMetrics();
+      (0, _registerHandler.registerHandler)('api-recordCustomEvent', (timestamp, eventType, attributes) => {
+        if (_constants.RESERVED_EVENT_TYPES.includes(eventType)) return (0, _console.warn)(46);
+        this.addEvent({
+          eventType,
+          timestamp: this.toEpoch(timestamp),
+          ...attributes
+        });
+      }, this.featureName, this.ee);
       if (agentRef.init.page_action.enabled) {
         (0, _registerHandler.registerHandler)('api-addPageAction', (timestamp, name, attributes) => {
           this.addEvent({
             ...attributes,
             eventType: 'PageAction',
-            timestamp: Math.floor(this.agentRef.runtime.timeKeeper.correctRelativeTimestamp(timestamp)),
+            timestamp: this.toEpoch(timestamp),
             timeSinceLoad: timestamp / 1000,
             actionName: name,
             referrerUrl: this.referrerUrl,
@@ -69,7 +77,7 @@ class Aggregate extends _aggregateBase.AggregateBase {
               } = aggregatedUserAction.event;
               this.addEvent({
                 eventType: 'UserAction',
-                timestamp: Math.floor(this.agentRef.runtime.timeKeeper.correctRelativeTimestamp(timeStamp)),
+                timestamp: this.toEpoch(timeStamp),
                 action: type,
                 actionCount: aggregatedUserAction.count,
                 actionDuration: aggregatedUserAction.relativeMs[aggregatedUserAction.relativeMs.length - 1],
@@ -130,7 +138,7 @@ class Aggregate extends _aggregateBase.AggregateBase {
                     (0, _handle.handle)(_constants2.SUPPORTABILITY_METRIC_CHANNEL, ['Generic/Performance/' + type + '/Seen']);
                     this.addEvent({
                       eventType: 'BrowserPerformance',
-                      timestamp: Math.floor(agentRef.runtime.timeKeeper.correctRelativeTimestamp(entry.startTime)),
+                      timestamp: this.toEpoch(entry.startTime),
                       entryName: (0, _cleanUrl.cleanURL)(entry.name),
                       entryDuration: entry.duration,
                       entryType: type,
@@ -262,6 +270,9 @@ class Aggregate extends _aggregateBase.AggregateBase {
       at: this.agentRef.info.atts
     };
   }
+  toEpoch(timestamp) {
+    return Math.floor(this.agentRef.runtime.timeKeeper.correctRelativeTimestamp(timestamp));
+  }
   trackSupportabilityMetrics() {
     /** track usage SMs to improve these experimental features */
     const configPerfTag = 'Config/Performance/';

package/dist/cjs/features/generic_events/constants.js

@@ -3,7 +3,7 @@
 Object.defineProperty(exports, "__esModule", {
   value: true
 });
-exports.RAGE_CLICK_THRESHOLD_MS = exports.RAGE_CLICK_THRESHOLD_EVENTS = exports.OBSERVED_WINDOW_EVENTS = exports.OBSERVED_EVENTS = exports.MAX_PAYLOAD_SIZE = exports.IDEAL_PAYLOAD_SIZE = exports.FEATURE_NAME = exports.FEATURE_FLAGS = void 0;
+exports.RESERVED_EVENT_TYPES = exports.RAGE_CLICK_THRESHOLD_MS = exports.RAGE_CLICK_THRESHOLD_EVENTS = exports.OBSERVED_WINDOW_EVENTS = exports.OBSERVED_EVENTS = exports.MAX_PAYLOAD_SIZE = exports.IDEAL_PAYLOAD_SIZE = exports.FEATURE_NAME = exports.FEATURE_FLAGS = void 0;
 var _features = require("../../loaders/features/features");
 const FEATURE_NAME = exports.FEATURE_NAME = _features.FEATURE_NAMES.genericEvents;
 const IDEAL_PAYLOAD_SIZE = exports.IDEAL_PAYLOAD_SIZE = 64000;
@@ -12,6 +12,7 @@ const OBSERVED_EVENTS = exports.OBSERVED_EVENTS = ['auxclick', 'click', 'copy',
 const OBSERVED_WINDOW_EVENTS = exports.OBSERVED_WINDOW_EVENTS = ['focus', 'blur'];
 const RAGE_CLICK_THRESHOLD_EVENTS = exports.RAGE_CLICK_THRESHOLD_EVENTS = 4;
 const RAGE_CLICK_THRESHOLD_MS = exports.RAGE_CLICK_THRESHOLD_MS = 1000;
+const RESERVED_EVENT_TYPES = exports.RESERVED_EVENT_TYPES = ['PageAction', 'UserAction', 'BrowserPerformance'];
 const FEATURE_FLAGS = exports.FEATURE_FLAGS = {
   MARKS: 'experimental.marks',
   MEASURES: 'experimental.measures',

package/dist/cjs/features/soft_navigations/aggregate/index.js

@@ -26,20 +26,23 @@ class Aggregate extends _aggregateBase.AggregateBase {
     this.interactionsToHarvest = this.events;
     this.domObserver = domObserver;
     this.initialPageLoadInteraction = new _initialPageLoadInteraction.InitialPageLoadInteraction(agentRef.agentIdentifier);
+    this.initialPageLoadInteraction.onDone.push(() => {
+      // this ensures the .end() method also works with iPL
+      this.initialPageLoadInteraction.forceSave = true; // unless forcibly ignored, iPL always finish by default
+      this.interactionsToHarvest.add(this.initialPageLoadInteraction);
+      this.initialPageLoadInteraction = null;
+    });
     _timeToFirstByte.timeToFirstByte.subscribe(({
       attrs
     }) => {
       const loadEventTime = attrs.navigationEntry.loadEventEnd;
-      this.initialPageLoadInteraction.forceSave = true;
       this.initialPageLoadInteraction.done(loadEventTime);
-      this.interactionsToHarvest.add(this.initialPageLoadInteraction);
-      this.initialPageLoadInteraction = null;
       // Report metric on the initial page load time
       (0, _handle.handle)(_constants.SUPPORTABILITY_METRIC_CHANNEL, ['SoftNav/Interaction/InitialPageLoad/Duration/Ms', Math.round(loadEventTime)], undefined, _features.FEATURE_NAMES.metrics, this.ee);
     });
     this.latestRouteSetByApi = null;
     this.interactionInProgress = null; // aside from the "page load" interaction, there can only ever be 1 ongoing at a time
-
+    this.latestHistoryUrl = null;
     this.blocked = false;
     this.waitForFlags(['spa']).then(([spaOn]) => {
       if (spaOn) {
@@ -59,7 +62,11 @@ class Aggregate extends _aggregateBase.AggregateBase {
 
     // By default, a complete UI driven interaction requires event -> URL change -> DOM mod in that exact order.
     (0, _registerHandler.registerHandler)('newUIEvent', event => this.startUIInteraction(event.type, Math.floor(event.timeStamp), event.target), this.featureName, this.ee);
-    (0, _registerHandler.registerHandler)('newURL', (timestamp, url) => this.interactionInProgress?.updateHistory(timestamp, url), this.featureName, this.ee);
+    (0, _registerHandler.registerHandler)('newURL', (timestamp, url) => {
+      // In the case of 'popstate' trigger, by the time the event fires, the URL has already changed, so we need to store what-will-be the *previous* URL for oldURL of next popstate ixn.
+      this.latestHistoryUrl = url;
+      this.interactionInProgress?.updateHistory(timestamp, url);
+    }, this.featureName, this.ee);
     (0, _registerHandler.registerHandler)('newDom', timestamp => {
       this.interactionInProgress?.updateDom(timestamp);
       if (this.interactionInProgress?.seenHistoryAndDomChange()) this.interactionInProgress.done();
@@ -71,20 +78,23 @@ class Aggregate extends _aggregateBase.AggregateBase {
   serializer(eventBuffer) {
     // The payload depacker takes the first ixn of a payload (if there are multiple ixns) and positively offset the subsequent ixns timestamps by that amount.
     // In order to accurately portray the real start & end times of the 2nd & onward ixns, we hence need to negatively offset their start timestamps with that of the 1st ixn.
-    let firstIxnStartTime = 0; // the very 1st ixn does not require any offsetting
+    let firstIxnStartTime;
     const serializedIxnList = [];
     for (const interaction of eventBuffer) {
       serializedIxnList.push(interaction.serialize(firstIxnStartTime));
-      if (!firstIxnStartTime) firstIxnStartTime = Math.floor(interaction.start);
+      if (firstIxnStartTime === undefined) firstIxnStartTime = Math.floor(interaction.start); // careful not to match or overwrite on 0 value!
     }
     return "bel.7;".concat(serializedIxnList.join(';'));
   }
   startUIInteraction(eventName, startedAt, sourceElem) {
     // this is throttled by instrumentation so that it isn't excessively called
     if (this.interactionInProgress?.createdByApi) return; // api-started interactions cannot be disrupted aka cancelled by UI events (and the vice versa applies as well)
-    if (this.interactionInProgress?.done() === false) return;
-    this.interactionInProgress = new _interaction.Interaction(this.agentIdentifier, eventName, startedAt, this.latestRouteSetByApi);
-    if (eventName === 'click') {
+    if (this.interactionInProgress?.done() === false) return; // current in-progress is blocked from closing, e.g. by 'waitForEnd' api option
+
+    const oldURL = eventName === _constants2.INTERACTION_TRIGGERS[3] ? this.latestHistoryUrl : undefined; // see related comment in 'newURL' handler above, 'popstate'
+    this.interactionInProgress = new _interaction.Interaction(this.agentIdentifier, eventName, startedAt, this.latestRouteSetByApi, oldURL);
+    if (eventName === _constants2.INTERACTION_TRIGGERS[0]) {
+      // 'click'
       const sourceElemText = getActionText(sourceElem);
       if (sourceElemText) this.interactionInProgress.customAttributes.actionText = sourceElemText;
     }
@@ -130,7 +140,7 @@ class Aggregate extends _aggregateBase.AggregateBase {
       // reverse search for the latest completed interaction for efficiency
       const finishedInteraction = interactionsBuffer[idx];
       if (finishedInteraction.isActiveDuring(timestamp)) {
-        if (finishedInteraction.trigger !== 'initialPageLoad') return finishedInteraction;
+        if (finishedInteraction.trigger !== _constants2.IPL_TRIGGER_NAME) return finishedInteraction;
         // It's possible that a complete interaction occurs before page is fully loaded, so we need to consider if a route-change ixn may have overlapped this iPL
         else saveIxn = finishedInteraction;
       }
@@ -194,9 +204,16 @@ class Aggregate extends _aggregateBase.AggregateBase {
       // In here, 'this' refers to the EventContext specific to per InteractionHandle instance spawned by each .interaction() api call.
       // Each api call aka IH instance would therefore retain a reference to either the in-progress interaction *at the time of the call* OR a new api-started interaction.
       this.associatedInteraction = thisClass.getInteractionFor(time);
+      if (this.associatedInteraction?.trigger === _constants2.IPL_TRIGGER_NAME) this.associatedInteraction = null; // the api get-interaction method cannot target IPL
       if (!this.associatedInteraction) {
         // This new api-driven interaction will be the target of any subsequent .interaction() call, until it is closed by EITHER .end() OR the regular seenHistoryAndDomChange process.
         this.associatedInteraction = thisClass.interactionInProgress = new _interaction.Interaction(thisClass.agentIdentifier, _constants2.API_TRIGGER_NAME, time, thisClass.latestRouteSetByApi);
+        thisClass.domObserver.observe(document.body, {
+          attributes: true,
+          childList: true,
+          subtree: true,
+          characterData: true
+        }); // start observing for DOM changes like a regular UI-driven interaction
         thisClass.setClosureHandlers();
       }
       if (waitForEnd === true) this.associatedInteraction.keepOpenUntilEndApi = true;

package/dist/cjs/features/soft_navigations/aggregate/initial-page-load-interaction.js

@@ -10,9 +10,10 @@ var _belSerializer = require("../../../common/serialize/bel-serializer");
 var _firstPaint = require("../../../common/vitals/first-paint");
 var _firstContentfulPaint = require("../../../common/vitals/first-contentful-paint");
 var _info = require("../../../common/config/info");
+var _constants = require("../constants");
 class InitialPageLoadInteraction extends _interaction.Interaction {
   constructor(agentIdentifier) {
-    super(agentIdentifier, 'initialPageLoad', 0, null);
+    super(agentIdentifier, _constants.IPL_TRIGGER_NAME, 0, null);
     const agentInfo = (0, _info.getInfo)(agentIdentifier);
     this.queueTime = agentInfo.queueTime;
     this.appTime = agentInfo.applicationTime;

package/dist/cjs/features/soft_navigations/aggregate/interaction.js

@@ -18,8 +18,6 @@ var _belNode = require("./bel-node");
 class Interaction extends _belNode.BelNode {
   id = (0, _uniqueId.generateUuid)(); // unique id that is serialized and used to link interactions with errors
   initialPageURL = _runtime.initialLocation;
-  oldURL = '' + _runtime.globalScope?.location;
-  newURL = '' + _runtime.globalScope?.location;
   customName;
   customAttributes = {};
   customDataByApi = {};
@@ -34,7 +32,7 @@ class Interaction extends _belNode.BelNode {
   keepOpenUntilEndApi = false;
   onDone = [];
   cancellationTimer;
-  constructor(agentIdentifier, uiEvent, uiEventTimestamp, currentRouteKnown) {
+  constructor(agentIdentifier, uiEvent, uiEventTimestamp, currentRouteKnown, currentUrl) {
     super(agentIdentifier);
     this.belType = _constants.NODE_TYPE.INTERACTION;
     this.trigger = uiEvent;
@@ -43,6 +41,7 @@ class Interaction extends _belNode.BelNode {
     this.eventSubscription = new Map([['finished', []], ['cancelled', []]]);
     this.forceSave = this.forceIgnore = false;
     if (this.trigger === _constants.API_TRIGGER_NAME) this.createdByApi = true;
+    this.newURL = this.oldURL = currentUrl || _runtime.globalScope?.location.href;
   }
   updateDom(timestamp) {
     this.domTimestamp = timestamp || (0, _now.now)(); // default timestamp should be precise for accurate isActiveDuring calculations
@@ -62,6 +61,8 @@ class Interaction extends _belNode.BelNode {
   done(customEndTime) {
     // User could've mark this interaction--regardless UI or api started--as "don't close until .end() is called on it". Only .end provides a timestamp; the default flows do not.
     if (this.keepOpenUntilEndApi && customEndTime === undefined) return false;
+    // If interaction is already closed, this is a no-op. However, returning true lets startUIInteraction know that it CAN start a new interaction, as this one is done.
+    if (this.status !== _constants.INTERACTION_STATUS.IP) return true;
     this.onDone.forEach(apiProvidedCb => apiProvidedCb(this.customDataByApi)); // this interaction's .save or .ignore can still be set by these user provided callbacks for example
 
     if (this.forceIgnore) this.#cancel(); // .ignore() always has precedence over save actions
@@ -71,7 +72,6 @@ class Interaction extends _belNode.BelNode {
     return true;
   }
   #finish(customEndTime = 0) {
-    if (this.status !== _constants.INTERACTION_STATUS.IP) return; // disallow this call if the ixn is already done aka not in-progress
     clearTimeout(this.cancellationTimer);
     this.end = Math.max(this.domTimestamp, this.historyTimestamp, customEndTime);
     this.customAttributes = {
@@ -85,7 +85,6 @@ class Interaction extends _belNode.BelNode {
     callbacks.forEach(fn => fn());
   }
   #cancel() {
-    if (this.status !== _constants.INTERACTION_STATUS.IP) return; // disallow this call if the ixn is already done aka not in-progress
     clearTimeout(this.cancellationTimer);
     this.status = _constants.INTERACTION_STATUS.CAN;
 
@@ -102,7 +101,7 @@ class Interaction extends _belNode.BelNode {
    */
   isActiveDuring(timestamp) {
     if (this.status === _constants.INTERACTION_STATUS.IP) return this.start <= timestamp;
-    return this.status === _constants.INTERACTION_STATUS.FIN && this.start <= timestamp && this.end >= timestamp;
+    return this.status === _constants.INTERACTION_STATUS.FIN && this.start <= timestamp && this.end > timestamp;
   }
 
   // Following are virtual properties overridden by a subclass:
@@ -110,16 +109,17 @@ class Interaction extends _belNode.BelNode {
   get firstContentfulPaint() {}
   get navTiming() {}
   serialize(firstStartTimeOfPayload) {
+    const isFirstIxnOfPayload = firstStartTimeOfPayload === undefined;
     const addString = (0, _belSerializer.getAddStringContext)(this.agentIdentifier);
     const nodeList = [];
     let ixnType;
-    if (this.trigger === 'initialPageLoad') ixnType = _constants.INTERACTION_TYPE.INITIAL_PAGE_LOAD;else if (this.newURL !== this.oldURL) ixnType = _constants.INTERACTION_TYPE.ROUTE_CHANGE;else ixnType = _constants.INTERACTION_TYPE.UNSPECIFIED;
+    if (this.trigger === _constants.IPL_TRIGGER_NAME) ixnType = _constants.INTERACTION_TYPE.INITIAL_PAGE_LOAD;else if (this.newURL !== this.oldURL) ixnType = _constants.INTERACTION_TYPE.ROUTE_CHANGE;else ixnType = _constants.INTERACTION_TYPE.UNSPECIFIED;
 
     // IMPORTANT: The order in which addString is called matters and correlates to the order in which string shows up in the harvest payload. Do not re-order the following code.
     const fields = [(0, _belSerializer.numeric)(this.belType), 0,
     // this will be overwritten below with number of attached nodes
-    (0, _belSerializer.numeric)(this.start - firstStartTimeOfPayload),
-    // relative to first node
+    (0, _belSerializer.numeric)(this.start - (isFirstIxnOfPayload ? 0 : firstStartTimeOfPayload)),
+    // the very 1st ixn does not require offset so it should fallback to a 0 while rest is offset by the very 1st ixn's start
     (0, _belSerializer.numeric)(this.end - this.start),
     // end -- relative to start
     (0, _belSerializer.numeric)(this.callbackEnd),
@@ -130,9 +130,9 @@ class Interaction extends _belNode.BelNode {
     const allAttachedNodes = (0, _belSerializer.addCustomAttributes)(this.customAttributes || {}, addString); // start with all custom attributes
     if ((0, _info.getInfo)(this.agentIdentifier).atts) allAttachedNodes.push('a,' + addString((0, _info.getInfo)(this.agentIdentifier).atts)); // add apm provided attributes
     /* Querypack encoder+decoder quirkiness:
-       - If first ixn node of payload is being processed, we use this node's start to offset. (firstStartTime should be 0--or undefined.)
-       - Else for subsequent ixn nodes, we use the first ixn node's start to offset. */
-    this.children.forEach(node => allAttachedNodes.push(node.serialize(firstStartTimeOfPayload || this.start))); // recursively add the serialized string of every child of this (ixn) bel node
+       - If first ixn node of payload is being processed, its children's start time must be offset by this node's start. (firstStartTime should be undefined.)
+       - Else for subsequent ixns in the same payload, we go back to using that first ixn node's start to offset their children's start. */
+    this.children.forEach(node => allAttachedNodes.push(node.serialize(isFirstIxnOfPayload ? this.start : firstStartTimeOfPayload))); // recursively add the serialized string of every child of this (ixn) bel node
 
     fields[1] = (0, _belSerializer.numeric)(allAttachedNodes.length);
     nodeList.push(fields);

package/dist/cjs/features/soft_navigations/constants.js

@@ -3,15 +3,18 @@
 Object.defineProperty(exports, "__esModule", {
   value: true
 });
-exports.NODE_TYPE = exports.INTERACTION_TYPE = exports.INTERACTION_TRIGGERS = exports.INTERACTION_STATUS = exports.FEATURE_NAME = exports.API_TRIGGER_NAME = void 0;
+exports.NODE_TYPE = exports.IPL_TRIGGER_NAME = exports.INTERACTION_TYPE = exports.INTERACTION_TRIGGERS = exports.INTERACTION_STATUS = exports.FEATURE_NAME = exports.API_TRIGGER_NAME = void 0;
 var _features = require("../../loaders/features/features");
 const INTERACTION_TRIGGERS = exports.INTERACTION_TRIGGERS = ['click',
 // e.g. user clicks link or the page back/forward buttons
 'keydown',
 // e.g. user presses left and right arrow key to switch between displayed photo gallery
-'submit' // e.g. user clicks submit butotn or presses enter while editing a form field
+'submit',
+// e.g. user clicks submit butotn or presses enter while editing a form field
+'popstate' // history api is used to navigate back and forward
 ];
 const API_TRIGGER_NAME = exports.API_TRIGGER_NAME = 'api';
+const IPL_TRIGGER_NAME = exports.IPL_TRIGGER_NAME = 'initialPageLoad';
 const FEATURE_NAME = exports.FEATURE_NAME = _features.FEATURE_NAMES.softNav;
 const INTERACTION_TYPE = exports.INTERACTION_TYPE = {
   INITIAL_PAGE_LOAD: '',

package/dist/cjs/loaders/api/api-methods.js

@@ -5,5 +5,5 @@ Object.defineProperty(exports, "__esModule", {
 });
 exports.asyncApiMethods = exports.apiMethods = void 0;
 var _constants = require("../../features/session_replay/constants");
-const apiMethods = exports.apiMethods = ['setErrorHandler', 'finished', 'addToTrace', 'addRelease', 'addPageAction', 'setCurrentRouteName', 'setPageViewName', 'setCustomAttribute', 'interaction', 'noticeError', 'setUserId', 'setApplicationVersion', 'start', _constants.SR_EVENT_EMITTER_TYPES.RECORD, _constants.SR_EVENT_EMITTER_TYPES.PAUSE, 'log', 'wrapLogger'];
+const apiMethods = exports.apiMethods = ['setErrorHandler', 'finished', 'addToTrace', 'addRelease', 'recordCustomEvent', 'addPageAction', 'setCurrentRouteName', 'setPageViewName', 'setCustomAttribute', 'interaction', 'noticeError', 'setUserId', 'setApplicationVersion', 'start', _constants.SR_EVENT_EMITTER_TYPES.RECORD, _constants.SR_EVENT_EMITTER_TYPES.PAUSE, 'log', 'wrapLogger'];
 const asyncApiMethods = exports.asyncApiMethods = ['setErrorHandler', 'finished', 'addToTrace', 'addRelease'];

package/dist/cjs/loaders/api/api.js

@@ -80,6 +80,7 @@ function setAPI(agentIdentifier, forceDrain, runSoftNavOverSpa = false) {
     apiInterface[fnName] = apiCall(prefix, fnName, true, 'api');
   });
   apiInterface.addPageAction = apiCall(prefix, 'addPageAction', true, _features.FEATURE_NAMES.genericEvents);
+  apiInterface.recordCustomEvent = apiCall(prefix, 'recordCustomEvent', true, _features.FEATURE_NAMES.genericEvents);
   apiInterface.setPageViewName = function (name, host) {
     if (typeof name !== 'string') return;
     if (name.charAt(0) !== '/') name = '/' + name;
@@ -198,7 +199,7 @@ function setAPI(agentIdentifier, forceDrain, runSoftNavOverSpa = false) {
   function apiCall(prefix, name, notSpa, bufferGroup) {
     return function () {
       (0, _handle.handle)(_constants.SUPPORTABILITY_METRIC_CHANNEL, ['API/' + name + '/called'], undefined, _features.FEATURE_NAMES.metrics, instanceEE);
-      if (bufferGroup) (0, _handle.handle)(prefix + name, [(0, _now.now)(), ...arguments], notSpa ? null : this, bufferGroup, instanceEE); // no bufferGroup means only the SM is emitted
+      if (bufferGroup) (0, _handle.handle)(prefix + name, [notSpa ? (0, _now.now)() : performance.now(), ...arguments], notSpa ? null : this, bufferGroup, instanceEE); // no bufferGroup means only the SM is emitted
       return notSpa ? undefined : this; // returns the InteractionHandle which allows these methods to be chained
     };
   }

package/dist/cjs/loaders/micro-agent-base.js

@@ -33,6 +33,16 @@ class MicroAgentBase {
     return this.#callMethod('addPageAction', name, attributes);
   }
 
+  /**
+   * Records a custom event with a specified eventType and attributes.
+   * {@link https://docs.newrelic.com/docs/browser/new-relic-browser/browser-apis/recordCustomEvent/}
+   * @param {string} eventType The eventType to store the event as.
+   * @param {object} [attributes] JSON object with one or more key/value pairs. For example: {key:"value"}.
+   */
+  recordCustomEvent(eventType, attributes) {
+    return this.#callMethod('recordCustomEvent', eventType, attributes);
+  }
+
   /**
    * Groups page views to help URL structure or to capture the URL's routing information.
    * {@link https://docs.newrelic.com/docs/browser/new-relic-browser/browser-apis/setpageviewname/}

package/dist/esm/common/constants/env.cdn.js

@@ -6,7 +6,7 @@
 /**
  * Exposes the version of the agent
  */
-export const VERSION = "1.276.0";
+export const VERSION = "1.277.0";
 
 /**
  * Exposes the build type of the agent

package/dist/esm/common/constants/env.npm.js

@@ -6,7 +6,7 @@
 /**
  * Exposes the version of the agent
  */
-export const VERSION = "1.276.0";
+export const VERSION = "1.277.0";
 
 /**
  * Exposes the build type of the agent

package/dist/esm/features/generic_events/aggregate/index.js

@@ -5,7 +5,7 @@
 import { stringify } from '../../../common/util/stringify';
 import { HarvestScheduler } from '../../../common/harvest/harvest-scheduler';
 import { cleanURL } from '../../../common/url/clean-url';
-import { FEATURE_NAME } from '../constants';
+import { FEATURE_NAME, RESERVED_EVENT_TYPES } from '../constants';
 import { globalScope, initialLocation, isBrowserScope } from '../../../common/constants/runtime';
 import { AggregateBase } from '../../utils/aggregate-base';
 import { warn } from '../../../common/util/console';
@@ -31,12 +31,20 @@ export class Aggregate extends AggregateBase {
         return;
       }
       this.trackSupportabilityMetrics();
+      registerHandler('api-recordCustomEvent', (timestamp, eventType, attributes) => {
+        if (RESERVED_EVENT_TYPES.includes(eventType)) return warn(46);
+        this.addEvent({
+          eventType,
+          timestamp: this.toEpoch(timestamp),
+          ...attributes
+        });
+      }, this.featureName, this.ee);
       if (agentRef.init.page_action.enabled) {
         registerHandler('api-addPageAction', (timestamp, name, attributes) => {
           this.addEvent({
             ...attributes,
             eventType: 'PageAction',
-            timestamp: Math.floor(this.agentRef.runtime.timeKeeper.correctRelativeTimestamp(timestamp)),
+            timestamp: this.toEpoch(timestamp),
             timeSinceLoad: timestamp / 1000,
             actionName: name,
             referrerUrl: this.referrerUrl,
@@ -62,7 +70,7 @@ export class Aggregate extends AggregateBase {
               } = aggregatedUserAction.event;
               this.addEvent({
                 eventType: 'UserAction',
-                timestamp: Math.floor(this.agentRef.runtime.timeKeeper.correctRelativeTimestamp(timeStamp)),
+                timestamp: this.toEpoch(timeStamp),
                 action: type,
                 actionCount: aggregatedUserAction.count,
                 actionDuration: aggregatedUserAction.relativeMs[aggregatedUserAction.relativeMs.length - 1],
@@ -123,7 +131,7 @@ export class Aggregate extends AggregateBase {
                     handle(SUPPORTABILITY_METRIC_CHANNEL, ['Generic/Performance/' + type + '/Seen']);
                     this.addEvent({
                       eventType: 'BrowserPerformance',
-                      timestamp: Math.floor(agentRef.runtime.timeKeeper.correctRelativeTimestamp(entry.startTime)),
+                      timestamp: this.toEpoch(entry.startTime),
                       entryName: cleanURL(entry.name),
                       entryDuration: entry.duration,
                       entryType: type,
@@ -255,6 +263,9 @@ export class Aggregate extends AggregateBase {
       at: this.agentRef.info.atts
     };
   }
+  toEpoch(timestamp) {
+    return Math.floor(this.agentRef.runtime.timeKeeper.correctRelativeTimestamp(timestamp));
+  }
   trackSupportabilityMetrics() {
     /** track usage SMs to improve these experimental features */
     const configPerfTag = 'Config/Performance/';

package/dist/esm/features/generic_events/constants.js

@@ -6,6 +6,7 @@ export const OBSERVED_EVENTS = ['auxclick', 'click', 'copy', 'keydown', 'paste',
 export const OBSERVED_WINDOW_EVENTS = ['focus', 'blur'];
 export const RAGE_CLICK_THRESHOLD_EVENTS = 4;
 export const RAGE_CLICK_THRESHOLD_MS = 1000;
+export const RESERVED_EVENT_TYPES = ['PageAction', 'UserAction', 'BrowserPerformance'];
 export const FEATURE_FLAGS = {
   MARKS: 'experimental.marks',
   MEASURES: 'experimental.measures',

package/dist/esm/features/soft_navigations/aggregate/index.js

@@ -6,7 +6,7 @@ import { timeToFirstByte } from '../../../common/vitals/time-to-first-byte';
 import { FEATURE_NAMES, FEATURE_TO_ENDPOINT } from '../../../loaders/features/features';
 import { SUPPORTABILITY_METRIC_CHANNEL } from '../../metrics/constants';
 import { AggregateBase } from '../../utils/aggregate-base';
-import { API_TRIGGER_NAME, FEATURE_NAME, INTERACTION_STATUS } from '../constants';
+import { API_TRIGGER_NAME, FEATURE_NAME, INTERACTION_STATUS, INTERACTION_TRIGGERS, IPL_TRIGGER_NAME } from '../constants';
 import { AjaxNode } from './ajax-node';
 import { InitialPageLoadInteraction } from './initial-page-load-interaction';
 import { Interaction } from './interaction';
@@ -20,20 +20,23 @@ export class Aggregate extends AggregateBase {
     this.interactionsToHarvest = this.events;
     this.domObserver = domObserver;
     this.initialPageLoadInteraction = new InitialPageLoadInteraction(agentRef.agentIdentifier);
+    this.initialPageLoadInteraction.onDone.push(() => {
+      // this ensures the .end() method also works with iPL
+      this.initialPageLoadInteraction.forceSave = true; // unless forcibly ignored, iPL always finish by default
+      this.interactionsToHarvest.add(this.initialPageLoadInteraction);
+      this.initialPageLoadInteraction = null;
+    });
     timeToFirstByte.subscribe(({
       attrs
     }) => {
       const loadEventTime = attrs.navigationEntry.loadEventEnd;
-      this.initialPageLoadInteraction.forceSave = true;
       this.initialPageLoadInteraction.done(loadEventTime);
-      this.interactionsToHarvest.add(this.initialPageLoadInteraction);
-      this.initialPageLoadInteraction = null;
       // Report metric on the initial page load time
       handle(SUPPORTABILITY_METRIC_CHANNEL, ['SoftNav/Interaction/InitialPageLoad/Duration/Ms', Math.round(loadEventTime)], undefined, FEATURE_NAMES.metrics, this.ee);
     });
     this.latestRouteSetByApi = null;
     this.interactionInProgress = null; // aside from the "page load" interaction, there can only ever be 1 ongoing at a time
-
+    this.latestHistoryUrl = null;
     this.blocked = false;
     this.waitForFlags(['spa']).then(([spaOn]) => {
       if (spaOn) {
@@ -53,7 +56,11 @@ export class Aggregate extends AggregateBase {
 
     // By default, a complete UI driven interaction requires event -> URL change -> DOM mod in that exact order.
     registerHandler('newUIEvent', event => this.startUIInteraction(event.type, Math.floor(event.timeStamp), event.target), this.featureName, this.ee);
-    registerHandler('newURL', (timestamp, url) => this.interactionInProgress?.updateHistory(timestamp, url), this.featureName, this.ee);
+    registerHandler('newURL', (timestamp, url) => {
+      // In the case of 'popstate' trigger, by the time the event fires, the URL has already changed, so we need to store what-will-be the *previous* URL for oldURL of next popstate ixn.
+      this.latestHistoryUrl = url;
+      this.interactionInProgress?.updateHistory(timestamp, url);
+    }, this.featureName, this.ee);
     registerHandler('newDom', timestamp => {
       this.interactionInProgress?.updateDom(timestamp);
       if (this.interactionInProgress?.seenHistoryAndDomChange()) this.interactionInProgress.done();
@@ -65,20 +72,23 @@ export class Aggregate extends AggregateBase {
   serializer(eventBuffer) {
     // The payload depacker takes the first ixn of a payload (if there are multiple ixns) and positively offset the subsequent ixns timestamps by that amount.
     // In order to accurately portray the real start & end times of the 2nd & onward ixns, we hence need to negatively offset their start timestamps with that of the 1st ixn.
-    let firstIxnStartTime = 0; // the very 1st ixn does not require any offsetting
+    let firstIxnStartTime;
     const serializedIxnList = [];
     for (const interaction of eventBuffer) {
       serializedIxnList.push(interaction.serialize(firstIxnStartTime));
-      if (!firstIxnStartTime) firstIxnStartTime = Math.floor(interaction.start);
+      if (firstIxnStartTime === undefined) firstIxnStartTime = Math.floor(interaction.start); // careful not to match or overwrite on 0 value!
     }
     return "bel.7;".concat(serializedIxnList.join(';'));
   }
   startUIInteraction(eventName, startedAt, sourceElem) {
     // this is throttled by instrumentation so that it isn't excessively called
     if (this.interactionInProgress?.createdByApi) return; // api-started interactions cannot be disrupted aka cancelled by UI events (and the vice versa applies as well)
-    if (this.interactionInProgress?.done() === false) return;
-    this.interactionInProgress = new Interaction(this.agentIdentifier, eventName, startedAt, this.latestRouteSetByApi);
-    if (eventName === 'click') {
+    if (this.interactionInProgress?.done() === false) return; // current in-progress is blocked from closing, e.g. by 'waitForEnd' api option
+
+    const oldURL = eventName === INTERACTION_TRIGGERS[3] ? this.latestHistoryUrl : undefined; // see related comment in 'newURL' handler above, 'popstate'
+    this.interactionInProgress = new Interaction(this.agentIdentifier, eventName, startedAt, this.latestRouteSetByApi, oldURL);
+    if (eventName === INTERACTION_TRIGGERS[0]) {
+      // 'click'
       const sourceElemText = getActionText(sourceElem);
       if (sourceElemText) this.interactionInProgress.customAttributes.actionText = sourceElemText;
     }
@@ -124,7 +134,7 @@ export class Aggregate extends AggregateBase {
       // reverse search for the latest completed interaction for efficiency
       const finishedInteraction = interactionsBuffer[idx];
       if (finishedInteraction.isActiveDuring(timestamp)) {
-        if (finishedInteraction.trigger !== 'initialPageLoad') return finishedInteraction;
+        if (finishedInteraction.trigger !== IPL_TRIGGER_NAME) return finishedInteraction;
         // It's possible that a complete interaction occurs before page is fully loaded, so we need to consider if a route-change ixn may have overlapped this iPL
         else saveIxn = finishedInteraction;
       }
@@ -188,9 +198,16 @@ export class Aggregate extends AggregateBase {
       // In here, 'this' refers to the EventContext specific to per InteractionHandle instance spawned by each .interaction() api call.
       // Each api call aka IH instance would therefore retain a reference to either the in-progress interaction *at the time of the call* OR a new api-started interaction.
       this.associatedInteraction = thisClass.getInteractionFor(time);
+      if (this.associatedInteraction?.trigger === IPL_TRIGGER_NAME) this.associatedInteraction = null; // the api get-interaction method cannot target IPL
       if (!this.associatedInteraction) {
         // This new api-driven interaction will be the target of any subsequent .interaction() call, until it is closed by EITHER .end() OR the regular seenHistoryAndDomChange process.
         this.associatedInteraction = thisClass.interactionInProgress = new Interaction(thisClass.agentIdentifier, API_TRIGGER_NAME, time, thisClass.latestRouteSetByApi);
+        thisClass.domObserver.observe(document.body, {
+          attributes: true,
+          childList: true,
+          subtree: true,
+          characterData: true
+        }); // start observing for DOM changes like a regular UI-driven interaction
         thisClass.setClosureHandlers();
       }
       if (waitForEnd === true) this.associatedInteraction.keepOpenUntilEndApi = true;

package/dist/esm/features/soft_navigations/aggregate/initial-page-load-interaction.js

@@ -4,9 +4,10 @@ import { numeric } from '../../../common/serialize/bel-serializer';
 import { firstPaint } from '../../../common/vitals/first-paint';
 import { firstContentfulPaint } from '../../../common/vitals/first-contentful-paint';
 import { getInfo } from '../../../common/config/info';
+import { IPL_TRIGGER_NAME } from '../constants';
 export class InitialPageLoadInteraction extends Interaction {
   constructor(agentIdentifier) {
-    super(agentIdentifier, 'initialPageLoad', 0, null);
+    super(agentIdentifier, IPL_TRIGGER_NAME, 0, null);
     const agentInfo = getInfo(agentIdentifier);
     this.queueTime = agentInfo.queueTime;
     this.appTime = agentInfo.applicationTime;