@adobe/spacecat-shared-rum-api-client 2.41.0 → 2.42.0

package/CHANGELOG.md

@@ -1,3 +1,16 @@
+## [@adobe/spacecat-shared-rum-api-client-v2.42.0](https://github.com/adobe/spacecat-shared/compare/@adobe/spacecat-shared-rum-api-client-v2.41.1...@adobe/spacecat-shared-rum-api-client-v2.42.0) (2026-06-09)
+
+### Features
+
+* Add per-field engagement metrics for forms ([#1653](https://github.com/adobe/spacecat-shared/issues/1653)) ([b6dba5b](https://github.com/adobe/spacecat-shared/commit/b6dba5bd9abb623aecf2d3f5d8e1e36bf427a919))
+
+## [@adobe/spacecat-shared-rum-api-client-v2.41.1](https://github.com/adobe/spacecat-shared/compare/@adobe/spacecat-shared-rum-api-client-v2.41.0...@adobe/spacecat-shared-rum-api-client-v2.41.1) (2026-05-29)
+
+### Bug Fixes
+
+* **deps:** update adobe fixes ([#1609](https://github.com/adobe/spacecat-shared/issues/1609)) ([ccdcc2b](https://github.com/adobe/spacecat-shared/commit/ccdcc2b88c1b03e5c58ed682daaaadb382638395))
+* **deps:** update external major (major) ([#1611](https://github.com/adobe/spacecat-shared/issues/1611)) ([5a80797](https://github.com/adobe/spacecat-shared/commit/5a807979187f1ebcc32b088faee9165aa38cc461))
+
 ## [@adobe/spacecat-shared-rum-api-client-v2.41.0](https://github.com/adobe/spacecat-shared/compare/@adobe/spacecat-shared-rum-api-client-v2.40.13...@adobe/spacecat-shared-rum-api-client-v2.41.0) (2026-05-21)
 
 ### Features

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adobe/spacecat-shared-rum-api-client",
-  "version": "2.41.0",
+  "version": "2.42.0",
   "description": "Shared modules of the Spacecat Services - Rum API client",
   "type": "module",
   "engines": {
@@ -37,7 +37,7 @@
   "dependencies": {
     "@adobe/fetch": "4.3.0",
     "@adobe/helix-shared-wrap": "2.0.2",
-    "@adobe/helix-universal": "5.4.1",
+    "@adobe/helix-universal": "5.4.2",
     "@adobe/rum-distiller": "1.23.0",
     "@adobe/spacecat-shared-utils": "1.81.1",
     "aws4": "1.13.2",
@@ -47,7 +47,7 @@
     "chai": "6.2.2",
     "chai-as-promised": "8.0.2",
     "nock": "14.0.15",
-    "sinon": "21.1.2",
+    "sinon": "22.0.0",
     "sinon-chai": "4.0.1",
     "typescript": "6.0.3"
   }

package/src/functions/form-field-engagement.js

@@ -0,0 +1,106 @@
+/*
+ * Copyright 2026 Adobe. All rights reserved.
+ * This file is licensed to you under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License. You may obtain a copy
+ * of the License at http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software distributed under
+ * the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS
+ * OF ANY KIND, either express or implied. See the License for the specific language
+ * governing permissions and limitations under the License.
+ */
+
+// Per-field form engagement helper. NOT a RUM query — invoked from form-vitals.js to
+// attach a `fieldEngagement` property to each form-vitals entry (like trafficacquisition).
+
+import { FORM_KEYWORDS_TO_FILTER, isFormSource } from '../utils.js';
+
+const average = (nums) => (nums.length ? nums.reduce((a, b) => a + b, 0) / nums.length : 0);
+
+const isSearchEvent = (event) => FORM_KEYWORDS_TO_FILTER.some(
+  (kw) => event.source?.toLowerCase().includes(kw) || event.target?.toLowerCase().includes(kw),
+);
+
+/**
+ * Average time (in seconds) spent on a field before the next interaction.
+ * Direct port of time_spent_in_seconds() from forms-analysis-automation:
+ * within each bundle, sort events by timeDelta; for every click/fill on this
+ * selector, take the gap to the next event; average the gaps and convert ms → s.
+ */
+function timeSpentInSeconds(urlBundles, selector) {
+  const deltaDiffs = [];
+  for (const bundle of urlBundles) {
+    const sortedEvents = [...bundle.events].sort((a, b) => a.timeDelta - b.timeDelta);
+    for (let i = 0; i < sortedEvents.length - 1; i += 1) {
+      const event = sortedEvents[i];
+      if ((event.checkpoint === 'click' || event.checkpoint === 'fill')
+        && event.source === selector) {
+        deltaDiffs.push(sortedEvents[i + 1].timeDelta - event.timeDelta);
+      }
+    }
+  }
+  return Math.round((average(deltaDiffs) / 1000) * 100) / 100;
+}
+
+/** Average absolute timeDelta of a field's click/fill events — used for output ordering. */
+function avgInteractionTime(urlBundles, selector) {
+  const times = [];
+  for (const bundle of urlBundles) {
+    for (const event of bundle.events) {
+      if ((event.checkpoint === 'click' || event.checkpoint === 'fill')
+        && event.source === selector && event.timeDelta != null) {
+        times.push(event.timeDelta);
+      }
+    }
+  }
+  return average(times);
+}
+
+/**
+ * Single-traversal collection of weighted click/fill counts per field selector.
+ * Returns a Map<source, { clicks, fills }> for all form-scoped field events.
+ */
+function getFieldMetrics(urlBundles, formSourceKey) {
+  const metricsMap = new Map();
+  for (const bundle of urlBundles) {
+    for (const event of bundle.events) {
+      if ((event.checkpoint === 'click' || event.checkpoint === 'fill')
+        && event.source && !isSearchEvent(event)
+        && isFormSource(formSourceKey, event.source)) {
+        if (!metricsMap.has(event.source)) {
+          metricsMap.set(event.source, { clicks: 0, fills: 0 });
+        }
+        const metrics = metricsMap.get(event.source);
+        if (event.checkpoint === 'click') {
+          metrics.clicks += bundle.weight;
+        } else {
+          metrics.fills += bundle.weight;
+        }
+      }
+    }
+  }
+  return metricsMap;
+}
+
+/**
+ * Computes per-field engagement for a single form on a page.
+ *
+ * @param {Array} urlBundles - RUM bundles already filtered to the form's page URL
+ * @param {string} formSourceKey - form key extracted from the form source (e.g. 'abc'
+ *   for 'form#abc'), or 'unknown'
+ * @returns {Array<{source: string, clicks: number, fills: number, avg_time_spend: number}>}
+ *   fields ordered by average absolute timeDelta (natural form interaction order)
+ */
+export function computeFieldEngagement(urlBundles, formSourceKey) {
+  const fieldMetrics = getFieldMetrics(urlBundles, formSourceKey);
+
+  return [...fieldMetrics.keys()]
+    .map((source) => ({
+      source,
+      clicks: fieldMetrics.get(source).clicks,
+      fills: fieldMetrics.get(source).fills,
+      avg_time_spend: timeSpentInSeconds(urlBundles, source),
+    }))
+    .sort((a, b) => avgInteractionTime(urlBundles, a.source)
+      - avgInteractionTime(urlBundles, b.source));
+}

package/src/functions/form-vitals.js

@@ -12,7 +12,10 @@
 
 import { DataChunks, facets } from '@adobe/rum-distiller';
 import trafficAcquisition from './traffic-acquisition.js';
-import { DELIMITER, generateKey, loadBundles } from '../utils.js';
+import { computeFieldEngagement } from './form-field-engagement.js';
+import {
+  DELIMITER, generateKey, loadBundles, isFormSource,
+} from '../utils.js';
 
 const METRICS = ['formview', 'formengagement', 'formsubmit'];
 const CHECKPOINTS = ['viewblock', 'click', 'fill', 'formsubmit', 'navigate', 'viewmedia', 'experiment'];
@@ -53,15 +56,6 @@ function filterEvents(bundles) {
   }));
 }
 
-function isFormSource(source, eventSource) {
-  const excludeSrc = ['form.', 'form#'];
-  if (source === 'unknown') {
-    return /\bform\b/.test(eventSource?.toLowerCase()) && !excludeSrc.some((exclude) => eventSource?.includes(exclude));
-  } else {
-    return eventSource?.includes(source);
-  }
-}
-
 const metricFns = {
   formview: (source) => (bundle) => {
     const formView = bundle.events.find((e) => e.checkpoint === 'viewblock' && isFormSource(source, e.source));
@@ -321,6 +315,13 @@ function handler(bundles) {
         iframeSrc,
       });
     }
+    // attach per-field engagement for this form (mirrors the trafficacquisition property)
+    const fieldMatch = formVitalCopy.formsource?.match(/form[#.]((?:\\[0-9a-fA-F]{1,6}\s?|\w|-)+)/);
+    const fieldFormSourceKey = fieldMatch ? fieldMatch[1] : 'unknown';
+    formVitalCopy.fieldEngagement = computeFieldEngagement(
+      bundles.filter((b) => b.url === formVitalCopy.url),
+      fieldFormSourceKey,
+    );
     return formVitalCopy;
   });
 

package/src/utils.js

@@ -16,6 +16,21 @@ import { classifyTraffic } from './common/traffic.js';
 
 export const DELIMITER = '≡';
 
+export const FORM_KEYWORDS_TO_FILTER = ['search'];
+
+/**
+ * Checks whether a bundle event's source belongs to the given form source key.
+ * Shared between form-vitals.js and form-field-engagement.js.
+ */
+export function isFormSource(source, eventSource) {
+  const excludeSrc = ['form.', 'form#'];
+  if (source === 'unknown') {
+    return /\bform\b/.test(eventSource?.toLowerCase()) && !excludeSrc.some((exclude) => eventSource?.includes(exclude));
+  } else {
+    return eventSource?.includes(source);
+  }
+}
+
 export const generateKey = (...keys) => keys.join(DELIMITER);
 
 export const trafficSeriesFn = (memo, type) => (bundle) => {