feat: Capture Nearest UserAction Fields (#1267)

Author: metal-messiah

.github/actions/build-ab/templates/experiments.js

@@ -7,6 +7,7 @@ window.NREUM.init.proxy = {} // Proxy won't work for experiments
 window.NREUM.init.session_replay.enabled = false // disabled for now to not double wrap the page which can cause extra processing burden
 window.NREUM.init.session_trace.enabled = false // disabled for now to not double wrap the page which can cause extra processing burden
 window.NREUM.init.feature_flags = ['ajax_metrics_deny_list','soft_nav']
+window.NREUM.init.user_actions = {elementAttributes: ['id', 'className', 'tagName', 'type', 'innerText', 'textContent', 'ariaLabel', 'alt', 'title']}
 
 {{#if experimentScripts}}
 {{#each experimentScripts}}

.github/actions/build-ab/templates/latest.js

@@ -7,5 +7,6 @@ window.NREUM.init.proxy.assets = 'https://staging-js-agent.newrelic.com/dev'
 window.NREUM.init.feature_flags = ['soft_nav','ajax_metrics_deny_list']
 window.NREUM.init.session_replay.enabled = false // disabled for now to not double wrap the page which can cause extra processing burden
 window.NREUM.init.session_trace.enabled = false // disabled for now to not double wrap the page which can cause extra processing burden
+window.NREUM.init.user_actions = {elementAttributes: ['id', 'className', 'tagName', 'type', 'innerText', 'textContent', 'ariaLabel', 'alt', 'title']}
 
 {{{latestScript}}}

.github/actions/build-ab/templates/postamble.js

@@ -7,6 +7,7 @@ window.NREUM.info.licenseKey = '{{{args.licenseKey}}}'
 window.NREUM.init.proxy = {}
 window.NREUM.init.session_replay.enabled = true
 window.NREUM.init.session_trace.enabled = true
+window.NREUM.init.user_actions = {elementAttributes: ['id', 'className', 'tagName', 'type', 'innerText', 'textContent', 'ariaLabel', 'alt', 'title']}
 
 // Session replay entitlements check
 try {

.github/actions/build-ab/templates/released.js

@@ -33,7 +33,8 @@ window.NREUM={
         first_party_domains: ['dev-one.nr-assets.net', 'staging-one.nr-assets.net', 'one.nr-assets.net', 'nr-assets.net']
       }
     },
-    proxy: {}
+    proxy: {},
+    user_actions: {elementAttributes: ['id', 'className', 'tagName', 'type', 'innerText', 'textContent', 'ariaLabel', 'alt', 'title']}
   },
   loader_config: {
     accountID: '1',

.github/workflows/publish-experiment.yml

@@ -26,6 +26,8 @@ jobs:
         shell: bash
     steps:
       - uses: actions/checkout@v4
+        with:
+            ref: ${{ github.ref }}
       - uses: actions/setup-node@v4
         with:
           node-version: 22.11.0 # See package.json for the stable node version that works with our testing.  Do not change this unless you know what you are doing as some node versions do not play nicely with our testing server.
@@ -84,6 +86,8 @@ jobs:
         shell: bash
     steps:
       - uses: actions/checkout@v4
+        with:
+            ref: ${{ github.ref }}
       - uses: actions/setup-node@v4
         with:
           node-version: 22.11.0 # See package.json for the stable node version that works with our testing.  Do not change this unless you know what you are doing as some node versions do not play nicely with our testing server.

package.json

@@ -172,7 +172,7 @@
     "start": "npm-run-all --parallel cdn:watch test-server",
     "lint": "eslint -c .eslintrc.js --ext .js,.cjs,.mjs .",
     "lint:fix": "npm run lint -- --fix",
-    "test": "jest",
+    "test": " NODE_OPTIONS=--max-old-space-size=8192 jest",
     "test:unit": "jest --selectProjects unit",
     "test:component": "jest --selectProjects component",
     "test:types": "tsd -f ./tests/dts/**/*.ts",

src/common/config/init.js

@@ -131,7 +131,7 @@ const model = () => {
     soft_navigations: { enabled: true, autoStart: true },
     spa: { enabled: true, autoStart: true },
     ssl: undefined,
-    user_actions: { enabled: true }
+    user_actions: { enabled: true, elementAttributes: ['id', 'className', 'tagName', 'type'] }
   }
 }
 

src/common/dom/selector-path.js

@@ -10,8 +10,8 @@
  * @param {boolean} includeClass
  * @returns {string|undefined}
  */
-export const generateSelectorPath = (elem) => {
-  if (!elem) return
+export const generateSelectorPath = (elem, targetFields = []) => {
+  if (!elem) return { path: undefined, nearestFields: {} }
 
   const getNthOfTypeIndex = (node) => {
     try {
@@ -30,9 +30,13 @@ export const generateSelectorPath = (elem) => {
   let pathSelector = ''
   let index = getNthOfTypeIndex(elem)
 
+  const nearestFields = {}
   try {
     while (elem?.tagName) {
       const { id, localName } = elem
+      targetFields.forEach(field => {
+        nearestFields[nearestAttrName(field)] ||= elem[field]
+      })
       const selector = [
         localName,
         id ? `#${id}` : '',
@@ -46,5 +50,13 @@ export const generateSelectorPath = (elem) => {
   // do nothing for now
   }
 
-  return pathSelector ? index ? `${pathSelector}:nth-of-type(${index})` : pathSelector : undefined
+  const path = pathSelector ? index ? `${pathSelector}:nth-of-type(${index})` : pathSelector : undefined
+  return { path, nearestFields }
+
+  function nearestAttrName (originalFieldName) {
+    /** preserve original renaming structure for pre-existing field maps */
+    if (originalFieldName === 'tagName') originalFieldName = 'tag'
+    if (originalFieldName === 'className') originalFieldName = 'class'
+    return `nearest${originalFieldName.charAt(0).toUpperCase() + originalFieldName.slice(1)}`
+  }
 }

src/features/generic_events/aggregate/index.js

@@ -60,7 +60,7 @@ export class Aggregate extends AggregateBase {
         }, this.featureName, this.ee)
       }
 
-      let addUserAction
+      let addUserAction = () => { /** no-op */ }
       if (isBrowserScope && agentRef.init.user_actions.enabled) {
         this.userActionAggregator = new UserActionsAggregator()
         this.harvestOpts.beforeUnload = () => addUserAction?.(this.userActionAggregator.aggregationEvent)
@@ -81,12 +81,27 @@ export class Aggregate extends AggregateBase {
                 rageClick: aggregatedUserAction.rageClick,
                 target: aggregatedUserAction.selectorPath,
                 ...(isIFrameWindow(window) && { iframe: true }),
-                ...(canTrustTargetAttribute('id') && { targetId: target.id }),
-                ...(canTrustTargetAttribute('tagName') && { targetTag: target.tagName }),
-                ...(canTrustTargetAttribute('type') && { targetType: target.type }),
-                ...(canTrustTargetAttribute('className') && { targetClass: target.className })
+                ...(this.agentRef.init.user_actions.elementAttributes.reduce((acc, field) => {
+                  /** prevent us from capturing an obscenely long value */
+                  if (canTrustTargetAttribute(field)) acc[targetAttrName(field)] = String(target[field]).trim().slice(0, 128)
+                  return acc
+                }, {})),
+                ...aggregatedUserAction.nearestTargetFields
               })
 
+              /**
+               * Returns the original target field name with `target` prepended and camelCased
+               * @param {string} originalFieldName
+               * @returns {string} the target field name
+               */
+              function targetAttrName (originalFieldName) {
+                /** preserve original renaming structure for pre-existing field maps */
+                if (originalFieldName === 'tagName') originalFieldName = 'tag'
+                if (originalFieldName === 'className') originalFieldName = 'class'
+                /** return the original field name, cap'd and prepended with target to match formatting */
+                return `target${originalFieldName.charAt(0).toUpperCase() + originalFieldName.slice(1)}`
+              }
+
               /**
                * Only trust attributes that exist on HTML element targets, which excludes the window and the document targets
                * @param {string} attribute The attribute to check for on the target element
@@ -103,7 +118,7 @@ export class Aggregate extends AggregateBase {
 
         registerHandler('ua', (evt) => {
           /** the processor will return the previously aggregated event if it has been completed by processing the current event */
-          addUserAction(this.userActionAggregator.process(evt))
+          addUserAction(this.userActionAggregator.process(evt, this.agentRef.init.user_actions.elementAttributes))
         }, this.featureName, this.ee)
       }
 

src/features/generic_events/aggregate/user-actions/aggregated-user-action.js

@@ -5,13 +5,14 @@
 import { RAGE_CLICK_THRESHOLD_EVENTS, RAGE_CLICK_THRESHOLD_MS } from '../../constants'
 
 export class AggregatedUserAction {
-  constructor (evt, selectorPath) {
+  constructor (evt, selectorPath, nearestTargetFields) {
     this.event = evt
     this.count = 1
     this.originMs = Math.floor(evt.timeStamp)
     this.relativeMs = [0]
     this.selectorPath = selectorPath
     this.rageClick = undefined
+    this.nearestTargetFields = nearestTargetFields
   }
 
   /**

src/features/generic_events/aggregate/user-actions/user-actions-aggregator.js

@@ -26,9 +26,9 @@ export class UserActionsAggregator {
    * @param {Event} evt The event supplied by the addEventListener callback
    * @returns {AggregatedUserAction|undefined} The previous aggregation set if it has been completed by processing the current event
    */
-  process (evt) {
+  process (evt, targetFields) {
     if (!evt) return
-    const selectorPath = getSelectorPath(evt)
+    const { selectorPath, nearestTargetFields } = getSelectorPath(evt, targetFields)
     const aggregationKey = getAggregationKey(evt, selectorPath)
     if (!!aggregationKey && aggregationKey === this.#aggregationKey) {
       // an aggregation exists already, so lets just continue to increment
@@ -38,7 +38,7 @@ export class UserActionsAggregator {
       const finishedEvent = this.#aggregationEvent
       // then set as this new event aggregation
       this.#aggregationKey = aggregationKey
-      this.#aggregationEvent = new AggregatedUserAction(evt, selectorPath)
+      this.#aggregationEvent = new AggregatedUserAction(evt, selectorPath, nearestTargetFields)
       return finishedEvent
     }
   }
@@ -50,14 +50,18 @@ export class UserActionsAggregator {
  * @param {Event} evt
  * @returns {string}
  */
-function getSelectorPath (evt) {
-  let selectorPath
+function getSelectorPath (evt, targetFields) {
+  let selectorPath; let nearestTargetFields = {}
   if (OBSERVED_WINDOW_EVENTS.includes(evt.type) || evt.target === window) selectorPath = 'window'
   else if (evt.target === document) selectorPath = 'document'
   // if still no selectorPath, generate one from target tree that includes elem ids
-  else selectorPath = generateSelectorPath(evt.target)
+  else {
+    const { path, nearestFields } = generateSelectorPath(evt.target, targetFields)
+    selectorPath = path
+    nearestTargetFields = nearestFields
+  }
   // if STILL no selectorPath, it will return undefined which will skip aggregation for this event
-  return selectorPath
+  return { selectorPath, nearestTargetFields }
 }
 
 /**

tests/assets/user-actions.html

@@ -18,7 +18,11 @@
 		{loader}
   </head>
   <body style="height: 200vh; overflow: scroll;">
-		<button id="pay-btn" class="btn-cart-add flex-grow container" type="submit">Create click user action</button>
-		<input type="text" id="textbox"/>
+    <div aria-label="Pay submit button">
+      <button style="padding: 20px;" id="pay-btn" class="btn-cart-add flex-grow container" type="submit">
+        <span>Create click user action</span>
+      </button>
+      <input type="text" id="textbox"/>
+    </div>
   </body>
 </html>

tests/specs/ins/harvesting.e2e.js

@@ -81,14 +81,14 @@ describe('ins harvesting', () => {
 
     const [insHarvests] = await Promise.all([
       insightsCapture.waitForResult({ timeout: 7500 }),
-      $('#pay-btn').click().then(async () => {
+      $('#textbox').click().then(async () => {
         // rage click
         await browser.execute(function () {
           for (let i = 0; i < 5; i++) {
-            document.querySelector('#textbox').click()
+            document.querySelector('span').click()
           }
         })
-        // stop aggregating textbox clicks
+        // stop aggregating clicks
         await $('body').click()
       })
     ])
@@ -102,11 +102,10 @@ describe('ins harvesting', () => {
       actionCount: 1,
       actionDuration: 0,
       actionMs: '[0]',
-      target: 'html>body>button#pay-btn:nth-of-type(1)',
-      targetId: 'pay-btn',
-      targetTag: 'BUTTON',
-      targetType: 'submit',
-      targetClass: 'btn-cart-add flex-grow container',
+      target: 'html>body>div>input#textbox:nth-of-type(1)',
+      targetId: 'textbox',
+      targetTag: 'INPUT',
+      targetType: 'text',
       pageUrl: expect.any(String),
       timestamp: expect.any(Number)
     })
@@ -116,11 +115,13 @@ describe('ins harvesting', () => {
       actionCount: 5,
       actionDuration: expect.any(Number),
       actionMs: expect.any(String),
+      nearestId: 'pay-btn',
+      nearestTag: 'SPAN',
+      nearestType: 'submit',
+      nearestClass: 'btn-cart-add flex-grow container',
       rageClick: true,
-      target: 'html>body>input#textbox:nth-of-type(1)',
-      targetId: 'textbox',
-      targetTag: 'INPUT',
-      targetType: 'text',
+      target: 'html>body>div>button#pay-btn>span:nth-of-type(1)',
+      targetTag: 'SPAN',
       pageUrl: expect.any(String),
       timestamp: expect.any(Number)
     })

tests/unit/common/config/init.test.js

@@ -73,7 +73,8 @@ test('init props exist and return expected defaults', () => {
     enabled: true
   })
   expect(config.user_actions).toEqual({
-    enabled: true
+    enabled: true,
+    elementAttributes: ['id', 'className', 'tagName', 'type']
   })
   expect(config.page_view_event).toEqual({
     autoStart: true,
@@ -153,7 +154,8 @@ test('init props exist and return expected defaults', () => {
   })
   expect(config.ssl).toEqual(undefined)
   expect(config.user_actions).toEqual({
-    enabled: true
+    enabled: true,
+    elementAttributes: ['id', 'className', 'tagName', 'type']
   })
 })
 

tests/unit/common/dom/selector-path.test.js

@@ -1,17 +1,19 @@
 import { generateSelectorPath } from '../../../../src/common/dom/selector-path'
 
+const targetFields = ['id', 'className', 'tagName', 'type']
+
 describe('generateSelectorPath', () => {
   let span, p
 
   beforeEach(() => {
     document.body.innerHTML = `
     <html>
         <body>
-            <div id="container">
+            <div id="container" class="container">
                 <div class="child">
                     <span class="grandchild">Text</span>
                 </div>
-                <div class="child">
+                <div>
                     <p id="target">Paragraph</p>
                 </div>
             </div>
@@ -24,31 +26,41 @@ describe('generateSelectorPath', () => {
   })
 
   test('should generate selector path including id', () => {
-    const selectorWithId = generateSelectorPath(p)
+    const { path: selectorWithId } = generateSelectorPath(p, targetFields)
     expect(selectorWithId).toBe('html>body>div#container>div>p#target:nth-of-type(1)')
 
-    const selectorWithoutId = generateSelectorPath(span)
+    const { path: selectorWithoutId } = generateSelectorPath(span)
+    expect(selectorWithoutId).toBe('html>body>div#container>div>span:nth-of-type(1)')
+  })
+
+  test('should generate nearestFields', () => {
+    // should get the id from <p>, tagName from <p> and class from <div>
+    const { nearestFields } = generateSelectorPath(p, targetFields)
+    expect(nearestFields).toMatchObject({ nearestId: 'target', nearestTag: 'P', nearestClass: 'container' })
+
+    const { path: selectorWithoutId } = generateSelectorPath(span)
     expect(selectorWithoutId).toBe('html>body>div#container>div>span:nth-of-type(1)')
   })
 
   test('should return undefined for null element', () => {
-    const selector = generateSelectorPath(null)
+    const { path: selector } = generateSelectorPath(null)
     expect(selector).toBeUndefined()
   })
 
   test('should handle elements with siblings', () => {
     const sibling = document.createElement('div')
     document.body.appendChild(sibling)
-    const selector = generateSelectorPath(sibling, { includeId: false, includeClass: false })
+    const { path: selector } = generateSelectorPath(sibling, targetFields)
     expect(selector).toBe('html>body>div:nth-of-type(2)')
     document.body.removeChild(sibling)
   })
 
   test('should handle elements without siblings', () => {
     const singleTable = document.createElement('table')
     document.body.appendChild(singleTable)
-    const selector = generateSelectorPath(singleTable, { includeId: false, includeClass: false })
+    const { path: selector, nearestFields } = generateSelectorPath(singleTable)
     expect(selector).toBe('html>body>table:nth-of-type(1)')
+    expect(nearestFields).toEqual({})
     document.body.removeChild(singleTable)
   })
 })

tools/testing-server/constants.js

@@ -77,5 +77,5 @@ module.exports.defaultInitBlock = {
   ssl: false,
   soft_navigations: enabledFeature,
   spa: enabledFeature,
-  user_actions: { enabled: true }
+  user_actions: { enabled: true, elementAttributes: ['id', 'className', 'tagName', 'type'] }
 }