@newrelic/browser-agent 1.302.0 → 1.303.0-rc.1

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

@@ -17,14 +17,19 @@ import { timeToFirstByte } from '../../../common/vitals/time-to-first-byte';
 import { now } from '../../../common/timing/now';
 import { TimeKeeper } from '../../../common/timing/time-keeper';
 import { applyFnToProps } from '../../../common/util/traverse';
+import { send } from '../../../common/harvest/harvester';
+import { FEATURE_NAMES, FEATURE_TO_ENDPOINT } from '../../../loaders/features/features';
+import { getSubmitMethod } from '../../../common/util/submit-data';
 export class Aggregate extends AggregateBase {
   static featureName = CONSTANTS.FEATURE_NAME;
   constructor(agentRef) {
     super(agentRef, CONSTANTS.FEATURE_NAME);
+    this.sentRum = false; // flag to facilitate calling sendRum() once externally (by the consent API in agent-session.js)
+
     this.timeToFirstByte = 0;
     this.firstByteToWindowLoad = 0; // our "frontend" duration
     this.firstByteToDomContent = 0; // our "dom processing" duration
-
+    this.retries = 0;
     if (!isValid(agentRef.info)) {
       this.ee.abort();
       return warn(43);
@@ -52,12 +57,8 @@ export class Aggregate extends AggregateBase {
    *
    * @param {Function} cb A function to run once the RUM call has finished - Defaults to activateFeatures
    * @param {*} customAttributes custom attributes to attach to the RUM call - Defaults to info.js
-   * @param {*} target The target to harvest to
    */
-  sendRum(customAttributes = this.agentRef.info.jsAttributes, target = {
-    licenseKey: this.agentRef.info.licenseKey,
-    applicationID: this.agentRef.info.applicationID
-  }) {
+  sendRum(customAttributes = this.agentRef.info.jsAttributes) {
     const info = this.agentRef.info;
     const measures = {};
     if (info.queueTime) measures.qt = info.queueTime;
@@ -108,27 +109,30 @@ export class Aggregate extends AggregateBase {
     }
     queryParameters.fp = firstPaint.current.value;
     queryParameters.fcp = firstContentfulPaint.current.value;
-    const timeKeeper = this.agentRef.runtime.timeKeeper;
-    if (timeKeeper?.ready) {
-      queryParameters.timestamp = Math.floor(timeKeeper.correctRelativeTimestamp(now()));
-    }
-    this.rumStartTime = now();
-    this.agentRef.runtime.harvester.triggerHarvestFor(this, {
-      directSend: {
-        target,
-        payload: {
-          qs: queryParameters,
-          body
-        }
-      },
-      needResponse: true,
+    this.queryStringsBuilder = () => {
+      // this will be called by AggregateBase.makeHarvestPayload every time harvest is triggered to be qs
+      this.rumStartTime = now(); // this should be reset at the beginning of each RUM call for proper timeKeeper calculation in coordination with postHarvestCleanup
+      const timeKeeper = this.agentRef.runtime.timeKeeper;
+      if (timeKeeper?.ready) {
+        queryParameters.timestamp = Math.floor(timeKeeper.correctRelativeTimestamp(this.rumStartTime));
+      }
+      return queryParameters;
+    };
+    this.events.add(body);
+    if (this.agentRef.runtime.harvester.triggerHarvestFor(this, {
       sendEmptyBody: true
-    });
+    }).ranSend) this.sentRum = true;
+  }
+  serializer(eventBuffer) {
+    // this is necessary because PVE sends a single item rather than an array; in the case of undefined, this prevents sending [null] as body
+    return eventBuffer[0];
   }
   postHarvestCleanup({
+    sent,
     status,
     responseText,
-    xhr
+    xhr,
+    retry
   }) {
     const rumEndTime = now();
     let app, flags;
@@ -141,8 +145,65 @@ export class Aggregate extends AggregateBase {
       // wont set entity stuff here, if main agent will later abort, if registered agent, nothing will happen
       warn(53, error);
     }
+    super.postHarvestCleanup({
+      sent,
+      retry
+    }); // this will set isRetrying & re-buffer the body if request is to be retried
+    if (this.isRetrying && this.retries++ < 1) {
+      // Only retry once
+      setTimeout(() => this.agentRef.runtime.harvester.triggerHarvestFor(this, {
+        sendEmptyBody: true
+      }), 5000); // Retry sending the RUM event after 5 seconds
+      return;
+    }
     if (status >= 400 || status === 0) {
       warn(18, status);
+      this.blocked = true;
+
+      // Get estimated payload size of our backlog
+      const textEncoder = new TextEncoder();
+      const payloadSize = Object.values(newrelic.ee.backlog).reduce((acc, value) => {
+        if (!value) return acc;
+        const encoded = textEncoder.encode(value);
+        return acc + encoded.byteLength;
+      }, 0);
+
+      // Send SMs about failed RUM request
+      const body = {
+        sm: [{
+          params: {
+            name: "Browser/Supportability/BCS/Error/".concat(status)
+          },
+          stats: {
+            c: 1
+          }
+        }, {
+          params: {
+            name: 'Browser/Supportability/BCS/Error/Dropped/Bytes'
+          },
+          stats: {
+            c: 1,
+            t: payloadSize
+          }
+        }, {
+          params: {
+            name: 'Browser/Supportability/BCS/Error/Duration/Ms'
+          },
+          stats: {
+            c: 1,
+            t: rumEndTime - this.rumStartTime
+          }
+        }]
+      };
+      send(this.agentRef, {
+        endpoint: FEATURE_TO_ENDPOINT[FEATURE_NAMES.metrics],
+        payload: {
+          body
+        },
+        submitMethod: getSubmitMethod(),
+        featureName: FEATURE_NAMES.metrics
+      });
+
       // Adding retry logic for the rum call will be a separate change; this.blocked will need to be changed since that prevents another triggerHarvestFor()
       this.ee.abort();
       return;
@@ -161,6 +222,7 @@ export class Aggregate extends AggregateBase {
       }
     } catch (error) {
       this.ee.abort();
+      this.blocked = true;
       warn(17, error);
       return;
     }

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

@@ -2,7 +2,6 @@
  * Copyright 2020-2025 New Relic, Inc. All rights reserved.
  * SPDX-License-Identifier: Apache-2.0
  */
-import { handle } from '../../../common/event-emitter/handle';
 import { setupSetPageViewNameAPI } from '../../../loaders/api/setPageViewName';
 import { InstrumentBase } from '../../utils/instrument-base';
 import * as CONSTANTS from '../constants';
@@ -19,9 +18,6 @@ export class Instrument extends InstrumentBase {
 
     /** feature specific APIs */
     setupSetPageViewNameAPI(agentRef);
-
-    /** messages from the register API that can trigger a new RUM call */
-    this.ee.on('api-send-rum', (attrs, target) => handle('send-rum', [attrs, target], undefined, this.featureName, this.ee));
     this.importAggregator(agentRef, () => import(/* webpackChunkName: "page_view_event-aggregate" */'../aggregate'));
   }
   setupInspectionEvents(agentIdentifier) {

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

@@ -7,7 +7,7 @@
  */
 
 import { registerHandler } from '../../../common/event-emitter/register-handler';
-import { ABORT_REASONS, FEATURE_NAME, QUERY_PARAM_PADDING, RRWEB_EVENT_TYPES, SR_EVENT_EMITTER_TYPES, TRIGGERS } from '../constants';
+import { ABORT_REASONS, ERROR_DURING_REPLAY, FEATURE_NAME, QUERY_PARAM_PADDING, RRWEB_EVENT_TYPES, TRIGGERS } from '../constants';
 import { AggregateBase } from '../../utils/aggregate-base';
 import { sharedChannel } from '../../../common/constants/shared-channel';
 import { obj as encodeObj } from '../../../common/url/encode';
@@ -21,6 +21,7 @@ import { now } from '../../../common/timing/now';
 import { MAX_PAYLOAD_SIZE } from '../../../common/constants/agent-constants';
 import { cleanURL } from '../../../common/url/clean-url';
 import { canEnableSessionTracking } from '../../utils/feature-gates';
+import { PAUSE_REPLAY } from '../../../loaders/api/constants';
 export class Aggregate extends AggregateBase {
   static featureName = FEATURE_NAME;
   mode = MODE.OFF;
@@ -72,10 +73,10 @@ export class Aggregate extends AggregateBase {
       if (this.mode !== MODE.OFF && data.sessionReplayMode === MODE.OFF) this.abort(ABORT_REASONS.CROSS_TAB);
       this.mode = data.sessionReplayMode;
     });
-    registerHandler(SR_EVENT_EMITTER_TYPES.PAUSE, () => {
+    registerHandler(PAUSE_REPLAY, () => {
       this.forceStop(this.mode === MODE.FULL);
     }, this.featureName, this.ee);
-    registerHandler(SR_EVENT_EMITTER_TYPES.ERROR_DURING_REPLAY, e => {
+    registerHandler(ERROR_DURING_REPLAY, e => {
       this.handleError(e);
     }, this.featureName, this.ee);
     const {

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

@@ -5,11 +5,7 @@
 import { MODE } from '../../common/session/constants';
 import { FEATURE_NAMES } from '../../loaders/features/features';
 export const FEATURE_NAME = FEATURE_NAMES.sessionReplay;
-export const SR_EVENT_EMITTER_TYPES = {
-  RECORD: 'recordReplay',
-  PAUSE: 'pauseReplay',
-  ERROR_DURING_REPLAY: 'errorDuringReplay'
-};
+export const ERROR_DURING_REPLAY = 'errorDuringReplay';
 export const AVG_COMPRESSION = 0.12;
 export const RRWEB_EVENT_TYPES = {
   DomContentLoaded: 0,

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

@@ -10,9 +10,10 @@ import { handle } from '../../../common/event-emitter/handle';
 import { DEFAULT_KEY, MODE, PREFIX } from '../../../common/session/constants';
 import { InstrumentBase } from '../../utils/instrument-base';
 import { hasReplayPrerequisite, isPreloadAllowed } from '../shared/utils';
-import { FEATURE_NAME, SR_EVENT_EMITTER_TYPES, TRIGGERS } from '../constants';
+import { ERROR_DURING_REPLAY, FEATURE_NAME, TRIGGERS } from '../constants';
 import { setupRecordReplayAPI } from '../../../loaders/api/recordReplay';
 import { setupPauseReplayAPI } from '../../../loaders/api/pauseReplay';
+import { RECORD_REPLAY } from '../../../loaders/api/constants';
 export class Instrument extends InstrumentBase {
   static featureName = FEATURE_NAME;
   /** @type {Promise|undefined} A promise that resolves when the recorder module is imported and added to the class. Undefined if the recorder has never been staged to import with `importRecorder`. */
@@ -30,7 +31,7 @@ export class Instrument extends InstrumentBase {
       session = JSON.parse(localStorage.getItem("".concat(PREFIX, "_").concat(DEFAULT_KEY)));
     } catch (err) {}
     if (hasReplayPrerequisite(agentRef.init)) {
-      this.ee.on(SR_EVENT_EMITTER_TYPES.RECORD, () => this.#apiStartOrRestartReplay());
+      this.ee.on(RECORD_REPLAY, () => this.#apiStartOrRestartReplay());
     }
     if (this.#canPreloadRecorder(session)) {
       this.importRecorder().then(recorder => {
@@ -44,7 +45,7 @@ export class Instrument extends InstrumentBase {
       if (this.blocked) return;
       if (this.agentRef.runtime.isRecording) {
         this.errorNoticed = true;
-        handle(SR_EVENT_EMITTER_TYPES.ERROR_DURING_REPLAY, [e], undefined, this.featureName, this.ee);
+        handle(ERROR_DURING_REPLAY, [e], undefined, this.featureName, this.ee);
       }
     });
   }

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

@@ -52,6 +52,11 @@ export function setupAgentSession(agentRef) {
   registerHandler('api-setUserId', (time, key, value) => {
     agentRef.runtime.session.syncCustomAttribute(key, value);
   }, 'session', sharedEE);
+  registerHandler('api-consent', accept => {
+    agentRef.runtime.session.write({
+      consent: accept === undefined ? true : accept
+    });
+  }, 'session', sharedEE);
   drain(agentRef.agentIdentifier, 'session');
   return agentRef.runtime.session;
 }

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

@@ -48,7 +48,10 @@ export class InstrumentBase extends FeatureBase {
      * @type {Promise} Assigned immediately after @see importAggregator runs. Serves as a signal for when the inner async fn finishes execution. Useful for features to await
      * one another if there are inter-features dependencies.
     */
-    this.onAggregateImported = undefined;
+    this.loadedSuccessfully = undefined;
+    this.onAggregateImported = new Promise(resolve => {
+      this.loadedSuccessfully = resolve;
+    });
 
     /**
      * used in conjunction with newrelic.start() to defer harvesting in features
@@ -80,10 +83,6 @@ export class InstrumentBase extends FeatureBase {
    */
   importAggregator(agentRef, fetchAggregator, argsObjFromInstrument = {}) {
     if (this.featAggregate) return;
-    let loadedSuccessfully;
-    this.onAggregateImported = new Promise(resolve => {
-      loadedSuccessfully = resolve;
-    });
     const importLater = async () => {
       // wait for the deferred promise to resolve before proceeding
       // this will resolve immediately if the feature is auto-started,
@@ -111,7 +110,7 @@ export class InstrumentBase extends FeatureBase {
       try {
         if (!this.#shouldImportAgg(this.featureName, session, agentRef.init)) {
           drain(this.agentIdentifier, this.featureName);
-          loadedSuccessfully(false); // aggregate module isn't loaded at all
+          this.loadedSuccessfully(false); // aggregate module isn't loaded at all
           return;
         }
         const {
@@ -119,13 +118,13 @@ export class InstrumentBase extends FeatureBase {
         } = await fetchAggregator();
         this.featAggregate = new Aggregate(agentRef, argsObjFromInstrument);
         agentRef.runtime.harvester.initializedAggregates.push(this.featAggregate); // "subscribe" the feature to future harvest intervals (PVE will start the timer)
-        loadedSuccessfully(true);
+        this.loadedSuccessfully(true);
       } catch (e) {
         warn(34, e);
         this.abortHandler?.(); // undo any important alterations made to the page
         // not supported yet but nice to do: "abort" this agent's EE for this feature specifically
         drain(this.agentIdentifier, this.featureName, true);
-        loadedSuccessfully(false);
+        this.loadedSuccessfully(false);
         if (this.ee) this.ee.abort();
       }
     };

package/dist/esm/interfaces/registered-entity.js

@@ -48,6 +48,27 @@ export class RegisteredEntity {
     warn(35, 'addPageAction');
   }
 
+  /**
+     * Records a custom event with a specified eventType and attributes.
+     * {@link https://docs.newrelic.com/docs/browser/new-relic-browser/browser-apis/recordCustomEvent/}
+     * @param {string} eventType The eventType to store the event as.
+     * @param {Object} [attributes] JSON object with one or more key/value pairs. For example: {key:"value"}.
+     */
+  recordCustomEvent(eventType, attributes) {
+    warn(35, 'recordCustomEvent');
+  }
+
+  /**
+   * Measures a task that is recorded as a BrowserPerformance event.
+   * {@link https://docs.newrelic.com/docs/browser/new-relic-browser/browser-apis/measure/}
+   * @param {string} name The name of the task
+   * @param {{start: number, end: number, duration: number, customAttributes: object}} [options] An object used to control the way the measure API operates
+   * @returns {{start: number, end: number, duration: number, customAttributes: object}} Measurement details
+   */
+  measure(name, options) {
+    warn(35, 'measure');
+  }
+
   /**
    * Adds a user-defined attribute name and value to subsequent events on the page for the registered target. Note -- the persist flag does not work with the register API.
    * {@link https://docs.newrelic.com/docs/browser/new-relic-browser/browser-apis/setcustomattribute/}

package/dist/esm/loaders/agent.js

@@ -23,6 +23,7 @@ import { setupSetCustomAttributeAPI } from './api/setCustomAttribute';
 import { setupSetUserIdAPI } from './api/setUserId';
 import { setupSetApplicationVersionAPI } from './api/setApplicationVersion';
 import { setupStartAPI } from './api/start';
+import { setupConsentAPI } from './api/consent';
 
 /**
  * @typedef {Object} AgentOptions
@@ -67,6 +68,7 @@ export class Agent extends AgentBase {
     setupSetUserIdAPI(this);
     setupSetApplicationVersionAPI(this);
     setupStartAPI(this);
+    setupConsentAPI(this);
     this.run();
   }
   get config() {

package/dist/esm/loaders/api/consent.js

@@ -0,0 +1,30 @@
+/**
+ * Copyright 2020-2025 New Relic, Inc. All rights reserved.
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { prefix, CONSENT } from './constants';
+import { setupAPI } from './sharedHandlers';
+import { handle } from '../../common/event-emitter/handle';
+import { warn } from '../../common/util/console';
+export function setupConsentAPI(agent) {
+  setupAPI(CONSENT, function (accept = true) {
+    if (typeof accept !== 'boolean') {
+      warn(65, typeof accept);
+      return;
+    }
+    /** harvester, by way of "consented" getter, checks session state first, and falls back on runtime state if not available. Set both here */
+    handle(prefix + CONSENT, [accept], undefined, 'session', agent.ee); // sets session state (if available)
+    agent.runtime.consented = accept; // sets runtime state
+
+    /** if consent is granted, attempt to make a PageView event harvest if one has not already been made */
+    if (accept) {
+      const pveInst = agent.features.page_view_event;
+      pveInst.onAggregateImported.then(loaded => {
+        const pveAgg = pveInst.featAggregate;
+        if (loaded && !pveAgg.sentRum) {
+          pveAgg.sendRum();
+        }
+      });
+    }
+  }, agent);
+}

package/dist/esm/loaders/api/constants.js

@@ -23,4 +23,5 @@ export const SET_PAGE_VIEW_NAME = 'setPageViewName';
 export const SET_USER_ID = 'setUserId';
 export const START = 'start';
 export const WRAP_LOGGER = 'wrapLogger';
-export const MEASURE = 'measure';
+export const MEASURE = 'measure';
+export const CONSENT = 'consent';

package/dist/esm/loaders/api/measure.js

@@ -9,45 +9,45 @@ import { FEATURE_NAMES } from '../features/features';
 import { prefix, MEASURE } from './constants';
 import { setupAPI } from './sharedHandlers';
 export function setupMeasureAPI(agent) {
-  setupAPI(MEASURE, function (name, options) {
-    const n = now();
-    const {
-      start,
-      end,
-      customAttributes
-    } = options || {};
-    const returnObj = {
-      customAttributes: customAttributes || {}
-    };
-    if (typeof returnObj.customAttributes !== 'object' || typeof name !== 'string' || name.length === 0) {
-      warn(57);
-      return;
-    }
+  setupAPI(MEASURE, (name, options) => measure(name, options, agent), agent);
+}
+export function measure(name, options, agentRef, target, timestamp = now()) {
+  const {
+    start,
+    end,
+    customAttributes
+  } = options || {};
+  const returnObj = {
+    customAttributes: customAttributes || {}
+  };
+  if (typeof returnObj.customAttributes !== 'object' || typeof name !== 'string' || name.length === 0) {
+    warn(57);
+    return;
+  }
 
-    /**
+  /**
      * getValueFromTiming - Helper function to extract a numeric value from a supplied option.
      * @param {Number|PerformanceMark} [timing] The timing value
      * @param {Number} [d] The default value to return if timing is invalid
      * @returns {Number} The timing value or the default value
      */
-    const getValueFromTiming = (timing, d) => {
-      if (timing == null) return d;
-      if (typeof timing === 'number') return timing;
-      if (timing instanceof PerformanceMark) return timing.startTime;
-      return Number.NaN;
-    };
-    returnObj.start = getValueFromTiming(start, 0);
-    returnObj.end = getValueFromTiming(end, n);
-    if (Number.isNaN(returnObj.start) || Number.isNaN(returnObj.end)) {
-      warn(57);
-      return;
-    }
-    returnObj.duration = returnObj.end - returnObj.start;
-    if (returnObj.duration < 0) {
-      warn(58);
-      return;
-    }
-    handle(prefix + MEASURE, [returnObj, name], undefined, FEATURE_NAMES.genericEvents, agent.ee);
-    return returnObj;
-  }, agent);
+  const getValueFromTiming = (timing, d) => {
+    if (timing == null) return d;
+    if (typeof timing === 'number') return timing;
+    if (timing instanceof PerformanceMark) return timing.startTime;
+    return Number.NaN;
+  };
+  returnObj.start = getValueFromTiming(start, 0);
+  returnObj.end = getValueFromTiming(end, timestamp);
+  if (Number.isNaN(returnObj.start) || Number.isNaN(returnObj.end)) {
+    warn(57);
+    return;
+  }
+  returnObj.duration = returnObj.end - returnObj.start;
+  if (returnObj.duration < 0) {
+    warn(58);
+    return;
+  }
+  handle(prefix + MEASURE, [returnObj, name, target], undefined, FEATURE_NAMES.genericEvents, agentRef.ee);
+  return returnObj;
 }

package/dist/esm/loaders/api/recordCustomEvent.js

@@ -8,7 +8,8 @@ import { FEATURE_NAMES } from '../features/features';
 import { prefix, RECORD_CUSTOM_EVENT } from './constants';
 import { setupAPI } from './sharedHandlers';
 export function setupRecordCustomEventAPI(agent) {
-  setupAPI(RECORD_CUSTOM_EVENT, function () {
-    handle(prefix + RECORD_CUSTOM_EVENT, [now(), ...arguments], undefined, FEATURE_NAMES.genericEvents, agent.ee);
-  }, agent);
+  setupAPI(RECORD_CUSTOM_EVENT, (eventType, attributes) => recordCustomEvent(eventType, attributes, agent), agent);
+}
+export function recordCustomEvent(eventType, attributes = {}, agentRef, target, timestamp = now()) {
+  handle(prefix + RECORD_CUSTOM_EVENT, [timestamp, eventType, attributes, target], undefined, FEATURE_NAMES.genericEvents, agentRef.ee);
 }

package/dist/esm/loaders/api/register-api-types.js

@@ -5,29 +5,33 @@
 
 /**
  * @typedef {Object} RegisterAPI
- * @property {Function} addPageAction - Add a page action for the registered entity.
- * @property {Function} log - Capture a log for the registered entity.
- * @property {Function} noticeError - Notice an error for the registered entity.
- * @property {Function} setApplicationVersion - Add an application.version attribute to all outgoing data for the registered entity.
- * @property {Function} setCustomAttribute - Add a custom attribute to outgoing data for the registered entity.
- * @property {Function} setUserId - Add an enduser.id attribute to all outgoing API data for the registered entity.
+ * @property {(name: string, attributes?: object) => void} addPageAction - Add a page action for the registered entity.
+ * @property {(message: string, options?: { customAttributes?: object, level?: 'ERROR' | 'TRACE' | 'DEBUG' | 'INFO' | 'WARN'}) => void} log - Capture a log for the registered entity.
+ * @property {(error: Error | string, customAttributes?: object) => void} noticeError - Notice an error for the registered entity.
+ * @property {(target: RegisterAPIConstructor) => RegisterAPI} register - Record a custom event for the registered entity.
+ * @property {(eventType: string, attributes?: Object) => void} recordCustomEvent - Record a custom event for the registered entity.
+ * @property {(eventType: string, options?: {start: number, end: number, duration: number, customAttributes: object}) => ({start: number, end: number, duration: number, customAttributes: object})} measure - Measures a task that is recorded as a BrowserPerformance event.
+ * @property {(value: string | null) => void} setApplicationVersion - Add an application.version attribute to all outgoing data for the registered entity.
+ * @property {(name: string, value: string | number | boolean | null, persist?: boolean) => void} setCustomAttribute - Add a custom attribute to outgoing data for the registered entity.
+ * @property {(value: string | null) => void} setUserId - Add an enduser.id attribute to all outgoing API data for the registered entity.
  * @property {RegisterAPIMetadata} metadata - The metadata object containing the custom attributes and target information for the registered entity.
  */
 
 /**
  * @typedef {Object} RegisterAPIConstructor
- * @property {Object} opts - The options for the registered entity.
- * @property {string} opts.id - The unique id for the registered entity. This will be assigned to any synthesized entities.
- * @property {string} opts.name - The readable name for the registered entity. This will be assigned to any synthesized entities.
+ * @property {string|number} id - The unique id for the registered entity. This will be assigned to any synthesized entities.
+ * @property {string} name - The readable name for the registered entity. This will be assigned to any synthesized entities.
+ * @property {string} [parentId] - The parentId for the registered entity. If none was supplied, it will assume the entity guid from the main agent.
  */
 
 /**
  * @typedef {Object} RegisterAPIMetadata
  * @property {Object} customAttributes - The custom attributes for the registered entity.
  * @property {Object} target - The options for the registered entity.
- * @property {string} target.licenseKey - The license key for the registered entity. If none was supplied, it will assume the license key from the main agent.
+ * @property {string} [target.licenseKey] - The license key for the registered entity. If none was supplied, it will assume the license key from the main agent.
  * @property {string} target.id - The ID for the registered entity.
  * @property {string} target.name - The name returned for the registered entity.
+ * @property {string} [target.parentId] - The parentId for the registered entity. If none was supplied, it will assume the entity guid from the main agent.
  */
 
 export default {};

package/dist/esm/loaders/api/register.js

@@ -4,7 +4,7 @@
  */
 import { handle } from '../../common/event-emitter/handle';
 import { warn } from '../../common/util/console';
-import { isValidMFETarget } from '../../common/util/mfe';
+import { hasValidValue, isValidMFETarget } from '../../common/util/mfe';
 import { FEATURE_NAMES } from '../features/features';
 import { now } from '../../common/timing/now';
 import { SUPPORTABILITY_METRIC_CHANNEL } from '../../features/metrics/constants';
@@ -14,6 +14,8 @@ import { log } from './log';
 import { addPageAction } from './addPageAction';
 import { noticeError } from './noticeError';
 import { single } from '../../common/util/invoke';
+import { measure } from './measure';
+import { recordCustomEvent } from './recordCustomEvent';
 
 /**
  * @typedef {import('./register-api-types').RegisterAPI} RegisterAPI
@@ -26,7 +28,7 @@ import { single } from '../../common/util/invoke';
  */
 export function setupRegisterAPI(agent) {
   setupAPI(REGISTER, function (target) {
-    return buildRegisterApi(agent, target);
+    return register(agent, target);
   }, agent);
 }
 
@@ -34,19 +36,18 @@ export function setupRegisterAPI(agent) {
  * Builds the api object that will be returned from the register api method.
  * Also conducts certain side-effects, such as harvesting a PageView event when triggered and gathering metadata for the registered entity.
  * @param {Object} agentRef the reference to the base agent instance
- * @param {Object} handlers the shared handlers to be used by both the base agent's API and the external target's API
- * @param {Object} target the target information to be used by the external target's API to send data to the correct location
- * @param {string} [target.licenseKey] the license key of the target to report data to
- * @param {string} target.id the entity ID of the target to report data to
- * @param {string} target.name the entity name of the target to report data to
+ * @param {import('./register-api-types').RegisterAPIConstructor} target
+ * @param {import('./register-api-types').RegisterAPIConstructor} [parent]
  * @returns {RegisterAPI} the api object to be returned from the register api method
  */
-export function buildRegisterApi(agentRef, target) {
+function register(agentRef, target, parent) {
   const attrs = {};
   warn(54, 'newrelic.register');
   target ||= {};
+  target.eventSource = 'MicroFrontendBrowserAgent';
   target.licenseKey ||= agentRef.info.licenseKey; // will inherit the license key from the container agent if not provided for brevity. A future state may dictate that we need different license keys to do different things.
   target.blocked = false;
+  target.parent = parent || {};
 
   /** @type {Function} a function that is set and reports when APIs are triggered -- warns the customer of the invalid state  */
   let invalidApiResponse = () => {};
@@ -79,6 +80,9 @@ export function buildRegisterApi(agentRef, target) {
   /** primary cases that can block the register API from working at init time */
   if (!agentRef.init.api.allow_registered_children) block(single(() => warn(55)));
   if (!isValidMFETarget(target)) block(single(() => warn(48, target)));
+  if (!hasValidValue(target.id) || !hasValidValue(target.name)) {
+    block(single(() => warn(48, target)));
+  }
 
   /** @type {RegisterAPI} */
   const api = {
@@ -93,10 +97,22 @@ export function buildRegisterApi(agentRef, target) {
         ...(options.customAttributes || {})
       }
     }, agentRef], target),
+    measure: (name, options = {}) => report(measure, [name, {
+      ...options,
+      customAttributes: {
+        ...attrs,
+        ...(options.customAttributes || {})
+      }
+    }, agentRef], target),
     noticeError: (error, attributes = {}) => report(noticeError, [error, {
       ...attrs,
       ...attributes
     }, agentRef], target),
+    register: (target = {}) => report(register, [agentRef, target], api.metadata.target),
+    recordCustomEvent: (eventType, attributes = {}) => report(recordCustomEvent, [eventType, {
+      ...attrs,
+      ...attributes
+    }, agentRef], target),
     setApplicationVersion: value => setLocalValue('application.version', value),
     setCustomAttribute: (key, value) => setLocalValue(key, value),
     setUserId: value => setLocalValue('enduser.id', value),
@@ -144,8 +160,8 @@ export function buildRegisterApi(agentRef, target) {
     const timestamp = now();
     handle(SUPPORTABILITY_METRIC_CHANNEL, ["API/register/".concat(methodToCall.name, "/called")], undefined, FEATURE_NAMES.metrics, agentRef.ee);
     try {
-      const shouldDuplicate = agentRef.init.api.duplicate_registered_data;
-      if (shouldDuplicate === true || Array.isArray(shouldDuplicate)) {
+      const shouldDuplicate = agentRef.init.api.duplicate_registered_data && methodToCall.name !== 'register';
+      if (shouldDuplicate) {
         // also report to container by providing undefined target
         methodToCall(...args, undefined, timestamp);
       }