feat: Add API: setApplicationVersion (#639)

Co-authored-by: Patrick Housley <[email protected]>

Author: metal-messiah

package-lock.json

@@ -51,6 +51,18 @@ export class AgentBase {
     warn('Call to agent api setUserId failed. The js errors feature is not currently initialized.')
   }
 
+  /**
+   * Adds a user-defined application version string to subsequent events on the page.
+   * This decorates all payloads with an attribute of `application.version` which is queryable in NR1.
+   * {@link https://docs.newrelic.com/docs/browser/new-relic-browser/browser-apis/setapplicationversion/}
+   * @param {string|null} value A string identifier for the application version, useful for
+   * tying all browser events to a specific release tag. The value parameter does not
+   * have to be unique. Passing a null value unsets any existing value.
+   */
+  setApplicationVersion (value) {
+    warn('Call to agent api setApplicationVersion failed. The agent is not currently initialized.')
+  }
+
   /**
    * Allows selective ignoring and grouping of known errors that the browser agent captures.
    * {@link https://docs.newrelic.com/docs/browser/new-relic-browser/browser-apis/seterrorhandler/}

src/loaders/agent-base.js

@@ -0,0 +1,45 @@
+import { setAPI } from './api'
+import { setInfo, getInfo, setConfiguration } from '../../common/config/config'
+
+setInfo('abcd', { licenseKey: '1234', applicationID: '1234' })
+setConfiguration('abcd', {})
+let apiInterface
+beforeEach(() => {
+  console.warn = jest.fn()
+  apiInterface = setAPI('abcd', true)
+})
+
+afterEach(() => {
+  jest.restoreAllMocks()
+})
+
+describe('api', () => {
+  describe('setApplicationVersion', () => {
+    test('setApplicationVersion sets and unsets ja with valid values', () => {
+      apiInterface.setApplicationVersion('1.2.3')
+      expect(getInfo('abcd').jsAttributes).toMatchObject({ 'application.version': '1.2.3' })
+
+      apiInterface.setApplicationVersion(null)
+      expect(getInfo('abcd').jsAttributes).toMatchObject({ })
+    })
+
+    test('setApplicationVersion warns if invalid data is supplied', () => {
+      apiInterface.setApplicationVersion(1)
+      expect(console.warn).toHaveBeenCalledWith('New Relic: Failed to execute setApplicationVersion. Expected <String | null>, but got <number>.')
+
+      apiInterface.setApplicationVersion(false)
+      expect(console.warn).toHaveBeenCalledWith('New Relic: Failed to execute setApplicationVersion. Expected <String | null>, but got <boolean>.')
+
+      apiInterface.setApplicationVersion({ version: '1.2.3' })
+      expect(console.warn).toHaveBeenCalledWith('New Relic: Failed to execute setApplicationVersion. Expected <String | null>, but got <object>.')
+    })
+
+    test('setApplicationVersion replaces existing data if called twice', () => {
+      apiInterface.setApplicationVersion('1.2.3')
+      expect(getInfo('abcd').jsAttributes).toMatchObject({ 'application.version': '1.2.3' })
+
+      apiInterface.setApplicationVersion('4.5.6')
+      expect(getInfo('abcd').jsAttributes).toMatchObject({ 'application.version': '4.5.6' })
+    })
+  })
+})

src/loaders/api/api.component-test.js

@@ -21,7 +21,7 @@ export function setTopLevelCallers () {
   const funcs = [
     'setErrorHandler', 'finished', 'addToTrace', 'inlineHit', 'addRelease',
     'addPageAction', 'setCurrentRouteName', 'setPageViewName', 'setCustomAttribute',
-    'interaction', 'noticeError', 'setUserId'
+    'interaction', 'noticeError', 'setUserId', 'setApplicationVersion'
   ]
   funcs.forEach(f => {
     nr[f] = (...args) => caller(f, ...args)
@@ -109,6 +109,19 @@ export function setAPI (agentIdentifier, forceDrain) {
     return appendJsAttribute('enduser.id', value, 'setUserId', true)
   }
 
+  /**
+   * Attach the 'applcation.version' attribute onto agent payloads. This may be used in NR queries to group all browser events by a specific customer-defined release.
+   * @param {string|null} value - Application version -- if null, will "unset" the value
+   * @returns @see apiCall
+   */
+  apiInterface.setApplicationVersion = function (value) {
+    if (!(typeof value === 'string' || value === null)) {
+      warn(`Failed to execute setApplicationVersion. Expected <String | null>, but got <${typeof value}>.`)
+      return
+    }
+    return appendJsAttribute('application.version', value, 'setApplicationVersion', false)
+  }
+
   apiInterface.interaction = function () {
     return new InteractionHandle().get()
   }

src/loaders/api/api.js

@@ -32,6 +32,7 @@ const asyncApiFns = [
   'setPageViewName',
   'setCustomAttribute',
   'setUserId',
+  'setApplicationVersion',
   'setErrorHandler',
   'finished',
   'addToTrace',

tests/functional/uncat-internal-help.cjs

@@ -34,8 +34,8 @@
       "browserName": "MicrosoftEdge",
       "platformName": "Windows 11",
       "platform": "Windows 11",
-      "version": "105",
-      "browserVersion": "105"
+      "version": "106",
+      "browserVersion": "106"
     },
     {
       "browserName": "MicrosoftEdge",
@@ -48,8 +48,8 @@
       "browserName": "MicrosoftEdge",
       "platformName": "Windows 11",
       "platform": "Windows 11",
-      "version": "110",
-      "browserVersion": "110"
+      "version": "111",
+      "browserVersion": "111"
     },
     {
       "browserName": "MicrosoftEdge",
@@ -64,15 +64,15 @@
       "browserName": "firefox",
       "platformName": "Windows 10",
       "platform": "Windows 10",
-      "version": "106",
-      "browserVersion": "106"
+      "version": "107",
+      "browserVersion": "107"
     },
     {
       "browserName": "firefox",
       "platformName": "Windows 10",
       "platform": "Windows 10",
-      "version": "108",
-      "browserVersion": "108"
+      "version": "109",
+      "browserVersion": "109"
     },
     {
       "browserName": "firefox",