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

package/src/loaders/api/consent.js

@@ -0,0 +1,31 @@
+/**
+ * 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/src/loaders/api/constants.js

@@ -25,3 +25,4 @@ export const SET_USER_ID = 'setUserId'
 export const START = 'start'
 export const WRAP_LOGGER = 'wrapLogger'
 export const MEASURE = 'measure'
+export const CONSENT = 'consent'

package/src/loaders/api/measure.js

@@ -10,44 +10,45 @@ 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 || {} }
+  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
-    }
+  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/src/loaders/api/recordCustomEvent.js

@@ -9,7 +9,9 @@ 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/src/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/src/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,20 +36,19 @@ 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 = () => {}
@@ -73,12 +74,18 @@ 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 = {
     addPageAction: (name, attributes = {}) => report(addPageAction, [name, { ...attrs, ...attributes }, agentRef], target),
     log: (message, options = {}) => report(log, [message, { ...options, customAttributes: { ...attrs, ...(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),
@@ -126,8 +133,8 @@ export function buildRegisterApi (agentRef, target) {
     const timestamp = now()
     handle(SUPPORTABILITY_METRIC_CHANNEL, [`API/register/${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)
       }

package/src/loaders/api-base.js

@@ -3,7 +3,7 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 import { warn } from '../common/util/console'
-import { ADD_PAGE_ACTION, ADD_RELEASE, ADD_TO_TRACE, FINISHED, INTERACTION, LOG, NOTICE_ERROR, PAUSE_REPLAY, RECORD_CUSTOM_EVENT, RECORD_REPLAY, REGISTER, SET_APPLICATION_VERSION, SET_CURRENT_ROUTE_NAME, SET_CUSTOM_ATTRIBUTE, SET_ERROR_HANDLER, SET_PAGE_VIEW_NAME, SET_USER_ID, START, WRAP_LOGGER, MEASURE } from './api/constants'
+import { ADD_PAGE_ACTION, ADD_RELEASE, ADD_TO_TRACE, CONSENT, FINISHED, INTERACTION, LOG, NOTICE_ERROR, PAUSE_REPLAY, RECORD_CUSTOM_EVENT, RECORD_REPLAY, REGISTER, SET_APPLICATION_VERSION, SET_CURRENT_ROUTE_NAME, SET_CUSTOM_ATTRIBUTE, SET_ERROR_HANDLER, SET_PAGE_VIEW_NAME, SET_USER_ID, START, WRAP_LOGGER, MEASURE } from './api/constants'
 
 /**
  * @typedef {import('./api/interaction-types').InteractionInstance} InteractionInstance
@@ -32,11 +32,8 @@ export class ApiBase {
    * It is not recommended for use in production environments and will not receive support for issues.
    *
    * Registers an external caller to report through the base agent to a different target than the base agent.
-   * @param {object} target the target object to report data to
-   * @param {string} target.licenseKey The licenseKey to report data to
-   * @param {string} target.applicationID The applicationID to report data to
-   * @param {string=} target.entityGuid The entityGuid to report data to
-   * @returns {object} Returns an object that contains the available API methods and configurations to use with the external caller. See loaders/api/api.js for more information.
+   * @param {import('./api/register-api-types').RegisterAPIConstructor} target the target object to report data to
+  @returns {import('./api/register-api-types').RegisterAPI} Returns an object that contains the available API methods and configurations to use with the external caller. See loaders/api/api.js for more information.
    */
   register (target) {
     return this.#callMethod(REGISTER, target)
@@ -46,7 +43,7 @@ export class ApiBase {
    * 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"}.
+   * @param {Object} [attributes] JSON object with one or more key/value pairs. For example: {key:"value"}.
    */
   recordCustomEvent (eventType, attributes) {
     return this.#callMethod(RECORD_CUSTOM_EVENT, eventType, attributes)
@@ -222,10 +219,20 @@ export class ApiBase {
    * 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 {object?} options An object used to control the way the measure API operates
+   * @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) {
     return this.#callMethod(MEASURE, name, options)
   }
+
+  /**
+   * Accepts or rejects consent when the agent is configured to require consent before harvesting.
+   * The consent state is stored in session storage inside the NRBA_SESSION object.
+   * {@link https://docs.newrelic.com/docs/browser/new-relic-browser/browser-apis/consent/}
+   * @param {boolean?} accept Whether to accept or reject consent. Defaults to true (accept) if left undefined.
+   */
+  consent (accept) {
+    return this.#callMethod(CONSENT, accept)
+  }
 }