@adobe/spacecat-shared-rum-api-client 2.37.7 → 2.38.0

package/CHANGELOG.md

@@ -1,3 +1,17 @@
+# [@adobe/spacecat-shared-rum-api-client-v2.38.0](https://github.com/adobe/spacecat-shared/compare/@adobe/spacecat-shared-rum-api-client-v2.37.8...@adobe/spacecat-shared-rum-api-client-v2.38.0) (2025-10-07)
+
+
+### Features
+
+* add query for fetching RUM engagement metrics ([#985](https://github.com/adobe/spacecat-shared/issues/985)) ([0eb8881](https://github.com/adobe/spacecat-shared/commit/0eb88818af000076ea663b2e08ab1fb2b1957510))
+
+# [@adobe/spacecat-shared-rum-api-client-v2.37.8](https://github.com/adobe/spacecat-shared/compare/@adobe/spacecat-shared-rum-api-client-v2.37.7...@adobe/spacecat-shared-rum-api-client-v2.37.8) (2025-10-07)
+
+
+### Bug Fixes
+
+* **deps:** update dependency @adobe/rum-distiller to v1.19.1 ([#1004](https://github.com/adobe/spacecat-shared/issues/1004)) ([23446ad](https://github.com/adobe/spacecat-shared/commit/23446adeb9bfb2484885ac28b080b45bffe2d30c)), closes [#8203](https://github.com/adobe/spacecat-shared/issues/8203)
+
 # [@adobe/spacecat-shared-rum-api-client-v2.37.7](https://github.com/adobe/spacecat-shared/compare/@adobe/spacecat-shared-rum-api-client-v2.37.6...@adobe/spacecat-shared-rum-api-client-v2.37.7) (2025-09-25)
 
 

package/README.md

@@ -437,6 +437,28 @@ An example response:
 ]
 ```
 
+### User engagement
+
+Calculates user engagement metrics for all pages from RUM data. A page view is considered engaged if there has been at least some user interaction (click events) or significant content has been viewed (4 or more viewmedia or viewblock events).
+Ref. - https://github.com/adobe/rum-distiller/blob/22f8b3caa6d700f4d1cbe29a94b7da34b9d50764/series.js#L89
+
+An example response:
+
+```json
+[
+  {
+    "url": "https://www.example.com/home",
+    "totalTraffic": 5000,
+    "engagementPercentage": 50
+  },
+  {
+    "url": "https://www.example.com/about",
+    "totalTraffic": 2000,
+    "engagementPercentage": 40
+  }
+]
+```
+
 ## Linting
 Lint the codebase using:
 ```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adobe/spacecat-shared-rum-api-client",
-  "version": "2.37.7",
+  "version": "2.38.0",
   "description": "Shared modules of the Spacecat Services - Rum API client",
   "type": "module",
   "engines": {
@@ -38,7 +38,7 @@
     "@adobe/fetch": "4.2.3",
     "@adobe/helix-shared-wrap": "2.0.2",
     "@adobe/helix-universal": "5.2.3",
-    "@adobe/rum-distiller": "1.19.0",
+    "@adobe/rum-distiller": "1.19.1",
     "@adobe/spacecat-shared-utils": "1.48.0",
     "aws4": "1.13.2",
     "urijs": "1.19.11"

package/src/functions/user-engagement.js

@@ -0,0 +1,60 @@
+/*
+ * Copyright 2025 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.
+ */
+
+const evaluateEngagement = (bundle) => {
+  const clickEngagement = bundle.events.filter((evt) => evt.checkpoint === 'click').length > 0
+    ? bundle.weight
+    : 0;
+  const contentEngagement = bundle.events
+    .filter((evt) => evt.checkpoint === 'viewmedia' || evt.checkpoint === 'viewblock')
+    .length > 3
+    ? bundle.weight
+    : 0;
+  return clickEngagement || contentEngagement;
+};
+
+/**
+ * Calculates engagement metrics for all pages from RUM data.
+ * A page view is considered engaged if there has been at least some user interaction (click events)
+ * or significant content has been viewed (4 or more viewmedia or viewblock events).
+ * Ref. - https://github.com/adobe/rum-distiller/blob/22f8b3caa6d700f4d1cbe29a94b7da34b9d50764/series.js#L89
+ *
+ * @param {Array} bundles - The RUM bundles to calculate engagement metrics for.
+ * @returns {Array} An array of engagement metrics for each page.
+ */
+function handler(bundles) {
+  const urlsData = {};
+  bundles.forEach((bundle) => {
+    const engagementTraffic = evaluateEngagement(bundle);
+    if (!urlsData[bundle.url]) {
+      urlsData[bundle.url] = {
+        url: bundle.url,
+        totalTraffic: bundle.weight,
+        engagementTraffic,
+        engagementPercentage: (engagementTraffic / bundle.weight) * 100,
+      };
+    } else {
+      urlsData[bundle.url].totalTraffic += bundle.weight;
+      urlsData[bundle.url].engagementTraffic += engagementTraffic;
+      urlsData[bundle.url].engagementPercentage = Math.round(
+        (urlsData[bundle.url].engagementTraffic / urlsData[bundle.url].totalTraffic) * 100,
+      );
+    }
+  });
+
+  return Object.values(urlsData);
+}
+
+export default {
+  handler,
+  checkpoints: ['click', 'viewmedia', 'viewblock'],
+};

package/src/index.js

@@ -27,6 +27,7 @@ import highOrganicLowCtr from './functions/opportunities/high-organic-low-ctr.js
 import trafficAnalysis from './functions/traffic-analysis.js';
 import optimizationReportMetrics from './functions/reports/optimization/metrics.js';
 import optimizationReportGraph from './functions/reports/optimization/graph.js';
+import userEngagement from './functions/user-engagement.js';
 
 // exported for tests
 export const RUM_BUNDLER_API_HOST = 'https://bundles.aem.page';
@@ -48,6 +49,7 @@ const HANDLERS = {
   'traffic-analysis': trafficAnalysis,
   'optimization-report-metrics': optimizationReportMetrics,
   'optimization-report-graph': optimizationReportGraph,
+  'user-engagement': userEngagement,
 };
 
 function sanitize(opts) {