@newrelic/browser-agent 1.252.0 → 1.253.0

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

@@ -0,0 +1,256 @@
+import { getConfigurationValue } from '../../../common/config/config';
+import { handle } from '../../../common/event-emitter/handle';
+import { registerHandler } from '../../../common/event-emitter/register-handler';
+import { HarvestScheduler } from '../../../common/harvest/harvest-scheduler';
+import { single } from '../../../common/util/invoke';
+import { timeToFirstByte } from '../../../common/vitals/time-to-first-byte';
+import { FEATURE_NAMES } 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 { AjaxNode } from './ajax-node';
+import { InitialPageLoadInteraction } from './initial-page-load-interaction';
+import { Interaction } from './interaction';
+export class Aggregate extends AggregateBase {
+  static featureName = FEATURE_NAME;
+  constructor(agentIdentifier, aggregator, _ref) {
+    let {
+      domObserver
+    } = _ref;
+    super(agentIdentifier, aggregator, FEATURE_NAME);
+    const harvestTimeSeconds = getConfigurationValue(agentIdentifier, 'soft_navigations.harvestTimeSeconds') || 10;
+    this.interactionsToHarvest = [];
+    this.interactionsAwaitingRetry = [];
+    this.domObserver = domObserver;
+    this.scheduler = new 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(agentIdentifier);
+    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
+      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.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.
+    registerHandler('newUIEvent', event => this.startUIInteraction(event.type, event.timeStamp, event.target), this.featureName, this.ee);
+    registerHandler('newURL', (timestamp, url) => this.interactionInProgress?.updateHistory(timestamp, url), this.featureName, this.ee);
+    registerHandler('newDom', timestamp => {
+      this.interactionInProgress?.updateDom(timestamp);
+      if (this.interactionInProgress?.seenHistoryAndDomChange()) this.interactionInProgress.done();
+    }, this.featureName, this.ee);
+    this.#registerApiHandlers();
+    registerHandler('ajax', this.#handleAjaxEvent.bind(this), this.featureName, this.ee);
+    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(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
+      handle(SUPPORTABILITY_METRIC_CHANNEL, ['SoftNav/Interaction/TimeOut'], undefined, 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
+      handle(SUPPORTABILITY_METRIC_CHANNEL, ["SoftNav/Interaction/".concat(ref.newURL !== ref.oldURL ? 'RouteChange' : 'Custom', "/Duration/Ms"), Math.round(ref.end - ref.start)], undefined, 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
+      handle('returnAjax', [event], undefined, FEATURE_NAMES.ajax, this.ee);
+    } else {
+      if (associatedInteraction.status === 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', () => handle('returnAjax', [event], undefined, FEATURE_NAMES.ajax, this.ee));
+      }
+    }
+    function processAjax(agentId, event, parentInteraction) {
+      const newNode = new 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 === 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', single(() => handle('softNavFlush', [associatedInteraction.id, true, associatedInteraction.customAttributes], undefined, FEATURE_NAMES.jserrors, this.ee)));
+      associatedInteraction.on('cancelled', single(() => handle('softNavFlush', [associatedInteraction.id, false, undefined], undefined, FEATURE_NAMES.jserrors, this.ee))); // don't take custom attrs from cancelled ixns
+    }
+  }
+  #registerApiHandlers() {
+    const INTERACTION_API = 'api-ixn-';
+    const thisClass = this;
+    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(thisClass.agentIdentifier, API_TRIGGER_NAME, time, thisClass.latestRouteSetByApi);
+        thisClass.setClosureHandlers();
+      }
+      if (waitForEnd === true) this.associatedInteraction.keepOpenUntilEndApi = true;
+    }, thisClass.featureName, thisClass.ee);
+    registerHandler(INTERACTION_API + 'end', function (timeNow) {
+      this.associatedInteraction.done(timeNow);
+    }, thisClass.featureName, thisClass.ee);
+    registerHandler(INTERACTION_API + 'save', function () {
+      this.associatedInteraction.forceSave = true;
+    }, thisClass.featureName, thisClass.ee);
+    registerHandler(INTERACTION_API + 'ignore', function () {
+      this.associatedInteraction.forceIgnore = true;
+    }, thisClass.featureName, thisClass.ee);
+    registerHandler(INTERACTION_API + 'getContext', function (time, callback) {
+      if (typeof callback !== 'function') return;
+      setTimeout(() => callback(this.associatedInteraction.customDataByApi), 0);
+    }, thisClass.featureName, thisClass.ee);
+    registerHandler(INTERACTION_API + 'onEnd', function (time, callback) {
+      if (typeof callback !== 'function') return;
+      this.associatedInteraction.onDone.push(callback);
+    }, thisClass.featureName, thisClass.ee);
+    registerHandler(INTERACTION_API + 'actionText', function (time, newActionText) {
+      if (newActionText) this.associatedInteraction.customAttributes.actionText = newActionText;
+    }, thisClass.featureName, thisClass.ee);
+    registerHandler(INTERACTION_API + 'setName', function (time, name, trigger) {
+      if (name) this.associatedInteraction.customName = name;
+      if (trigger) this.associatedInteraction.trigger = trigger;
+    }, thisClass.featureName, thisClass.ee);
+    registerHandler(INTERACTION_API + 'setAttribute', function (time, key, value) {
+      this.associatedInteraction.customAttributes[key] = value;
+    }, thisClass.featureName, thisClass.ee);
+    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);
+  }
+}
+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/esm/features/soft_navigations/aggregate/initial-page-load-interaction.js

@@ -0,0 +1,55 @@
+import { navTimingValues } from '../../../common/timing/nav-timing';
+import { Interaction } from './interaction';
+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/config';
+export class InitialPageLoadInteraction extends Interaction {
+  constructor(agentIdentifier) {
+    super(agentIdentifier, 'initialPageLoad', 0, null);
+    const agentInfo = getInfo(agentIdentifier);
+    this.queueTime = agentInfo.queueTime;
+    this.appTime = agentInfo.applicationTime;
+  }
+  get firstPaint() {
+    return firstPaint.current.value;
+  }
+  get firstContentfulPaint() {
+    return 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 (!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:
+    navTimingValues.slice(1, 21).forEach(v => {
+      if (v !== undefined) {
+        navTimingNode += seperator + numeric(v - prev);
+        seperator = ',';
+        prev = v;
+      } else {
+        navTimingNode += seperator + '!';
+        seperator = '';
+      }
+    });
+    return navTimingNode;
+  }
+}

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

@@ -0,0 +1,140 @@
+import { getInfo } from '../../../common/config/config';
+import { globalScope, initialLocation } from '../../../common/constants/runtime';
+import { generateUuid } from '../../../common/ids/unique-id';
+import { addCustomAttributes, getAddStringContext, nullable, numeric } from '../../../common/serialize/bel-serializer';
+import { cleanURL } from '../../../common/url/clean-url';
+import { NODE_TYPE, INTERACTION_STATUS, INTERACTION_TYPE, API_TRIGGER_NAME } from '../constants';
+import { BelNode } from './bel-node';
+
+/**
+ * link https://github.com/newrelic/nr-querypack/blob/main/schemas/bel/7.qpschema
+ **/
+export class Interaction extends BelNode {
+  id = generateUuid(); // unique id that is serialized and used to link interactions with errors
+  initialPageURL = initialLocation;
+  oldURL = '' + globalScope?.location;
+  newURL = '' + 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 = INTERACTION_STATUS.IP;
+  domTimestamp = 0;
+  historyTimestamp = 0;
+  createdByApi = false;
+  keepOpenUntilEndApi = false;
+  onDone = [];
+  cancellationTimer;
+  constructor(agentIdentifier, uiEvent, uiEventTimestamp, currentRouteKnown) {
+    super(agentIdentifier);
+    this.belType = 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 === 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 || '' + 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 !== 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 = {
+      ...getInfo(this.agentIdentifier).jsAttributes,
+      ...this.customAttributes
+    }; // attrs specific to this interaction should have precedence over the general custom attrs
+    this.status = 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 !== INTERACTION_STATUS.IP) return; // disallow this call if the ixn is already done aka not in-progress
+    clearTimeout(this.cancellationTimer);
+    this.status = 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 === INTERACTION_STATUS.IP) return this.start <= timestamp;
+    return this.status === 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 = getAddStringContext(this.agentIdentifier);
+    const nodeList = [];
+    let ixnType;
+    if (this.trigger === 'initialPageLoad') ixnType = INTERACTION_TYPE.INITIAL_PAGE_LOAD;else if (this.newURL !== this.oldURL) ixnType = INTERACTION_TYPE.ROUTE_CHANGE;else ixnType = 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 = [numeric(this.belType), 0,
+    // this will be overwritten below with number of attached nodes
+    numeric(Math.floor(this.start - firstStartTimeOfPayload)),
+    // relative to first node
+    numeric(Math.floor(this.end - this.start)),
+    // end -- relative to start
+    numeric(this.callbackEnd),
+    // cbEnd -- relative to start; not used by BrowserInteraction events
+    numeric(this.callbackDuration),
+    // not relative
+    addString(this.trigger), addString(cleanURL(this.initialPageURL, true)), addString(cleanURL(this.oldURL, true)), addString(cleanURL(this.newURL, true)), addString(this.customName), ixnType, nullable(this.queueTime, numeric, true) + nullable(this.appTime, numeric, true) + nullable(this.oldRoute, addString, true) + nullable(this.newRoute, addString, true) + addString(this.id), addString(this.nodeId), nullable(this.firstPaint, numeric, true) + nullable(this.firstContentfulPaint, numeric)];
+    const allAttachedNodes = addCustomAttributes(this.customAttributes || {}, addString); // start with all custom attributes
+    if (getInfo(this.agentIdentifier).atts) allAttachedNodes.push('a,' + addString(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] = 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(';');
+  }
+}

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

@@ -0,0 +1,25 @@
+import { FEATURE_NAMES } from '../../loaders/features/features';
+export const 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
+];
+export const API_TRIGGER_NAME = 'api';
+export const FEATURE_NAME = FEATURE_NAMES.softNav;
+export const INTERACTION_TYPE = {
+  INITIAL_PAGE_LOAD: '',
+  ROUTE_CHANGE: 1,
+  UNSPECIFIED: 2
+};
+export const NODE_TYPE = {
+  INTERACTION: 1,
+  AJAX: 2,
+  CUSTOM_END: 3,
+  CUSTOM_TRACER: 4
+};
+export const INTERACTION_STATUS = {
+  IP: 'in progress',
+  FIN: 'finished',
+  CAN: 'cancelled'
+};

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

@@ -0,0 +1 @@
+export { Instrument as SoftNav } from './instrument/index';

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

@@ -0,0 +1,73 @@
+import { originals } from '../../../common/config/config';
+import { isBrowserScope } from '../../../common/constants/runtime';
+import { handle } from '../../../common/event-emitter/handle';
+import { windowAddEventListener } from '../../../common/event-listener/event-listener-opts';
+import { now } from '../../../common/timing/now';
+import { debounce } from '../../../common/util/invoke';
+import { wrapEvents, wrapHistory } from '../../../common/wrap';
+import { InstrumentBase } from '../../utils/instrument-base';
+import { FEATURE_NAME, INTERACTION_TRIGGERS } from '../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
+
+export class Instrument extends InstrumentBase {
+  static featureName = FEATURE_NAME;
+  constructor(agentIdentifier, aggregator) {
+    let auto = arguments.length > 2 && arguments[2] !== undefined ? arguments[2] : true;
+    super(agentIdentifier, aggregator, FEATURE_NAME, auto);
+    if (!isBrowserScope || !originals.MO) return; // soft navigations is not supported outside web env or browsers without the mutation observer API
+
+    const historyEE = wrapHistory(this.ee);
+    const eventsEE = wrapEvents(this.ee);
+    const trackURLChange = () => handle('newURL', [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 => handle('newURL', [evt.timeStamp, '' + window.location], undefined, this.featureName, this.ee);
+    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 originals.MO((domChanges, observer) => {
+      if (oncePerFrame) return;
+      oncePerFrame = true;
+      requestAnimationFrame(() => {
+        // waiting for next frame to time when any visuals are supposedly updated
+        handle('newDom', [now()], undefined, this.featureName, this.ee);
+        oncePerFrame = false;
+      });
+    });
+    const processUserInteraction = debounce(event => {
+      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 (INTERACTION_TRIGGERS.includes(evt?.type)) {
+        processUserInteraction(evt);
+      }
+    });
+    for (let eventType of 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
+    }
+  }
+}

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

@@ -647,7 +647,7 @@ export class Aggregate extends 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) {
@@ -663,10 +663,10 @@ export class Aggregate extends AggregateBase {
         interaction.root.attrs.firstPaint = firstPaint.current.value;
         interaction.root.attrs.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';
       handle(SUPPORTABILITY_METRIC_CHANNEL, ["Spa/Interaction/".concat(smCategory, "/Duration/Ms"), Math.max((interaction.root?.end || 0) - (interaction.root?.start || 0), 0)], undefined, FEATURE_NAMES.metrics, baseEE);
       scheduler.scheduleHarvest(0);
     }

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

@@ -5,6 +5,7 @@ import { registerHandler } from '../../common/event-emitter/register-handler';
 import { SessionEntity } from '../../common/session/session-entity';
 import { LocalStorage } from '../../common/storage/local-storage.js';
 import { FirstPartyCookies } from '../../common/storage/first-party-cookies';
+import { DEFAULT_KEY } from '../../common/session/constants';
 let ranOnce = 0;
 export function setupAgentSession(agentIdentifier) {
   const agentRuntime = getRuntime(agentIdentifier);
@@ -15,7 +16,7 @@ export function setupAgentSession(agentIdentifier) {
   const storageTypeInst = sessionInit?.domain ? new FirstPartyCookies(sessionInit.domain) : new LocalStorage();
   agentRuntime.session = new SessionEntity({
     agentIdentifier,
-    key: 'SESSION',
+    key: DEFAULT_KEY,
     storage: storageTypeInst,
     expiresMs: sessionInit?.expiresMs,
     inactiveMs: sessionInit?.inactiveMs

package/dist/esm/features/utils/instrument-base.js

@@ -10,7 +10,8 @@ import { onWindowLoad } from '../../common/window/load';
 import { isBrowserScope } from '../../common/constants/runtime';
 import { warn } from '../../common/util/console';
 import { FEATURE_NAMES } from '../../loaders/features/features';
-import { getConfigurationValue, originals } from '../../common/config/config';
+import { getConfigurationValue } from '../../common/config/config';
+import { canImportReplayAgg, enableSessionTracking } from '../session_replay/shared/utils';
 
 /**
  * Base class for instrumenting a feature.
@@ -73,7 +74,6 @@ export class InstrumentBase extends FeatureBase {
       });
       return;
     }
-    const enableSessionTracking = isBrowserScope && getConfigurationValue(this.agentIdentifier, 'privacy.cookies_enabled') === true;
     let loadedSuccessfully;
     this.onAggregateImported = new Promise(resolve => {
       loadedSuccessfully = resolve;
@@ -81,7 +81,7 @@ export class InstrumentBase extends FeatureBase {
     const importLater = async () => {
       let session;
       try {
-        if (enableSessionTracking) {
+        if (enableSessionTracking(this.agentIdentifier)) {
           // would require some setup before certain features start
           const {
             setupAgentSession
@@ -90,6 +90,7 @@ export class InstrumentBase extends FeatureBase {
         }
       } catch (e) {
         warn('A problem occurred when starting up session manager. This page will not start or extend any session.', e);
+        if (this.featureName === FEATURE_NAMES.sessionReplay) this.abortHandler?.(); // SR should stop recording if session DNE
       }
 
       /**
@@ -97,7 +98,7 @@ export class InstrumentBase extends FeatureBase {
        * it's only responsible for aborting its one specific feature, rather than all.
        */
       try {
-        if (!this.shouldImportAgg(this.featureName, session)) {
+        if (!this.#shouldImportAgg(this.featureName, session)) {
           drain(this.agentIdentifier, this.featureName);
           loadedSuccessfully(false); // aggregate module isn't loaded at all
           return;
@@ -130,12 +131,8 @@ export class InstrumentBase extends FeatureBase {
   * @param {import('../../common/session/session-entity').SessionEntity} session
   * @returns
   */
-  shouldImportAgg(featureName, session) {
-    if (featureName === FEATURE_NAMES.sessionReplay) {
-      if (!originals.MO) return false; // Session Replay cannot work without Mutation Observer
-      if (getConfigurationValue(this.agentIdentifier, 'session_trace.enabled') === false) return false; // Session Replay as of now is tightly coupled with Session Trace in the UI
-      return !!session?.isNew || !!session?.state.sessionReplayMode; // Session Replay should only try to run if already running from a previous page, or at the beginning of a session
-    }
+  #shouldImportAgg(featureName, session) {
+    if (featureName === FEATURE_NAMES.sessionReplay) return canImportReplayAgg(this.agentIdentifier, session);
     return true;
   }
 }