@newrelic/browser-agent 1.246.1 → 1.248.0

package/CHANGELOG.md

@@ -3,6 +3,30 @@
 All notable changes to this project will be documented in this file.
 See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
 
+## [1.248.0](https://github.com/newrelic/newrelic-browser-agent/compare/v1.247.0...v1.248.0) (2023-11-16)
+
+
+### Features
+
+* Report enduser.id with Session Replay ([#815](https://github.com/newrelic/newrelic-browser-agent/issues/815)) ([8f5446d](https://github.com/newrelic/newrelic-browser-agent/commit/8f5446d1f7679f6a5ea0ba90eb082d1d4deb0d93))
+
+
+### Bug Fixes
+
+* Fix issue with errors forcefully triggering session traces ([#819](https://github.com/newrelic/newrelic-browser-agent/issues/819)) ([3872c35](https://github.com/newrelic/newrelic-browser-agent/commit/3872c35a173f76644b663df5ca0474971451b7cf))
+
+## [1.247.0](https://github.com/newrelic/newrelic-browser-agent/compare/v1.246.1...v1.247.0) (2023-11-14)
+
+
+### Features
+
+* Add basic support for deferring the browser agent loader script ([#800](https://github.com/newrelic/newrelic-browser-agent/issues/800)) ([92d864c](https://github.com/newrelic/newrelic-browser-agent/commit/92d864cb12a3076fd9b623fcd411d2dc9190110c))
+* Add relative timestamps to Session Replay payloads ([#810](https://github.com/newrelic/newrelic-browser-agent/issues/810)) ([e4d1c70](https://github.com/newrelic/newrelic-browser-agent/commit/e4d1c701228e011d7c6f9d84cdc107044c69ce79))
+* Add session durationMs to Session Replay payloads ([#792](https://github.com/newrelic/newrelic-browser-agent/issues/792)) ([3dfc4d4](https://github.com/newrelic/newrelic-browser-agent/commit/3dfc4d43fa978eeec47ebf432f8741562d0dd864))
+* Enable SRI and nonce attributes for async chunks ([#805](https://github.com/newrelic/newrelic-browser-agent/issues/805)) ([fd9c3f3](https://github.com/newrelic/newrelic-browser-agent/commit/fd9c3f388f17353796ac2ebf18814353ca819dcf))
+* Expose library versions used to capture session replay data ([#809](https://github.com/newrelic/newrelic-browser-agent/issues/809)) ([bc275ee](https://github.com/newrelic/newrelic-browser-agent/commit/bc275ee20242a5208358a0a77ac75e2b7cbd11c4))
+* Session Replay API ([#803](https://github.com/newrelic/newrelic-browser-agent/issues/803)) ([12eb453](https://github.com/newrelic/newrelic-browser-agent/commit/12eb4530cfb5eb1e0a94d858485be0df40582c21))
+
 ## [1.246.1](https://github.com/newrelic/newrelic-browser-agent/compare/v1.246.0...v1.246.1) (2023-10-31)
 
 

package/README.md

@@ -39,7 +39,7 @@ Before instrumenting your app using the NPM package, a Browser App should be con
 
 ## Instantiating the agent
 
-For best results, import and instantiate the `BrowserAgent` class as close to the top of the `head` element of your app's HTML output as possible. The specific location and method will vary based on your application's architecture or framework.
+For best results, import and instantiate the `BrowserAgent` class as close to the top of the `head` element of your app's HTML output as possible. The specific location and method will vary based on your application's architecture or framework. See [Library Support](#library-support) for more information.
 
 Populate the `options` parameter using configuration values found in the the *Copy/Paste JavaScript* box in your browser app's *Application settings* page in New Relic One.
 
@@ -229,6 +229,14 @@ import { Agent } from '@newrelic/browser-agent/loaders/agent'
 import { Metrics } from '@newrelic/browser-agent/src/features/metrics'
 ```
 
+## Library Support
+
+The browser agent is written to be agnostic to any JavaScript library or framework. The agent exposes a number of [API methods](https://docs.newrelic.com/docs/browser/new-relic-browser/browser-apis/using-browser-apis/) that can be incorporated into libraries and frameworks. For example, export or make available the initialized agent and create a new error boundary in your react application that calls `browserAgent.noticeError()`.
+
+### Server-Side Rendering
+
+A lot of new frameworks support the concept of server-side rendering the pages of an application to improve SEO and the performance of the user experience. The browser agent must be imported and instantiated within a browser context and will not work if executed on a server or in the server context of a server-side rendered application. These frameworks typically provide support for defining code that should only be run on the client. Check your frameworks documentation for more information.
+
 ## Disclaimers
 
 The session replay library shipping with this version of the browser agent is in *limited preview* and is not turned on by default. To use the feature, users will need to be part of the limited preview customer group and configure their browser application settings in the UI.
@@ -259,6 +267,6 @@ To all contributors, we thank you! Without your contribution, this project would
 
 ## License
 
-The Browser agent is licensed under the [Apache 2.0](http://apache.org/licenses/LICENSE-2.0.txt) License.
+The Browser agent is licensed under the [Apache 2.0](https://apache.org/licenses/LICENSE-2.0.txt) License.
 
 The Browser agent also uses source code from third-party libraries. Full details on which libraries are used and the terms under which they are licensed can be found in the [third-party notices document](THIRD_PARTY_NOTICES.md).

package/dist/cjs/common/config/state/info.js

@@ -46,5 +46,6 @@ function getInfo(id) {
 function setInfo(id, obj) {
   if (!id) throw new Error('All info objects require an agent identifier!');
   _cache[id] = (0, _configurable.getModeledObject)(obj, model);
-  (0, _nreum.gosNREUMInitializedAgents)(id, _cache[id], 'info');
+  const agentInst = (0, _nreum.getNREUMInitializedAgent)(id);
+  if (agentInst) agentInst.info = _cache[id];
 }

package/dist/cjs/common/config/state/init.js

@@ -173,7 +173,8 @@ function getConfiguration(id) {
 function setConfiguration(id, obj) {
   if (!id) throw new Error(missingAgentIdError);
   _cache[id] = (0, _configurable.getModeledObject)(obj, model());
-  (0, _nreum.gosNREUMInitializedAgents)(id, _cache[id], 'config');
+  const agentInst = (0, _nreum.getNREUMInitializedAgent)(id);
+  if (agentInst) agentInst.init = _cache[id];
 }
 function getConfigurationValue(id, path) {
   if (!id) throw new Error(missingAgentIdError);

package/dist/cjs/common/config/state/loader-config.js

@@ -24,5 +24,6 @@ function getLoaderConfig(id) {
 function setLoaderConfig(id, obj) {
   if (!id) throw new Error('All loader-config objects require an agent identifier!');
   _cache[id] = (0, _configurable.getModeledObject)(obj, model);
-  (0, _nreum.gosNREUMInitializedAgents)(id, _cache[id], 'loader_config');
+  const agentInst = (0, _nreum.getNREUMInitializedAgent)(id);
+  if (agentInst) agentInst.loader_config = _cache[id];
 }

package/dist/cjs/common/config/state/runtime.js

@@ -38,5 +38,6 @@ function getRuntime(id) {
 function setRuntime(id, obj) {
   if (!id) throw new Error('All runtime objects require an agent identifier!');
   _cache[id] = (0, _configurable.getModeledObject)(obj, model);
-  (0, _nreum.gosNREUMInitializedAgents)(id, _cache[id], 'runtime');
+  const agentInst = (0, _nreum.getNREUMInitializedAgent)(id);
+  if (agentInst) agentInst.runtime = _cache[id];
 }

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 = "1.246.1";
+const VERSION = "1.248.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 = "1.246.1";
+const VERSION = "1.248.0";
 
 /**
  * Exposes the build type of the agent

package/dist/cjs/common/constants/runtime.js

@@ -3,7 +3,7 @@
 Object.defineProperty(exports, "__esModule", {
   value: true
 });
-exports.supportsSendBeacon = exports.offset = exports.isiOS = exports.isWorkerScope = exports.isIE = exports.isBrowserScope = exports.initiallyHidden = exports.initialLocation = exports.iOSBelow16 = exports.globalScope = exports.ffVersion = void 0;
+exports.supportsSendBeacon = exports.offset = exports.loadedAsDeferredBrowserScript = exports.isiOS = exports.isWorkerScope = exports.isIE = exports.isBrowserScope = exports.initiallyHidden = exports.initialLocation = exports.iOSBelow16 = exports.globalScope = exports.ffVersion = void 0;
 /**
  * @file Contains constants about the environment the agent is running
  * within. These values are derived at the time the agent is first loaded.
@@ -24,6 +24,8 @@ const isWorkerScope = typeof WorkerGlobalScope !== 'undefined' && (typeof self !
 exports.isWorkerScope = isWorkerScope;
 const globalScope = isBrowserScope ? window : typeof WorkerGlobalScope !== 'undefined' && (typeof self !== 'undefined' && self instanceof WorkerGlobalScope && self || typeof globalThis !== 'undefined' && globalThis instanceof WorkerGlobalScope && globalThis);
 exports.globalScope = globalScope;
+const loadedAsDeferredBrowserScript = globalScope?.document?.readyState === 'complete';
+exports.loadedAsDeferredBrowserScript = loadedAsDeferredBrowserScript;
 const initiallyHidden = Boolean(globalScope?.document?.visibilityState === 'hidden');
 exports.initiallyHidden = initiallyHidden;
 const initialLocation = '' + globalScope?.location;

package/dist/cjs/common/dispatch/global-event.js

@@ -0,0 +1,19 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.dispatchGlobalEvent = dispatchGlobalEvent;
+var _runtime = require("../constants/runtime");
+const GLOBAL_EVENT_NAMESPACE = 'newrelic';
+function dispatchGlobalEvent() {
+  let detail = arguments.length > 0 && arguments[0] !== undefined ? arguments[0] : {};
+  try {
+    _runtime.globalScope.dispatchEvent(new CustomEvent(GLOBAL_EVENT_NAMESPACE, {
+      detail
+    }));
+  } catch (err) {
+    // something happened... dispatchEvent or CustomEvent might not be supported
+    // decide what to do about it here
+  }
+}

package/dist/cjs/common/session/session-entity.js

@@ -113,8 +113,8 @@ class SessionEntity {
       this.expiresTimer = new _timer.Timer({
         // When the inactive timer ends, collect a SM and reset the session
         onEnd: () => {
-          this.collectSM('expired', this);
-          this.collectSM('duration', this);
+          this.collectSM('expired');
+          this.collectSM('duration');
           this.reset();
         }
       }, this.state.expiresAt - Date.now());
@@ -130,8 +130,8 @@ class SessionEntity {
       this.inactiveTimer = new _interactionTimer.InteractionTimer({
         // When the inactive timer ends, collect a SM and reset the session
         onEnd: () => {
-          this.collectSM('inactive', this);
-          this.collectSM('duration', this);
+          this.collectSM('inactive');
+          this.collectSM('duration');
           this.reset();
         },
         // When the inactive timer refreshes, it will update the storage values with an update timestamp
@@ -181,14 +181,14 @@ class SessionEntity {
       if (this.isInvalid(obj)) return {};
       // if the session expires, collect a SM count before resetting
       if (this.isExpired(obj.expiresAt)) {
-        this.collectSM('expired', this);
+        this.collectSM('expired');
         this.collectSM('duration', obj, true);
         return this.reset();
       }
       // if "inactive" timer is expired at "read" time -- esp. initial read -- reset
       // collect a SM count before resetting
       if (this.isExpired(obj.inactiveAt)) {
-        this.collectSM('inactive', this);
+        this.collectSM('inactive');
         this.collectSM('duration', obj, true);
         return this.reset();
       }
@@ -279,15 +279,20 @@ class SessionEntity {
   collectSM(type, data, useUpdatedAt) {
     let value, tag;
     if (type === 'duration') {
-      const startingTimestamp = data.expiresAt - data.expiresMs;
-      const endingTimestamp = useUpdatedAt ? data.updatedAt : Date.now();
-      value = endingTimestamp - startingTimestamp;
+      value = this.getDuration(data, useUpdatedAt);
       tag = 'Session/Duration/Ms';
     }
     if (type === 'expired') tag = 'Session/Expired/Seen';
     if (type === 'inactive') tag = 'Session/Inactive/Seen';
     if (tag) (0, _handle.handle)(_constants2.SUPPORTABILITY_METRIC_CHANNEL, [tag, value], undefined, _features.FEATURE_NAMES.metrics, this.ee);
   }
+  getDuration() {
+    let data = arguments.length > 0 && arguments[0] !== undefined ? arguments[0] : this.state;
+    let useUpdatedAt = arguments.length > 1 ? arguments[1] : undefined;
+    const startingTimestamp = data.expiresAt - this.expiresMs;
+    const endingTimestamp = !useUpdatedAt ? data.updatedAt : Date.now();
+    return endingTimestamp - startingTimestamp;
+  }
 
   /**
    * @param {number} futureMs - The number of ms to use to generate a future timestamp

package/dist/cjs/common/util/feature-flags.js

@@ -8,6 +8,7 @@ exports.activatedFeatures = void 0;
 var _contextualEe = require("../event-emitter/contextual-ee");
 var _handle = require("../event-emitter/handle");
 var _features = require("../../loaders/features/features");
+var _globalEvent = require("../dispatch/global-event");
 /*
  * Copyright 2020 New Relic Corporation. All rights reserved.
  * SPDX-License-Identifier: Apache-2.0
@@ -26,18 +27,17 @@ const sentIds = new Set();
 function activateFeatures(flags, agentIdentifier) {
   const sharedEE = _contextualEe.ee.get(agentIdentifier);
   if (!(flags && typeof flags === 'object')) return;
-  if (!sentIds.has(agentIdentifier)) {
-    Object.entries(flags).forEach(_ref => {
-      let [flag, num] = _ref;
-      if (bucketMap[flag]) {
-        bucketMap[flag].forEach(feat => {
-          if (!num) (0, _handle.handle)('block-' + flag, [], undefined, feat, sharedEE);else (0, _handle.handle)('feat-' + flag, [], undefined, feat, sharedEE);
-          (0, _handle.handle)('rumresp-' + flag, [Boolean(num)], undefined, feat, sharedEE); // this is a duplicate of feat-/block- but makes awaiting for 1 event easier than 2
-        });
-      } else if (num) (0, _handle.handle)('feat-' + flag, [], undefined, undefined, sharedEE); // not sure what other flags are overlooked, but there's a test for ones not in the map --
-      activatedFeatures[flag] = Boolean(num);
-    });
-  }
+  if (sentIds.has(agentIdentifier)) return;
+  Object.entries(flags).forEach(_ref => {
+    let [flag, num] = _ref;
+    if (bucketMap[flag]) {
+      bucketMap[flag].forEach(feat => {
+        if (!num) (0, _handle.handle)('block-' + flag, [], undefined, feat, sharedEE);else (0, _handle.handle)('feat-' + flag, [], undefined, feat, sharedEE);
+        (0, _handle.handle)('rumresp-' + flag, [Boolean(num)], undefined, feat, sharedEE); // this is a duplicate of feat-/block- but makes awaiting for 1 event easier than 2
+      });
+    } else if (num) (0, _handle.handle)('feat-' + flag, [], undefined, undefined, sharedEE); // not sure what other flags are overlooked, but there's a test for ones not in the map --
+    activatedFeatures[flag] = Boolean(num);
+  });
 
   // Let the features waiting on their respective flags know that RUM response was received and that any missing flags are interpreted as bad entitlement / "off".
   // Hence, those features will not be hanging forever if their flags aren't included in the response.
@@ -48,6 +48,11 @@ function activateFeatures(flags, agentIdentifier) {
     }
   });
   sentIds.add(agentIdentifier);
+
+  // let any window level subscribers know that the agent is running
+  (0, _globalEvent.dispatchGlobalEvent)({
+    loaded: true
+  });
 }
 const activatedFeatures = {};
 exports.activatedFeatures = activatedFeatures;

package/dist/cjs/common/window/load.js

@@ -3,6 +3,7 @@
 Object.defineProperty(exports, "__esModule", {
   value: true
 });
+exports.checkState = checkState;
 exports.onDOMContentLoaded = onDOMContentLoaded;
 exports.onWindowLoad = onWindowLoad;
 var _eventListenerOpts = require("../event-listener/event-listener-opts");

package/dist/cjs/common/window/nreum.js

@@ -6,13 +6,14 @@ Object.defineProperty(exports, "__esModule", {
 exports.NREUMinitialized = NREUMinitialized;
 exports.addToNREUM = addToNREUM;
 exports.defaults = void 0;
+exports.getNREUMInitializedAgent = getNREUMInitializedAgent;
 exports.gosCDN = gosCDN;
 exports.gosNREUM = gosNREUM;
 exports.gosNREUMInfo = gosNREUMInfo;
 exports.gosNREUMInit = gosNREUMInit;
-exports.gosNREUMInitializedAgents = gosNREUMInitializedAgents;
 exports.gosNREUMLoaderConfig = gosNREUMLoaderConfig;
 exports.gosNREUMOriginals = gosNREUMOriginals;
+exports.setNREUMInitializedAgent = setNREUMInitializedAgent;
 var _now = require("../timing/now");
 var _runtime = require("../constants/runtime");
 const defaults = {
@@ -71,24 +72,24 @@ function gosNREUMOriginals() {
   }
   return nr;
 }
-function gosNREUMInitializedAgents(id, obj, target) {
+function setNREUMInitializedAgent(id, newAgentInstance) {
   let nr = gosNREUM();
-  const externallySupplied = nr.initializedAgents || {};
-  const curr = externallySupplied[id] || {};
-  if (!Object.keys(curr).length) {
-    curr.initializedAt = {
-      ms: (0, _now.now)(),
-      date: new Date()
-    };
-  }
-  nr.initializedAgents = {
-    ...externallySupplied,
-    [id]: {
-      ...curr,
-      [target]: obj
-    }
+  nr.initializedAgents ??= {};
+  newAgentInstance.initializedAt = {
+    ms: (0, _now.now)(),
+    date: new Date()
   };
-  return nr;
+  nr.initializedAgents[id] = newAgentInstance;
+}
+
+/**
+ * Get the agent instance under the associated identifier on the global newrelic object.
+ * @see setNREUMInitializedAgents
+ * @returns Existing agent instance under newrelic.initializedAgent[id], or undefined if it does not exist.
+ */
+function getNREUMInitializedAgent(id) {
+  let nr = gosNREUM();
+  return nr.initializedAgents?.[id];
 }
 function addToNREUM(fnName, fn) {
   let nr = gosNREUM();

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

@@ -69,10 +69,12 @@ class Aggregate extends _aggregateBase.AggregateBase {
     } = (0, _config.getRuntime)(this.agentIdentifier);
     if (loaderType) this.storeSupportabilityMetrics("Generic/LoaderType/".concat(loaderType, "/Detected"));
     if (distMethod) this.storeSupportabilityMetrics("Generic/DistMethod/".concat(distMethod, "/Detected"));
-
-    // frameworks on page
     if (_runtime.isBrowserScope) {
       this.storeSupportabilityMetrics('Generic/Runtime/Browser/Detected');
+      const nonce = document?.currentScript?.nonce;
+      if (nonce && nonce !== '') {
+        this.storeSupportabilityMetrics('Generic/Runtime/Nonce/Detected');
+      }
 
       // These SMs are used by the AppExp team
       (0, _load.onDOMContentLoaded)(() => {

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

@@ -19,6 +19,7 @@ var _constants2 = require("../../metrics/constants");
 var _handle = require("../../../common/event-emitter/handle");
 var _features = require("../../../loaders/features/features");
 var _env = require("../../../common/constants/env.npm");
+var _now = require("../../../common/timing/now");
 function _getRequireWildcardCache(nodeInterop) { if (typeof WeakMap !== "function") return null; var cacheBabelInterop = new WeakMap(); var cacheNodeInterop = new WeakMap(); return (_getRequireWildcardCache = function (nodeInterop) { return nodeInterop ? cacheNodeInterop : cacheBabelInterop; })(nodeInterop); }
 function _interopRequireWildcard(obj, nodeInterop) { if (!nodeInterop && obj && obj.__esModule) { return obj; } if (obj === null || typeof obj !== "object" && typeof obj !== "function") { return { default: obj }; } var cache = _getRequireWildcardCache(nodeInterop); if (cache && cache.has(obj)) { return cache.get(obj); } var newObj = {}; var hasPropertyDescriptor = Object.defineProperty && Object.getOwnPropertyDescriptor; for (var key in obj) { if (key !== "default" && Object.prototype.hasOwnProperty.call(obj, key)) { var desc = hasPropertyDescriptor ? Object.getOwnPropertyDescriptor(obj, key) : null; if (desc && (desc.get || desc.set)) { Object.defineProperty(newObj, key, desc); } else { newObj[key] = obj[key]; } } } newObj.default = obj; if (cache) { cache.set(obj, newObj); } return newObj; } /*
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       * Copyright 2023 New Relic Corporation. All rights reserved.
@@ -70,8 +71,10 @@ const MAX_PAYLOAD_SIZE = 1000000;
 /** Unloading caps around 64kb */
 exports.MAX_PAYLOAD_SIZE = MAX_PAYLOAD_SIZE;
 const IDEAL_PAYLOAD_SIZE = 64000;
-/** Interval between forcing new full snapshots -- 15 seconds in error mode (x2), 5 minutes in full mode */
+/** Reserved room for query param attrs */
 exports.IDEAL_PAYLOAD_SIZE = IDEAL_PAYLOAD_SIZE;
+const QUERY_PARAM_PADDING = 5000;
+/** Interval between forcing new full snapshots -- 15 seconds in error mode (x2), 5 minutes in full mode */
 const CHECKOUT_MS = {
   [_sessionEntity.MODE.ERROR]: 15000,
   [_sessionEntity.MODE.FULL]: 300000,
@@ -120,6 +123,9 @@ class Aggregate extends _aggregateBase.AggregateBase {
 
     /** Hold on to the last meta node, so that it can be re-inserted if the meta and snapshot nodes are broken up due to harvesting */
     this.lastMeta = undefined;
+
+    /** set by BCS response */
+    this.entitled = false;
     const shouldSetup = (0, _config.getConfigurationValue)(agentIdentifier, 'privacy.cookies_enabled') === true && (0, _config.getConfigurationValue)(agentIdentifier, 'session_trace.enabled') === true;
 
     /** The method to stop recording. This defaults to a noop, but is overwritten once the recording library is imported and initialized */
@@ -157,6 +163,18 @@ class Aggregate extends _aggregateBase.AggregateBase {
         getPayload: this.prepareHarvest.bind(this),
         raw: true
       }, this);
+      (0, _registerHandler.registerHandler)('recordReplay', () => {
+        // if it has aborted or BCS returned bad entitlements, do not allow
+        if (this.blocked || !this.entitled) return;
+        // if it isnt already (fully) initialized... initialize it
+        if (!recorder) this.initializeRecording(false, true, true);
+        // its been initialized and imported the recorder but its not recording (mode === off || error)
+        else if (this.mode !== _sessionEntity.MODE.FULL) this.switchToFull();
+        // if it gets all the way to here, that means a full session is already recording... do nothing
+      }, this.featureName, this.ee);
+      (0, _registerHandler.registerHandler)('pauseReplay', () => {
+        this.forceStop(this.mode !== _sessionEntity.MODE.ERROR);
+      }, this.featureName, this.ee);
 
       // Wait for an error to be reported.  This currently is wrapped around the "Error" feature.  This is a feature-feature dependency.
       // This was to ensure that all errors, including those on the page before load and those handled with "noticeError" are accounted for. Needs evalulation
@@ -165,37 +183,42 @@ class Aggregate extends _aggregateBase.AggregateBase {
         this.errorNoticed = true;
         // run once
         if (this.mode === _sessionEntity.MODE.ERROR && _runtime.globalScope?.document.visibilityState === 'visible') {
-          this.mode = _sessionEntity.MODE.FULL;
-          // if the error was noticed AFTER the recorder was already imported....
-          if (recorder && this.initialized) {
-            this.stopRecording();
-            this.startRecording();
-            this.scheduler.startTimer(this.harvestTimeSeconds);
-            this.syncWithSessionManager({
-              sessionReplayMode: this.mode
-            });
-          }
+          this.switchToFull();
         }
       }, this.featureName, this.ee);
       this.waitForFlags(['sr']).then(_ref => {
         let [flagOn] = _ref;
-        return this.initializeRecording(flagOn, Math.random() * 100 < (0, _config.getConfigurationValue)(this.agentIdentifier, 'session_replay.error_sampling_rate'), Math.random() * 100 < (0, _config.getConfigurationValue)(this.agentIdentifier, 'session_replay.sampling_rate'));
+        this.entitled = flagOn;
+        this.initializeRecording(Math.random() * 100 < (0, _config.getConfigurationValue)(this.agentIdentifier, 'session_replay.error_sampling_rate'), Math.random() * 100 < (0, _config.getConfigurationValue)(this.agentIdentifier, 'session_replay.sampling_rate'));
       }).then(() => _sharedChannel.sharedChannel.onReplayReady(this.mode)); // notify watchers that replay started with the mode
 
       this.drain();
     }
   }
+  switchToFull() {
+    this.mode = _sessionEntity.MODE.FULL;
+    // if the error was noticed AFTER the recorder was already imported....
+    if (recorder && this.initialized) {
+      this.stopRecording();
+      this.startRecording();
+      this.scheduler.startTimer(this.harvestTimeSeconds);
+      this.syncWithSessionManager({
+        sessionReplayMode: this.mode
+      });
+    }
+  }
 
   /**
    * Evaluate entitlements and sampling before starting feature mechanics, importing and configuring recording library, and setting storage state
    * @param {boolean} entitlements - the true/false state of the "sr" flag from RUM response
    * @param {boolean} errorSample - the true/false state of the error sampling decision
    * @param {boolean} fullSample - the true/false state of the full sampling decision
+   * @param {boolean} ignoreSession - whether to force the method to ignore the session state and use just the sample flags
    * @returns {void}
    */
-  async initializeRecording(entitlements, errorSample, fullSample) {
+  async initializeRecording(errorSample, fullSample, ignoreSession) {
     this.initialized = true;
-    if (!entitlements) return;
+    if (!this.entitled || this.recording) return;
     const {
       session
     } = (0, _config.getRuntime)(this.agentIdentifier);
@@ -205,7 +228,7 @@ class Aggregate extends _aggregateBase.AggregateBase {
     // we are not actively recording SR... DO NOT import or run the recording library
     // session replay samples can only be decided on the first load of a session
     // session replays can continue if already in progress
-    if (!session.isNew) {
+    if (!session.isNew && !ignoreSession) {
       // inherit the mode of the existing session
       this.mode = session.state.sessionReplayMode;
     } else {
@@ -277,6 +300,7 @@ class Aggregate extends _aggregateBase.AggregateBase {
   getHarvestContents() {
     const agentRuntime = (0, _config.getRuntime)(this.agentIdentifier);
     const info = (0, _config.getInfo)(this.agentIdentifier);
+    const endUserId = info.jsAttributes?.['enduser.id'];
     if (this.backloggedEvents.length) this.events = [...this.backloggedEvents, ...this.events];
 
     // do not let the first node be a full snapshot node, since this NEEDS to be preceded by a meta node
@@ -296,10 +320,12 @@ class Aggregate extends _aggregateBase.AggregateBase {
       this.events = this.events.slice(0, this.events.length - 1);
       this.hasMeta = !!this.events.find(x => x.type === RRWEB_EVENT_TYPES.Meta);
     }
+    const agentOffset = (0, _config.getRuntime)(this.agentIdentifier).offset;
+    const relativeNow = (0, _now.now)();
     const firstEventTimestamp = this.events[0]?.timestamp; // from rrweb node
     const lastEventTimestamp = this.events[this.events.length - 1]?.timestamp; // from rrweb node
     const firstTimestamp = firstEventTimestamp || this.cycleTimestamp;
-    const lastTimestamp = lastEventTimestamp || (0, _config.getRuntime)(this.agentIdentifier).offset + _runtime.globalScope.performance.now();
+    const lastTimestamp = lastEventTimestamp || agentOffset + relativeNow;
     return {
       qs: {
         browser_monitoring_key: info.licenseKey,
@@ -307,22 +333,32 @@ class Aggregate extends _aggregateBase.AggregateBase {
         app_id: info.applicationID,
         protocol_version: '0',
         attributes: (0, _encode.obj)({
+          // this section of attributes must be controllable and stay below the query param padding limit -- see QUERY_PARAM_PADDING
+          // if not, data could be lost to truncation at time of sending, potentially breaking parsing / API behavior in NR1
           ...(this.shouldCompress && {
             content_encoding: 'gzip'
           }),
           'replay.firstTimestamp': firstTimestamp,
+          'replay.firstTimestampOffset': firstTimestamp - agentOffset,
           'replay.lastTimestamp': lastTimestamp,
           'replay.durationMs': lastTimestamp - firstTimestamp,
           'replay.nodes': this.events.length,
+          'session.durationMs': agentRuntime.session.getDuration(),
           agentVersion: agentRuntime.version,
           session: agentRuntime.session.state.value,
+          rst: relativeNow,
           hasMeta: this.hasMeta,
           hasSnapshot: this.hasSnapshot,
           hasError: this.hasError,
           isFirstChunk: agentRuntime.session.state.sessionReplaySentFirstChunk === false,
           decompressedBytes: this.payloadBytesEstimation,
-          'nr.rrweb.version': _env.RRWEB_VERSION
-        }, MAX_PAYLOAD_SIZE - this.payloadBytesEstimation).substring(1) // remove the leading '&'
+          'rrweb.version': _env.RRWEB_VERSION,
+          // customer-defined data should go last so that if it exceeds the query param padding limit it will be truncated instead of important attrs
+          ...(endUserId && {
+            'enduser.id': endUserId
+          })
+          // The Query Param is being arbitrarily limited in length here.  It is also applied when estimating the size of the payload in getPayloadSize()
+        }, QUERY_PARAM_PADDING).substring(1) // remove the leading '&'
       },
 
       body: this.events
@@ -444,8 +480,22 @@ class Aggregate extends _aggregateBase.AggregateBase {
   /** Estimate the payload size */
   getPayloadSize() {
     let newBytes = arguments.length > 0 && arguments[0] !== undefined ? arguments[0] : 0;
-    // the 1KB gives us some padding for the other metadata
-    return this.estimateCompression(this.payloadBytesEstimation + newBytes) + 1000;
+    // the query param padding constant gives us some padding for the other metadata to be safely injected
+    return this.estimateCompression(this.payloadBytesEstimation + newBytes) + QUERY_PARAM_PADDING;
+  }
+
+  /**
+   * Forces the agent into OFF mode so that changing tabs or navigating
+   * does not restart the recording. This is used when the customer calls
+   * the stopRecording API.
+   */
+  forceStop(forceHarvest) {
+    if (forceHarvest) this.scheduler.runHarvest();
+    this.mode = _sessionEntity.MODE.OFF;
+    this.stopRecording();
+    this.syncWithSessionManager({
+      sessionReplayMode: this.mode
+    });
   }
 
   /** Abort the feature, once aborted it will not resume */

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

@@ -89,30 +89,45 @@ class Aggregate extends _aggregateBase.AggregateBase {
           break;
       }
     };
+    let seenAnError = false;
+    let mostRecentModeKnown;
+    this.ee.on(_sessionEntity.SESSION_EVENTS.UPDATE, (eventType, sessionState) => {
+      // this will only have an effect if ST is NOT already in full mode
+      if (sessionState.sessionReplayMode === _sessionEntity.MODE.FULL) switchToFull();
+    });
+
+    /**
+     * The goal of switchToFull is to take external input to trigger a change from off or error to full.
+     * It will have no effect if already running in full mode.
+     * "external" input in this case means errors thrown on the page or session replay itself being triggered to run in full mode by the API, which updates the session entity.
+     */
+    const switchToFull = () => {
+      if (this.agentRuntime?.session?.state?.sessionReplayMode !== _sessionEntity.MODE.FULL) return;
+      if (mostRecentModeKnown !== _sessionEntity.MODE.FULL) {
+        const prevMode = mostRecentModeKnown;
+        mostRecentModeKnown = _sessionEntity.MODE.FULL;
+        sessionEntity.write({
+          sessionTraceMode: mostRecentModeKnown
+        });
+        this.isStandalone = false;
+        if (prevMode === _sessionEntity.MODE.ERROR && this.#scheduler) {
+          this.trimSTNs(ERROR_MODE_SECONDS_WINDOW); // up until now, Trace would've been just buffering nodes up to max, which needs to be trimmed to last X seconds
+          this.#scheduler.runHarvest({
+            needResponse: true
+          });
+        } else {
+          controlTraceOp(_sessionEntity.MODE.FULL);
+        }
+      }
+    };
     if (!sessionEntity) {
       // Since session manager isn't around, do the old Trace behavior of waiting for RUM response to decide feature activation.
       this.isStandalone = true;
       (0, _registerHandler.registerHandler)('rumresp-stn', on => controlTraceOp(on), this.featureName, this.ee);
     } else {
-      let seenAnError = false;
-      let mostRecentModeKnown;
       (0, _registerHandler.registerHandler)('errorAgg', () => {
-        // Switch to full capture mode on next harvest on first exception thrown only. Only done once so that sessionTraceMode isn't constantly overwritten after decision block.
-        if (!seenAnError) {
-          seenAnError = true;
-          /* If this cb executes before Trace has started, then no further action needed. But if...
-           - startTracing already ran under ERROR mode, then it will NOT have kicked off the harvest-scheduler so that needs to be done & switch mode.
-           - startTracing never ran because mode is OFF or Replay aborted or Traced turned off elsewhere OR trace already in FULL, then this should do nothing. */
-          if (sessionEntity.state.sessionTraceMode === _sessionEntity.MODE.ERROR && this.#scheduler) {
-            sessionEntity.write({
-              sessionTraceMode: mostRecentModeKnown = _sessionEntity.MODE.FULL
-            });
-            this.trimSTNs(ERROR_MODE_SECONDS_WINDOW); // up until now, Trace would've been just buffering nodes up to max, which needs to be trimmed to last X seconds
-            this.#scheduler.runHarvest({
-              needResponse: true
-            });
-          }
-        }
+        seenAnError = true;
+        switchToFull();
       }, this.featureName, this.ee);
       const stopTracePerm = () => {
         if (sessionEntity.state.sessionTraceMode !== _sessionEntity.MODE.OFF) sessionEntity.write({