@newrelic/browser-agent 1.252.1 → 1.253.0

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

@@ -0,0 +1,263 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.Aggregate = void 0;
+var _config = require("../../../common/config/config");
+var _handle = require("../../../common/event-emitter/handle");
+var _registerHandler = require("../../../common/event-emitter/register-handler");
+var _harvestScheduler = require("../../../common/harvest/harvest-scheduler");
+var _invoke = require("../../../common/util/invoke");
+var _timeToFirstByte = require("../../../common/vitals/time-to-first-byte");
+var _features = require("../../../loaders/features/features");
+var _constants = require("../../metrics/constants");
+var _aggregateBase = require("../../utils/aggregate-base");
+var _constants2 = require("../constants");
+var _ajaxNode = require("./ajax-node");
+var _initialPageLoadInteraction = require("./initial-page-load-interaction");
+var _interaction = require("./interaction");
+class Aggregate extends _aggregateBase.AggregateBase {
+  static featureName = _constants2.FEATURE_NAME;
+  constructor(agentIdentifier, aggregator, _ref) {
+    let {
+      domObserver
+    } = _ref;
+    super(agentIdentifier, aggregator, _constants2.FEATURE_NAME);
+    const harvestTimeSeconds = (0, _config.getConfigurationValue)(agentIdentifier, 'soft_navigations.harvestTimeSeconds') || 10;
+    this.interactionsToHarvest = [];
+    this.interactionsAwaitingRetry = [];
+    this.domObserver = domObserver;
+    this.scheduler = new _harvestScheduler.HarvestScheduler('events', {
+      onFinished: this.onHarvestFinished.bind(this),
+      retryDelay: harvestTimeSeconds,
+      onUnload: () => this.interactionInProgress?.done() // return any held ajax or jserr events so they can be sent with EoL harvest
+    }, {
+      agentIdentifier,
+      ee: this.ee
+    });
+    this.scheduler.harvest.on('events', this.onHarvestStarted.bind(this));
+    this.initialPageLoadInteraction = new _initialPageLoadInteraction.InitialPageLoadInteraction(agentIdentifier);
+    _timeToFirstByte.timeToFirstByte.subscribe(_ref2 => {
+      let {
+        entries
+      } = _ref2;
+      const loadEventTime = entries[0].loadEventEnd;
+      this.initialPageLoadInteraction.forceSave = true;
+      this.initialPageLoadInteraction.done(loadEventTime);
+      this.interactionsToHarvest.push(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.blocked = false;
+    this.waitForFlags(['spa']).then(_ref3 => {
+      let [spaOn] = _ref3;
+      if (spaOn) this.scheduler.startTimer(harvestTimeSeconds, 0);else this.blocked = true; // if rum response determines that customer lacks entitlements for spa endpoint, this feature shouldn't harvest
+    });
+
+    // 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, 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)('newDom', timestamp => {
+      this.interactionInProgress?.updateDom(timestamp);
+      if (this.interactionInProgress?.seenHistoryAndDomChange()) this.interactionInProgress.done();
+    }, this.featureName, this.ee);
+    this.#registerApiHandlers();
+    (0, _registerHandler.registerHandler)('ajax', this.#handleAjaxEvent.bind(this), this.featureName, this.ee);
+    (0, _registerHandler.registerHandler)('jserror', this.#handleJserror.bind(this), this.featureName, this.ee);
+    this.drain();
+  }
+  onHarvestStarted(options) {
+    if (this.interactionsToHarvest.length === 0 || this.blocked) return;
+
+    // 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
+    const serializedIxnList = [];
+    for (const interaction of this.interactionsToHarvest) {
+      serializedIxnList.push(interaction.serialize(firstIxnStartTime));
+      if (!firstIxnStartTime) firstIxnStartTime = Math.floor(interaction.start);
+    }
+    const payload = "bel.7;".concat(serializedIxnList.join(';'));
+    if (options.retry) this.interactionsAwaitingRetry.push(...this.interactionsToHarvest);
+    this.interactionsToHarvest = [];
+    return {
+      body: {
+        e: payload
+      }
+    };
+  }
+  onHarvestFinished(result) {
+    if (result.sent && result.retry && this.interactionsAwaitingRetry.length > 0) {
+      this.interactionsToHarvest = [...this.interactionsAwaitingRetry, ...this.interactionsToHarvest];
+      this.interactionsAwaitingRetry = [];
+    }
+  }
+  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') {
+      const sourceElemText = getActionText(sourceElem);
+      if (sourceElemText) this.interactionInProgress.customAttributes.actionText = sourceElemText;
+    }
+    this.interactionInProgress.cancellationTimer = setTimeout(() => {
+      this.interactionInProgress.done();
+      // Report metric on frequency of cancellation due to timeout for UI ixn
+      (0, _handle.handle)(_constants.SUPPORTABILITY_METRIC_CHANNEL, ['SoftNav/Interaction/TimeOut'], undefined, _features.FEATURE_NAMES.metrics, this.ee);
+    }, 30000); // UI ixn are disregarded after 30 seconds if it's not completed by then
+    this.setClosureHandlers();
+  }
+  setClosureHandlers() {
+    this.interactionInProgress.on('finished', () => {
+      const ref = this.interactionInProgress;
+      this.interactionsToHarvest.push(this.interactionInProgress);
+      this.interactionInProgress = null;
+      this.domObserver.disconnect(); // can stop observing whenever our interaction logic completes a cycle
+
+      // Report metric on the ixn duration
+      (0, _handle.handle)(_constants.SUPPORTABILITY_METRIC_CHANNEL, ["SoftNav/Interaction/".concat(ref.newURL !== ref.oldURL ? 'RouteChange' : 'Custom', "/Duration/Ms"), Math.round(ref.end - ref.start)], undefined, _features.FEATURE_NAMES.metrics, this.ee);
+    });
+    this.interactionInProgress.on('cancelled', () => {
+      this.interactionInProgress = null;
+      this.domObserver.disconnect();
+    });
+  }
+
+  /**
+   * Find the active interaction (current or past) for a given timestamp. Note that historic lookups mostly only go as far back as the last harvest for this feature.
+   * Also, the caller should check the status of the interaction returned if found via {@link Interaction.status}, if that's pertinent.
+   * TIP: Cancelled (status) interactions are NOT returned!
+   * IMPORTANT: Finished interactions are in queue for next harvest! It's highly recommended that consumer logic be synchronous for safe reference.
+   * @param {DOMHighResTimeStamp} timestamp
+   * @returns An {@link Interaction} or undefined, if no active interaction was found.
+   */
+  getInteractionFor(timestamp) {
+    /* In the sole case wherein there can be two "interactions" overlapping (initialPageLoad + regular route-change),
+      the regular interaction should get precedence in being assigned the "active" interaction in regards to our one-at-a-time model.
+    */
+    if (this.interactionInProgress?.isActiveDuring(timestamp)) return this.interactionInProgress;
+    let saveIxn;
+    for (let idx = this.interactionsToHarvest.length - 1; idx >= 0; idx--) {
+      // reverse search for the latest completed interaction for efficiency
+      const finishedInteraction = this.interactionsToHarvest[idx];
+      if (finishedInteraction.isActiveDuring(timestamp)) {
+        if (finishedInteraction.trigger !== 'initialPageLoad') 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;
+      }
+    }
+    if (saveIxn) return saveIxn; // if an iPL was determined to be active and no route-change was found active for the same time, then iPL is deemed the one
+    if (this.initialPageLoadInteraction?.isActiveDuring(timestamp)) return this.initialPageLoadInteraction; // lowest precedence and also only if it's still in-progress
+    // Time must be when no interaction is happening, so return undefined.
+  }
+
+  /**
+   * Handles or redirect ajax event based on the interaction, if any, that it's tied to.
+   * @param {Object} event see Ajax feature's storeXhr function for object definition
+   */
+  #handleAjaxEvent(event) {
+    const associatedInteraction = this.getInteractionFor(event.startTime);
+    if (!associatedInteraction) {
+      // no interaction was happening when this ajax started, so give it back to Ajax feature for processing
+      (0, _handle.handle)('returnAjax', [event], undefined, _features.FEATURE_NAMES.ajax, this.ee);
+    } else {
+      if (associatedInteraction.status === _constants2.INTERACTION_STATUS.FIN) processAjax(this.agentIdentifier, event, associatedInteraction); // tack ajax onto the ixn object awaiting harvest
+      else {
+        // same thing as above, just at a later time -- if the interaction in progress is cancelled, just send the event back to ajax feat unmodified
+        associatedInteraction.on('finished', () => processAjax(this.agentIdentifier, event, associatedInteraction));
+        associatedInteraction.on('cancelled', () => (0, _handle.handle)('returnAjax', [event], undefined, _features.FEATURE_NAMES.ajax, this.ee));
+      }
+    }
+    function processAjax(agentId, event, parentInteraction) {
+      const newNode = new _ajaxNode.AjaxNode(agentId, event);
+      parentInteraction.addChild(newNode);
+    }
+  }
+
+  /**
+   * Decorate the passed-in params obj with properties relating to any associated interaction at the time of the timestamp.
+   * @param {Object} params reference to the local var instance in Jserrors feature's storeError
+   * @param {DOMHighResTimeStamp} timestamp time the jserror occurred
+   */
+  #handleJserror(params, timestamp) {
+    const associatedInteraction = this.getInteractionFor(timestamp);
+    if (!associatedInteraction) return; // do not need to decorate this jserror params
+
+    // Whether the interaction is in-progress or already finished, the id will let jserror buffer it under its index, until it gets the next step instruction.
+    params.browserInteractionId = associatedInteraction.id;
+    if (associatedInteraction.status === _constants2.INTERACTION_STATUS.FIN) {
+      // This information cannot be relayed back via handle() that flushes buffered errs because this is being called by a jserror's handle() per se and before the err is buffered.
+      params._softNavFinished = true; // instead, signal that this err can be processed right away without needing to be buffered aka wait for an in-progress ixn
+      params._softNavAttributes = associatedInteraction.customAttributes;
+    } else {
+      // These callbacks may be added multiple times for an ixn, but just a single run will deal with all jserrors associated with the interaction.
+      // As such, be cautious not to use the params object since that's tied to one specific jserror and won't affect the rest of them.
+      associatedInteraction.on('finished', (0, _invoke.single)(() => (0, _handle.handle)('softNavFlush', [associatedInteraction.id, true, associatedInteraction.customAttributes], undefined, _features.FEATURE_NAMES.jserrors, this.ee)));
+      associatedInteraction.on('cancelled', (0, _invoke.single)(() => (0, _handle.handle)('softNavFlush', [associatedInteraction.id, false, undefined], undefined, _features.FEATURE_NAMES.jserrors, this.ee))); // don't take custom attrs from cancelled ixns
+    }
+  }
+  #registerApiHandlers() {
+    const INTERACTION_API = 'api-ixn-';
+    const thisClass = this;
+    (0, _registerHandler.registerHandler)(INTERACTION_API + 'get', function (time) {
+      let {
+        waitForEnd
+      } = arguments.length > 1 && arguments[1] !== undefined ? arguments[1] : {};
+      // 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) {
+        // 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.setClosureHandlers();
+      }
+      if (waitForEnd === true) this.associatedInteraction.keepOpenUntilEndApi = true;
+    }, thisClass.featureName, thisClass.ee);
+    (0, _registerHandler.registerHandler)(INTERACTION_API + 'end', function (timeNow) {
+      this.associatedInteraction.done(timeNow);
+    }, thisClass.featureName, thisClass.ee);
+    (0, _registerHandler.registerHandler)(INTERACTION_API + 'save', function () {
+      this.associatedInteraction.forceSave = true;
+    }, thisClass.featureName, thisClass.ee);
+    (0, _registerHandler.registerHandler)(INTERACTION_API + 'ignore', function () {
+      this.associatedInteraction.forceIgnore = true;
+    }, thisClass.featureName, thisClass.ee);
+    (0, _registerHandler.registerHandler)(INTERACTION_API + 'getContext', function (time, callback) {
+      if (typeof callback !== 'function') return;
+      setTimeout(() => callback(this.associatedInteraction.customDataByApi), 0);
+    }, thisClass.featureName, thisClass.ee);
+    (0, _registerHandler.registerHandler)(INTERACTION_API + 'onEnd', function (time, callback) {
+      if (typeof callback !== 'function') return;
+      this.associatedInteraction.onDone.push(callback);
+    }, thisClass.featureName, thisClass.ee);
+    (0, _registerHandler.registerHandler)(INTERACTION_API + 'actionText', function (time, newActionText) {
+      if (newActionText) this.associatedInteraction.customAttributes.actionText = newActionText;
+    }, thisClass.featureName, thisClass.ee);
+    (0, _registerHandler.registerHandler)(INTERACTION_API + 'setName', function (time, name, trigger) {
+      if (name) this.associatedInteraction.customName = name;
+      if (trigger) this.associatedInteraction.trigger = trigger;
+    }, thisClass.featureName, thisClass.ee);
+    (0, _registerHandler.registerHandler)(INTERACTION_API + 'setAttribute', function (time, key, value) {
+      this.associatedInteraction.customAttributes[key] = value;
+    }, thisClass.featureName, thisClass.ee);
+    (0, _registerHandler.registerHandler)(INTERACTION_API + 'routeName', function (time, newRouteName) {
+      // notice that this fn tampers with the ixn IP, not with the linked ixn
+      thisClass.latestRouteSetByApi = newRouteName;
+      if (thisClass.interactionInProgress) thisClass.interactionInProgress.newRoute = newRouteName;
+    }, thisClass.featureName, thisClass.ee);
+  }
+}
+exports.Aggregate = Aggregate;
+function getActionText(elem) {
+  const tagName = elem.tagName.toLowerCase();
+  const elementsOfInterest = ['a', 'button', 'input'];
+  if (elementsOfInterest.includes(tagName)) {
+    return elem.title || elem.value || elem.innerText;
+  }
+}

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

@@ -0,0 +1,62 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.InitialPageLoadInteraction = void 0;
+var _navTiming = require("../../../common/timing/nav-timing");
+var _interaction = require("./interaction");
+var _belSerializer = require("../../../common/serialize/bel-serializer");
+var _firstPaint = require("../../../common/vitals/first-paint");
+var _firstContentfulPaint = require("../../../common/vitals/first-contentful-paint");
+var _config = require("../../../common/config/config");
+class InitialPageLoadInteraction extends _interaction.Interaction {
+  constructor(agentIdentifier) {
+    super(agentIdentifier, 'initialPageLoad', 0, null);
+    const agentInfo = (0, _config.getInfo)(agentIdentifier);
+    this.queueTime = agentInfo.queueTime;
+    this.appTime = agentInfo.applicationTime;
+  }
+  get firstPaint() {
+    return _firstPaint.firstPaint.current.value;
+  }
+  get firstContentfulPaint() {
+    return _firstContentfulPaint.firstContentfulPaint.current.value;
+  }
+
+  /**
+   * Build the navTiming node. This assumes the navTimingValues array in nav-timing.js has already been filled with values via the PageViewEvent feature having
+   * executed the addPT function first and foremost.
+   */
+  get navTiming() {
+    if (!_navTiming.navTimingValues.length) return;
+    /*
+    1. we initialize the seperator to ',' (seperates the nodeType id from the first value)
+    2. we initialize the navTiming node to 'b' (the nodeType id)
+    3. if the value is present, we add the seperator followed by the value;
+       otherwise:
+        - we add null seperator ('!') to the navTimingNode
+        - we set the seperator to an empty string since we already wrote it above
+      the reason for writing the null seperator instead of setting the seperator
+      is to ensure we still write it if the null is the last navTiming value.
+    */
+    let seperator = ',';
+    let navTimingNode = 'b';
+    let prev = 0;
+
+    // Get all navTiming values except offset aka timeOrigin since we just consider that (this.start) 0.
+    // These are the latter 20 of the 21 timings appended by addPT:
+    _navTiming.navTimingValues.slice(1, 21).forEach(v => {
+      if (v !== undefined) {
+        navTimingNode += seperator + (0, _belSerializer.numeric)(v - prev);
+        seperator = ',';
+        prev = v;
+      } else {
+        navTimingNode += seperator + '!';
+        seperator = '';
+      }
+    });
+    return navTimingNode;
+  }
+}
+exports.InitialPageLoadInteraction = InitialPageLoadInteraction;

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

@@ -0,0 +1,146 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.Interaction = void 0;
+var _config = require("../../../common/config/config");
+var _runtime = require("../../../common/constants/runtime");
+var _uniqueId = require("../../../common/ids/unique-id");
+var _belSerializer = require("../../../common/serialize/bel-serializer");
+var _cleanUrl = require("../../../common/url/clean-url");
+var _constants = require("../constants");
+var _belNode = require("./bel-node");
+/**
+ * link https://github.com/newrelic/nr-querypack/blob/main/schemas/bel/7.qpschema
+ **/
+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 = {};
+  queueTime; // only used by initialPageLoad interactions
+  appTime; // only used by initialPageLoad interactions
+  newRoute;
+  /** Internal state of this interaction: in-progress, finished, or cancelled. */
+  status = _constants.INTERACTION_STATUS.IP;
+  domTimestamp = 0;
+  historyTimestamp = 0;
+  createdByApi = false;
+  keepOpenUntilEndApi = false;
+  onDone = [];
+  cancellationTimer;
+  constructor(agentIdentifier, uiEvent, uiEventTimestamp, currentRouteKnown) {
+    super(agentIdentifier);
+    this.belType = _constants.NODE_TYPE.INTERACTION;
+    this.trigger = uiEvent;
+    this.start = uiEventTimestamp;
+    this.oldRoute = currentRouteKnown;
+    this.eventSubscription = new Map([['finished', []], ['cancelled', []]]);
+    this.forceSave = this.forceIgnore = false;
+    if (this.trigger === _constants.API_TRIGGER_NAME) this.createdByApi = true;
+  }
+  updateDom(timestamp) {
+    this.domTimestamp = timestamp || performance.now(); // default timestamp should be precise for accurate isActiveDuring calculations
+  }
+  updateHistory(timestamp, newUrl) {
+    this.newURL = newUrl || '' + _runtime.globalScope?.location;
+    this.historyTimestamp = timestamp || performance.now();
+  }
+  seenHistoryAndDomChange() {
+    return this.historyTimestamp > 0 && this.domTimestamp > this.historyTimestamp; // URL must change before DOM does
+  }
+  on(event, cb) {
+    if (!this.eventSubscription.has(event)) throw new Error('Cannot subscribe to non pre-defined events.');
+    if (typeof cb !== 'function') throw new Error('Must supply function as callback.');
+    this.eventSubscription.get(event).push(cb);
+  }
+  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;
+    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
+    else if (this.seenHistoryAndDomChange()) this.#finish(customEndTime); // then this should've already finished while it was the interactionInProgress, with a natural end time
+    else if (this.forceSave) this.#finish(customEndTime || performance.now()); // a manually saved ixn (did not fulfill conditions) must have a specified end time, if one wasn't provided
+    else this.#cancel();
+    return true;
+  }
+  #finish() {
+    let customEndTime = arguments.length > 0 && arguments[0] !== undefined ? arguments[0] : 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 = {
+      ...(0, _config.getInfo)(this.agentIdentifier).jsAttributes,
+      ...this.customAttributes
+    }; // attrs specific to this interaction should have precedence over the general custom attrs
+    this.status = _constants.INTERACTION_STATUS.FIN;
+
+    // Run all the callbacks awaiting this interaction to finish.
+    const callbacks = this.eventSubscription.get('finished');
+    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;
+
+    // Run all the callbacks listening to this interaction's potential cancellation.
+    const callbacks = this.eventSubscription.get('cancelled');
+    callbacks.forEach(fn => fn());
+  }
+
+  /**
+   * Given a timestamp, determine if it falls within this interaction's span, i.e. if this was the active interaction during that time.
+   * For in-progress interactions, this only compares the time with the start of span. Cancelled interactions are not considered active at all.
+   * @param {DOMHighResTimeStamp} timestamp
+   * @returns True or false boolean.
+   */
+  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;
+  }
+
+  // Following are virtual properties overridden by a subclass:
+  get firstPaint() {}
+  get firstContentfulPaint() {}
+  get navTiming() {}
+  serialize(firstStartTimeOfPayload) {
+    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;
+
+    // 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)(Math.floor(this.start - firstStartTimeOfPayload)),
+    // relative to first node
+    (0, _belSerializer.numeric)(Math.floor(this.end - this.start)),
+    // end -- relative to start
+    (0, _belSerializer.numeric)(this.callbackEnd),
+    // cbEnd -- relative to start; not used by BrowserInteraction events
+    (0, _belSerializer.numeric)(this.callbackDuration),
+    // not relative
+    addString(this.trigger), addString((0, _cleanUrl.cleanURL)(this.initialPageURL, true)), addString((0, _cleanUrl.cleanURL)(this.oldURL, true)), addString((0, _cleanUrl.cleanURL)(this.newURL, true)), addString(this.customName), ixnType, (0, _belSerializer.nullable)(this.queueTime, _belSerializer.numeric, true) + (0, _belSerializer.nullable)(this.appTime, _belSerializer.numeric, true) + (0, _belSerializer.nullable)(this.oldRoute, addString, true) + (0, _belSerializer.nullable)(this.newRoute, addString, true) + addString(this.id), addString(this.nodeId), (0, _belSerializer.nullable)(this.firstPaint, _belSerializer.numeric, true) + (0, _belSerializer.nullable)(this.firstContentfulPaint, _belSerializer.numeric)];
+    const allAttachedNodes = (0, _belSerializer.addCustomAttributes)(this.customAttributes || {}, addString); // start with all custom attributes
+    if ((0, _config.getInfo)(this.agentIdentifier).atts) allAttachedNodes.push('a,' + addString((0, _config.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
+
+    fields[1] = (0, _belSerializer.numeric)(allAttachedNodes.length);
+    nodeList.push(fields);
+    if (allAttachedNodes.length) nodeList.push(allAttachedNodes.join(';'));
+    if (this.navTiming) nodeList.push(this.navTiming);else nodeList.push('');
+    // nodeList = [<fields array>, <serialized string of all attributes and children>, <serialized nav timing info> || '']
+
+    return nodeList.join(';');
+  }
+}
+exports.Interaction = Interaction;

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

@@ -0,0 +1,31 @@
+"use strict";
+
+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;
+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
+];
+const API_TRIGGER_NAME = exports.API_TRIGGER_NAME = 'api';
+const FEATURE_NAME = exports.FEATURE_NAME = _features.FEATURE_NAMES.softNav;
+const INTERACTION_TYPE = exports.INTERACTION_TYPE = {
+  INITIAL_PAGE_LOAD: '',
+  ROUTE_CHANGE: 1,
+  UNSPECIFIED: 2
+};
+const NODE_TYPE = exports.NODE_TYPE = {
+  INTERACTION: 1,
+  AJAX: 2,
+  CUSTOM_END: 3,
+  CUSTOM_TRACER: 4
+};
+const INTERACTION_STATUS = exports.INTERACTION_STATUS = {
+  IP: 'in progress',
+  FIN: 'finished',
+  CAN: 'cancelled'
+};

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

@@ -0,0 +1,12 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+Object.defineProperty(exports, "SoftNav", {
+  enumerable: true,
+  get: function () {
+    return _index.Instrument;
+  }
+});
+var _index = require("./instrument/index");

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

@@ -0,0 +1,79 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.Instrument = void 0;
+var _config = require("../../../common/config/config");
+var _runtime = require("../../../common/constants/runtime");
+var _handle = require("../../../common/event-emitter/handle");
+var _eventListenerOpts = require("../../../common/event-listener/event-listener-opts");
+var _now = require("../../../common/timing/now");
+var _invoke = require("../../../common/util/invoke");
+var _wrap = require("../../../common/wrap");
+var _instrumentBase = require("../../utils/instrument-base");
+var _constants = require("../constants");
+/** The minimal time after a UI event for which no further events will be processed - i.e. a throttling rate to reduce spam.
+ * This also give some time for the new interaction to complete without being discarded by a subsequent UI event and wrongly attributed.
+ * This value is still subject to change and critique, as it is derived from beyond worst case time to next frame of a page.
+ */
+const UI_WAIT_INTERVAL = 1 / 10 * 1000; // assume 10 fps
+
+class Instrument extends _instrumentBase.InstrumentBase {
+  static featureName = _constants.FEATURE_NAME;
+  constructor(agentIdentifier, aggregator) {
+    let auto = arguments.length > 2 && arguments[2] !== undefined ? arguments[2] : true;
+    super(agentIdentifier, aggregator, _constants.FEATURE_NAME, auto);
+    if (!_runtime.isBrowserScope || !_config.originals.MO) return; // soft navigations is not supported outside web env or browsers without the mutation observer API
+
+    const historyEE = (0, _wrap.wrapHistory)(this.ee);
+    const eventsEE = (0, _wrap.wrapEvents)(this.ee);
+    const trackURLChange = () => (0, _handle.handle)('newURL', [(0, _now.now)(), '' + window.location], undefined, this.featureName, this.ee);
+    historyEE.on('pushState-end', trackURLChange);
+    historyEE.on('replaceState-end', trackURLChange);
+    try {
+      this.removeOnAbort = new AbortController();
+    } catch (e) {}
+    const trackURLChangeEvent = evt => (0, _handle.handle)('newURL', [evt.timeStamp, '' + window.location], undefined, this.featureName, this.ee);
+    (0, _eventListenerOpts.windowAddEventListener)('popstate', trackURLChangeEvent, true, this.removeOnAbort?.signal);
+    let oncePerFrame = false; // attempt to reduce dom noice since the observer runs very frequently with below options
+    const domObserver = new _config.originals.MO((domChanges, observer) => {
+      if (oncePerFrame) return;
+      oncePerFrame = true;
+      requestAnimationFrame(() => {
+        // waiting for next frame to time when any visuals are supposedly updated
+        (0, _handle.handle)('newDom', [(0, _now.now)()], undefined, this.featureName, this.ee);
+        oncePerFrame = false;
+      });
+    });
+    const processUserInteraction = (0, _invoke.debounce)(event => {
+      (0, _handle.handle)('newUIEvent', [event], undefined, this.featureName, this.ee);
+      domObserver.observe(document.body, {
+        attributes: true,
+        childList: true,
+        subtree: true,
+        characterData: true
+      });
+    }, UI_WAIT_INTERVAL, {
+      leading: true
+    });
+    eventsEE.on('fn-start', _ref => {
+      let [evt] = _ref;
+      // set up a new user ixn before the callback for the triggering event executes
+      if (_constants.INTERACTION_TRIGGERS.includes(evt?.type)) {
+        processUserInteraction(evt);
+      }
+    });
+    for (let eventType of _constants.INTERACTION_TRIGGERS) document.addEventListener(eventType, () => {/* no-op, this ensures the UI events are monitored by our callback above */});
+    this.abortHandler = abort;
+    this.importAggregator({
+      domObserver
+    });
+    function abort() {
+      this.removeOnAbort?.abort();
+      domObserver.disconnect();
+      this.abortHandler = undefined; // weakly allow this abort op to run only once
+    }
+  }
+}
+exports.Instrument = Instrument;

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

@@ -656,7 +656,7 @@ class Aggregate extends _aggregateBase.AggregateBase {
     }
     function saveInteraction(interaction) {
       if (interaction.ignored || !interaction.save && !interaction.routeChange) {
-        baseEE.emit('interactionDiscarded', [interaction]);
+        baseEE.emit('interactionDone', [interaction, false]);
         return;
       }
       if (state.prevInteraction === interaction) {
@@ -672,10 +672,10 @@ class Aggregate extends _aggregateBase.AggregateBase {
         interaction.root.attrs.firstPaint = _firstPaint.firstPaint.current.value;
         interaction.root.attrs.firstContentfulPaint = _firstContentfulPaint.firstContentfulPaint.current.value;
       }
-      baseEE.emit('interactionSaved', [interaction]);
+      baseEE.emit('interactionDone', [interaction, true]);
       state.interactionsToHarvest.push(interaction);
-      let smCategory = 'RouteChange';
-      if (interaction.root?.attrs?.trigger === 'initialPageLoad') smCategory = 'InitialPageLoad';else if (interaction.root?.attrs?.trigger === 'api') smCategory = 'Custom';
+      let smCategory;
+      if (interaction.root?.attrs?.trigger === 'initialPageLoad') smCategory = 'InitialPageLoad';else if (interaction.routeChange) smCategory = 'RouteChange';else smCategory = 'Custom';
       (0, _handle.handle)(_constants2.SUPPORTABILITY_METRIC_CHANNEL, ["Spa/Interaction/".concat(smCategory, "/Duration/Ms"), Math.max((interaction.root?.end || 0) - (interaction.root?.start || 0), 0)], undefined, _features.FEATURE_NAMES.metrics, baseEE);
       scheduler.scheduleHarvest(0);
     }

package/dist/cjs/features/utils/agent-session.js

@@ -11,6 +11,7 @@ var _registerHandler = require("../../common/event-emitter/register-handler");
 var _sessionEntity = require("../../common/session/session-entity");
 var _localStorage = require("../../common/storage/local-storage.js");
 var _firstPartyCookies = require("../../common/storage/first-party-cookies");
+var _constants = require("../../common/session/constants");
 let ranOnce = 0;
 function setupAgentSession(agentIdentifier) {
   const agentRuntime = (0, _config.getRuntime)(agentIdentifier);
@@ -21,7 +22,7 @@ function setupAgentSession(agentIdentifier) {
   const storageTypeInst = sessionInit?.domain ? new _firstPartyCookies.FirstPartyCookies(sessionInit.domain) : new _localStorage.LocalStorage();
   agentRuntime.session = new _sessionEntity.SessionEntity({
     agentIdentifier,
-    key: 'SESSION',
+    key: _constants.DEFAULT_KEY,
     storage: storageTypeInst,
     expiresMs: sessionInit?.expiresMs,
     inactiveMs: sessionInit?.inactiveMs