@newrelic/browser-agent 1.286.0 → 1.288.0

package/src/loaders/api/api.js

@@ -3,7 +3,6 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 import { FEATURE_NAMES } from '../features/features'
-import { setInfo } from '../../common/config/info'
 import { handle } from '../../common/event-emitter/handle'
 import { drain, registerDrain } from '../../common/drain/drain'
 import { onWindowLoad } from '../../common/window/load'
@@ -18,6 +17,7 @@ import { MODE } from '../../common/session/constants'
 import { LOG_LEVELS } from '../../features/logging/constants'
 import { bufferLog } from '../../features/logging/shared/utils'
 import { wrapLogger } from '../../common/wrap/wrap-logger'
+import { buildRegisterApi } from './register-api'
 import { dispatchGlobalEvent } from '../../common/dispatch/global-event'
 import { activatedFeatures } from '../../common/util/feature-flags'
 
@@ -55,9 +55,37 @@ export function setAPI (agent, forceDrain) {
   const prefix = 'api-'
   const spaPrefix = prefix + 'ixn-'
 
-  agent.log = function (message, { customAttributes = {}, level = LOG_LEVELS.INFO } = {}) {
-    handle(SUPPORTABILITY_METRIC_CHANNEL, ['API/log/called'], undefined, FEATURE_NAMES.metrics, agent.ee)
-    bufferLog(agent.ee, message, customAttributes, level)
+  /** Shared handlers are used by both the base agent instance as well as "registered" entities
+   * We isolate them like this so that the public interface methods are unchanged and still dont require
+   * a target, but the register APIs `can` supply a target.
+  */
+  const sharedHandlers = {
+    addPageAction: function (name, attributes, targetEntityGuid, timestamp = now()) {
+      apiCall(prefix, 'addPageAction', true, FEATURE_NAMES.genericEvents, timestamp)(name, attributes, targetEntityGuid)
+    },
+    log: function (message, { customAttributes = {}, level = LOG_LEVELS.INFO } = {}, targetEntityGuid, timestamp = now()) {
+      handle(SUPPORTABILITY_METRIC_CHANNEL, ['API/log/called'], undefined, FEATURE_NAMES.metrics, agent.ee)
+      bufferLog(agent.ee, message, customAttributes, level, targetEntityGuid, timestamp)
+    },
+    noticeError: function (err, customAttributes, targetEntityGuid, timestamp = now()) {
+      if (typeof err === 'string') err = new Error(err)
+      handle(SUPPORTABILITY_METRIC_CHANNEL, ['API/noticeError/called'], undefined, FEATURE_NAMES.metrics, agent.ee)
+      handle('err', [err, timestamp, false, customAttributes, !!replayRunning[agent.agentIdentifier], undefined, targetEntityGuid], undefined, FEATURE_NAMES.jserrors, agent.ee)
+    }
+  }
+
+  /**
+   * @experimental
+   * IMPORTANT: This feature is being developed for use internally and is not in a public-facing production-ready state.
+   * It is not recommended for use in production environments and will not receive support for issues.
+   */
+  agent.register = function (target) {
+    handle(SUPPORTABILITY_METRIC_CHANNEL, ['API/register/called'], undefined, FEATURE_NAMES.metrics, agent.ee)
+    return buildRegisterApi(agent, sharedHandlers, target)
+  }
+
+  agent.log = function (message, options) {
+    sharedHandlers.log(message, options)
   }
 
   agent.wrapLogger = (parent, functionName, { customAttributes = {}, level = LOG_LEVELS.INFO } = {}) => {
@@ -68,7 +96,9 @@ export function setAPI (agent, forceDrain) {
   // Setup stub functions that queue calls for later processing.
   asyncApiMethods.forEach(fnName => { agent[fnName] = apiCall(prefix, fnName, true, 'api') })
 
-  agent.addPageAction = apiCall(prefix, 'addPageAction', true, FEATURE_NAMES.genericEvents)
+  agent.addPageAction = function (name, attributes) {
+    sharedHandlers.addPageAction(name, attributes)
+  }
 
   agent.recordCustomEvent = apiCall(prefix, 'recordCustomEvent', true, FEATURE_NAMES.genericEvents)
 
@@ -92,7 +122,7 @@ export function setAPI (agent, forceDrain) {
     if (value === null) {
       delete currentInfo.jsAttributes[key]
     } else {
-      setInfo(agent.agentIdentifier, { ...currentInfo, jsAttributes: { ...currentInfo.jsAttributes, [key]: value } })
+      agent.info = { ...agent.info, jsAttributes: { ...currentInfo.jsAttributes, [key]: value } }
     }
     return apiCall(prefix, apiName, true, (!!addToBrowserStorage || value === null) ? 'session' : undefined)(key, value)
   }
@@ -185,11 +215,19 @@ export function setAPI (agent, forceDrain) {
   }
 
   ;['actionText', 'setName', 'setAttribute', 'save', 'ignore', 'onEnd', 'getContext', 'end', 'get'].forEach(name => {
-    InteractionApiProto[name] = apiCall(spaPrefix, name, undefined, agent.runSoftNavOverSpa ? FEATURE_NAMES.softNav : FEATURE_NAMES.spa)
+    InteractionApiProto[name] = function () {
+      return apiCall
+        .apply(this, [spaPrefix, name, undefined, agent.runSoftNavOverSpa ? FEATURE_NAMES.softNav : FEATURE_NAMES.spa])
+        .apply(this, arguments)
+    }
   })
-  agent.setCurrentRouteName = agent.runSoftNavOverSpa ? apiCall(spaPrefix, 'routeName', undefined, FEATURE_NAMES.softNav) : apiCall(prefix, 'routeName', true, FEATURE_NAMES.spa)
+  agent.setCurrentRouteName = function () {
+    return agent.runSoftNavOverSpa
+      ? apiCall(spaPrefix, 'routeName', undefined, FEATURE_NAMES.softNav)(...arguments)
+      : apiCall(prefix, 'routeName', true, FEATURE_NAMES.spa)(...arguments)
+  }
 
-  function apiCall (prefix, name, notSpa, bufferGroup) {
+  function apiCall (prefix, name, notSpa, bufferGroup, timestamp = now()) {
     return function () {
       handle(SUPPORTABILITY_METRIC_CHANNEL, ['API/' + name + '/called'], undefined, FEATURE_NAMES.metrics, agent.ee)
       dispatchGlobalEvent({
@@ -200,15 +238,13 @@ export function setAPI (agent, forceDrain) {
         feature: prefix + name,
         data: { notSpa, bufferGroup }
       })
-      if (bufferGroup) handle(prefix + name, [notSpa ? now() : performance.now(), ...arguments], notSpa ? null : this, bufferGroup, agent.ee) // no bufferGroup means only the SM is emitted
+      if (bufferGroup) handle(prefix + name, [timestamp, ...arguments], notSpa ? null : this, bufferGroup, agent.ee) // no bufferGroup means only the SM is emitted
       return notSpa ? undefined : this // returns the InteractionHandle which allows these methods to be chained
     }
   }
 
   agent.noticeError = function (err, customAttributes) {
-    if (typeof err === 'string') err = new Error(err)
-    handle(SUPPORTABILITY_METRIC_CHANNEL, ['API/noticeError/called'], undefined, FEATURE_NAMES.metrics, agent.ee)
-    handle('err', [err, now(), false, customAttributes, !!replayRunning[agent.agentIdentifier]], undefined, FEATURE_NAMES.jserrors, agent.ee)
+    sharedHandlers.noticeError(err, customAttributes)
   }
 
   // theres no window.load event on non-browser scopes, lazy load immediately

package/src/loaders/api/register-api-types.js

@@ -0,0 +1,33 @@
+/**
+ * Copyright 2020-2025 New Relic, Inc. All rights reserved.
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * @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 {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.licenseKey - The license key for the registered entity.
+ * @property {string} opts.applicationID - The application ID for the registered entity.
+ */
+
+/**
+ * @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.
+ * @property {string} target.applicationID - The application ID for the registered entity.
+ * @property {string} target.entityGuid - The entity guid returned for the registered entity.
+ */
+
+export default {}

package/src/loaders/api/register-api.js

@@ -0,0 +1,152 @@
+/**
+ * Copyright 2020-2025 New Relic, Inc. All rights reserved.
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { handle } from '../../common/event-emitter/handle'
+import { warn } from '../../common/util/console'
+import { isContainerAgentTarget, isValidTarget } from '../../common/util/target'
+import { FEATURE_NAMES } from '../features/features'
+import { now } from '../../common/timing/now'
+import { SUPPORTABILITY_METRIC_CHANNEL } from '../../features/metrics/constants'
+
+/**
+ * @typedef {import('./register-api-types').RegisterAPI} RegisterAPI
+ */
+
+/**
+ * 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
+ * @returns {RegisterAPI} the api object to be returned from the register api method
+ */
+export function buildRegisterApi (agentRef, handlers, target) {
+  const attrs = {}
+  warn(54, 'newrelic.register')
+
+  /** @type {Function|undefined} a function that is set and reports when APIs are triggered -- warns the customer of the invalid state  */
+  let invalidApiResponse
+
+  /**
+       * A promise that indicates when all needed connections for the registered child to be ready to report data
+       * 1. The main agent to be ready (made a RUM call and got its entity guid)
+       * 2. The child to be registered with the main agent (made its own RUM call and got its entity guid)
+       * @type {Promise<RegisterAPI>}
+       */
+  let _connected
+  if (!agentRef.init.api.allow_registered_children) invalidApiResponse = () => warn(55)
+  if (!target || !isValidTarget(target)) invalidApiResponse = () => warn(48, target)
+
+  /** @type {RegisterAPI} */
+  const api = {
+    addPageAction: (name, attributes = {}) => {
+      report(handlers.addPageAction, [name, { ...attrs, ...attributes }], target)
+    },
+    log: (message, options = {}) => {
+      report(handlers.log, [message, { ...options, customAttributes: { ...attrs, ...(options.customAttributes || {}) } }], target)
+    },
+    noticeError: (error, attributes = {}) => {
+      report(handlers.noticeError, [error, { ...attrs, ...attributes }], target)
+    },
+    setApplicationVersion: (value) => {
+      attrs['application.version'] = value
+    },
+    setCustomAttribute: (key, value) => {
+      attrs[key] = value
+    },
+    setUserId: (value) => {
+      attrs['enduser.id'] = value
+    },
+    /** metadata */
+    metadata: {
+      customAttributes: attrs,
+      target,
+      /** set in a getter so that later access of the Promise is not polluted before customer is allowed to set a catch block */
+      get connected () {
+        return _connected || Promise.reject(new Error('Failed to connect'))
+      }
+    }
+  }
+
+  if (invalidApiResponse) {
+    invalidApiResponse()
+  } else {
+    _connected = new Promise((resolve, reject) => {
+      try {
+        const entityManager = agentRef.runtime?.entityManager
+        /** check if main agent already has main agent entity guid */
+        let mainAgentReady = !!entityManager?.get().entityGuid
+        /** check if registered target already has entity guid */
+        let registeredEntityGuid = entityManager?.getEntityGuidFor(target.licenseKey, target.applicationID)
+        let registrationReady = !!registeredEntityGuid
+
+        /** check if we can just resolve immediately without making another connect call */
+        if (mainAgentReady && registrationReady) {
+          target.entityGuid = registeredEntityGuid
+          resolve(api)
+        } else {
+          /** we need to make a new connection call since we dont already have a registered entity for this call */
+
+          /** if the connect callback doesnt resolve in 15 seconds... reject */
+          const timeout = setTimeout(() => reject(new Error('Failed to connect - Timeout')), 15000)
+
+          // tell the main agent to send a rum call for this target
+          // when the rum call resolves, it will emit an "entity-added" event, see below
+          agentRef.ee.emit('api-send-rum', [attrs, target])
+
+          // wait for entity events to emit to see when main agent and/or API registration is ready
+          agentRef.ee.on('entity-added', entityEventHandler)
+
+          function entityEventHandler (entity) {
+            if (isContainerAgentTarget(entity, agentRef)) mainAgentReady ||= true
+            else {
+              if (target.licenseKey === entity.licenseKey && target.applicationID === entity.applicationID) {
+                registrationReady = true
+                target.entityGuid = entity.entityGuid
+              }
+            }
+
+            if (mainAgentReady && registrationReady) {
+              clearTimeout(timeout)
+              // unsubscribe from the event emitter
+              agentRef.ee.removeEventListener('entity-added', entityEventHandler)
+              resolve(api)
+            }
+          }
+        }
+      } catch (err) {
+        reject(err)
+      }
+    })
+  }
+
+  /**
+     * The reporter method that will be used to report the data to the container agent's API method. If invalid, will log a warning and not execute.
+     * If the api.duplicate_registered_data configuration value is set to true, the data will be reported to BOTH the container and the external target
+     * @param {*} methodToCall the container agent's API method to call
+     * @param {*} args the arguments to supply to the container agent's API method
+     * @param {string} targetEntityGuid the target entity guid, which looks up the target to report the data to from the entity manager. If undefined, will report to the container agent's target.
+     * @returns
+     */
+  const report = async (methodToCall, args, target) => {
+    if (invalidApiResponse) return invalidApiResponse()
+    /** set the timestamp before the async part of waiting for the rum response for better accuracy */
+    const timestamp = now()
+    handle(SUPPORTABILITY_METRIC_CHANNEL, [`API/register/${methodToCall.name}/called`], undefined, FEATURE_NAMES.metrics, agentRef.ee)
+    try {
+      await _connected
+      // target should be decorated with entityGuid by the rum resp at this point
+      const shouldDuplicate = agentRef.init.api.duplicate_registered_data
+      if (shouldDuplicate === true || (Array.isArray(shouldDuplicate) && shouldDuplicate.includes(target.entityGuid))) {
+        // also report to container by providing undefined target
+        methodToCall(...args, undefined, timestamp)
+      }
+      methodToCall(...args, target.entityGuid, timestamp) // always report to target
+    } catch (err) {
+      warn(50, err)
+    }
+  }
+
+  return api
+}

package/src/loaders/micro-agent-base.js

@@ -34,6 +34,22 @@ export class MicroAgentBase {
     return this.#callMethod('addPageAction', name, attributes)
   }
 
+  /**
+   * @experimental
+   * IMPORTANT: This feature is being developed for use internally and is not in a public-facing production-ready state.
+   * 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.
+   */
+  register (target) {
+    return this.#callMethod('register', target)
+  }
+
   /**
    * Records a custom event with a specified eventType and attributes.
    * {@link https://docs.newrelic.com/docs/browser/new-relic-browser/browser-apis/recordCustomEvent/}

package/src/loaders/micro-agent.js

@@ -21,6 +21,7 @@ const nonAutoFeatures = [
 ]
 
 /**
+ * @deprecated This feature has been deprecated and will be removed in a future release. A future product centralizing around a single agent instance will be released as a replacement, at which time this loader will be removed.
  * A minimal agent class designed to only respond to manual user input. As such, this class does not
  * automatically instrument. Instead, each MicroAgent instance will lazy load the required features and can support loading multiple instances on one page.
  * Out of the box, it can manually handle and report Page View, Page Action, and Error events.