@adobe/spacecat-shared-rum-api-client 2.8.0 → 2.9.1

package/CHANGELOG.md

@@ -1,3 +1,17 @@
+# [@adobe/spacecat-shared-rum-api-client-v2.9.1](https://github.com/adobe/spacecat-shared/compare/@adobe/spacecat-shared-rum-api-client-v2.9.0...@adobe/spacecat-shared-rum-api-client-v2.9.1) (2024-09-14)
+
+
+### Bug Fixes
+
+* **deps:** update external fixes ([#369](https://github.com/adobe/spacecat-shared/issues/369)) ([5412d7b](https://github.com/adobe/spacecat-shared/commit/5412d7be554b9940d43b39b18f2913146e866846))
+
+# [@adobe/spacecat-shared-rum-api-client-v2.9.0](https://github.com/adobe/spacecat-shared/compare/@adobe/spacecat-shared-rum-api-client-v2.8.0...@adobe/spacecat-shared-rum-api-client-v2.9.0) (2024-09-03)
+
+
+### Features
+
+* experimentation opportunities ([#351](https://github.com/adobe/spacecat-shared/issues/351)) ([f21a765](https://github.com/adobe/spacecat-shared/commit/f21a765996990b1748c11b0cd8089e87ec91d9ad))
+
 # [@adobe/spacecat-shared-rum-api-client-v2.8.0](https://github.com/adobe/spacecat-shared/compare/@adobe/spacecat-shared-rum-api-client-v2.7.4...@adobe/spacecat-shared-rum-api-client-v2.8.0) (2024-08-26)
 
 

package/README.md

@@ -191,6 +191,92 @@ An example response:
 
 ```
 
+### high-inorganic-high-bounce-rate (Experimentation Opportunity)
+
+Calculates the amount of inorganic traffic and the bounce rate for each page. Identifies pages with both high inorganic traffic and high bounce rates, which can be targeted for future experimentation opportunities. An example payload is provided below:
+
+```json
+[
+  {
+    "type": "high-inorganic-high-bounce-rate",
+    "page": "https://www.spacecat.com/",
+    "screenshot": "",
+    "trackedPageKPIName": "Bounce Rate",
+    "trackedPageKPIValue": 0.6507592190889371,
+    "pageViews": 46100,
+    "samples": 46100,
+    "metrics": [
+      {
+        "type": "traffic",
+        "value": {
+          "total": 46100,
+          "paid": 40700,
+          "owned": 5400,
+          "earned": 0
+        }
+      }
+    ]
+  },
+  {
+    "type": "high-inorganic-high-bounce-rate",
+    "page": "https://www.spacecat.com/pricing",
+    "screenshot": "",
+    "trackedPageKPIName": "Bounce Rate",
+    "trackedPageKPIValue": 0.8723897911832946,
+    "pageViews": 43100,
+    "samples": 43100,
+    "metrics": [
+      {
+        "type": "traffic",
+        "value": {
+          "total": 43100,
+          "paid": 24100,
+          "owned": 19000,
+          "earned": 0
+        }
+      }
+    ]
+  }
+]
+```
+
+### high-organic-low-ctr (Experimentation Opportunity)
+
+Calculates the amount of non-inorganic (earned and owned) traffic and the click-through rate for each page. Identifies pages with high non-inorganic traffic and low click-through rates, which can be targeted for future experimentation opportunities. An example payload is provided below:
+
+```json
+[
+  {
+    "type": "high-organic-low-ctr",
+    "page": "https://www.spacecat.com/about-us",
+    "screenshot": "",
+    "trackedPageKPIName": "Click Through Rate",
+    "trackedPageKPIValue": 0.14099783080260303,
+    "pageViews": 46100,
+    "samples": 46100,
+    "metrics": [
+      {
+        "type": "traffic",
+        "value": {
+          "total": 46100,
+          "paid": 0,
+          "owned": 46100,
+          "earned": 0
+        }
+      },
+      {
+        "type": "ctr",
+        "value": {
+          "page": 0.14099783080260303,
+          "siteAverage": 0.4077909270216962
+        }
+      }
+    ]
+  }
+]
+
+```
+
 ## Linting
 Lint the codebase using:
 ```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adobe/spacecat-shared-rum-api-client",
-  "version": "2.8.0",
+  "version": "2.9.1",
   "description": "Shared modules of the Spacecat Services - Rum API client",
   "type": "module",
   "engines": {
@@ -39,7 +39,7 @@
     "@adobe/helix-shared-wrap": "2.0.2",
     "@adobe/helix-universal": "5.0.5",
     "@adobe/spacecat-shared-utils": "1.4.0",
-    "aws4": "1.13.1",
+    "aws4": "1.13.2",
     "d3-array": "3.2.4",
     "urijs": "^1.19.11"
   },
@@ -47,8 +47,8 @@
     "chai": "5.1.1",
     "chai-as-promised": "8.0.0",
     "nock": "13.5.5",
-    "sinon": "18.0.0",
+    "sinon": "18.0.1",
     "sinon-chai": "4.0.0",
-    "typescript": "5.5.4"
+    "typescript": "5.6.2"
   }
 }

package/src/common/aggregateFns.js

@@ -23,6 +23,60 @@ function pageviewsByUrl(bundles) {
   }, {});
 }
 
+/**
+ * Calculates the Click-Through Rate (CTR) by URL.
+ * CTR is defined as the total number of sessions with at least one click event
+ * divided by the total number of pageviews for each URL.
+ *
+ * @param {Array<Object>} bundles - An array of RUM bundles (NOT Flat bundles).
+ * @returns {Object} - An object where the key is the URL and the value is the CTR value.
+ */
+function getCTRByUrl(bundles) {
+  const aggregated = bundles.reduce((acc, bundle) => {
+    const { url } = bundle;
+    if (!acc[url]) {
+      acc[url] = { sessionsWithClick: 0, totalPageviews: 0 };
+    }
+    const hasClick = bundle.events.some((event) => event.checkpoint === 'click');
+
+    acc[url].totalPageviews += bundle.weight;
+    if (hasClick) {
+      acc[url].sessionsWithClick += bundle.weight;
+    }
+    return acc;
+  }, {});
+  return Object.entries(aggregated)
+    .reduce((acc, [url, { sessionsWithClick, totalPageviews }]) => {
+      acc[url] = (sessionsWithClick / totalPageviews);
+      return acc;
+    }, {});
+}
+
+/**
+ * Calculates the Click-Through Rate (CTR) average for the entire site.
+ * CTR is defined as the total number of sessions with at least one click event
+ * divided by the total number of pageviews for the entire site.
+ *
+ * @param {Array<Object>} bundles - An array of RUM bundles (NOT Flat bundles).
+ * @returns {number} - Average CTR for the site.
+ */
+function getSiteAvgCTR(bundles) {
+  const aggregated = bundles.reduce((acc, bundle) => {
+    const hasClick = bundle.events.some((event) => event.checkpoint === 'click');
+    acc.totalPageviews += bundle.weight;
+    if (hasClick) {
+      acc.sessionsWithClick += bundle.weight;
+    }
+    return acc;
+  }, { sessionsWithClick: 0, totalPageviews: 0 });
+
+  return aggregated.totalPageviews === 0
+    ? 0
+    : aggregated.sessionsWithClick / aggregated.totalPageviews;
+}
+
 export {
+  getSiteAvgCTR,
+  getCTRByUrl,
   pageviewsByUrl,
 };

package/src/functions/opportunities/high-inorganic-high-bounce-rate.js

@@ -0,0 +1,74 @@
+/*
+ * Copyright 2024 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.
+ */
+
+import trafficAcquisition from '../traffic-acquisition.js';
+import { getCTRByUrl } from '../../common/aggregateFns.js';
+
+const HOMEPAGE_PAID_TRAFFIC_THRESHOLD = 0.8;
+const NON_HOMEPAGE_PAID_TRAFFIC_THRESHOLD = 0.5;
+const BOUNCE_RATE_THRESHOLD = 0.5;
+const DAILY_PAGEVIEW_THRESHOLD = 1000;
+
+function convertToOpportunity(traffic) {
+  const {
+    url, total, bounceRate, paid, earned, owned,
+  } = traffic;
+
+  return {
+    type: 'high-inorganic-high-bounce-rate',
+    page: url,
+    screenshot: '',
+    trackedPageKPIName: 'Bounce Rate',
+    trackedPageKPIValue: bounceRate,
+    pageViews: total,
+    samples: total, // todo: get the actual number of samples
+    metrics: [{
+      type: 'traffic',
+      value: {
+        total,
+        paid,
+        owned,
+        earned,
+      },
+    }],
+  };
+}
+
+function hasHighInorganicTraffic(traffic) {
+  const { url, paid, total } = traffic;
+  const isHomepage = new URL(url).pathname === '/';
+  const threshold = isHomepage
+    ? HOMEPAGE_PAID_TRAFFIC_THRESHOLD
+    : NON_HOMEPAGE_PAID_TRAFFIC_THRESHOLD;
+  return paid / total > threshold;
+}
+
+function hasHighBounceRate(ctr) {
+  return ctr < BOUNCE_RATE_THRESHOLD;
+}
+
+function handler(bundles, opts = {}) {
+  const { interval = 7 } = opts;
+  const trafficByUrl = trafficAcquisition.handler(bundles);
+  const ctrByUrl = getCTRByUrl(bundles);
+
+  return trafficByUrl.filter((traffic) => traffic.total > interval * DAILY_PAGEVIEW_THRESHOLD)
+    .filter(hasHighInorganicTraffic)
+    .filter((traffic) => hasHighBounceRate(ctrByUrl[traffic.url]))
+    .map((traffic) => ({ ...traffic, bounceRate: 1 - ctrByUrl[traffic.url] }))
+    .map(convertToOpportunity);
+}
+
+export default {
+  handler,
+  checkpoints: ['email', 'enter', 'paid', 'utm', 'click', 'experiment'],
+};

package/src/functions/opportunities/high-organic-low-ctr.js

@@ -0,0 +1,77 @@
+/*
+ * Copyright 2024 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.
+ */
+
+import trafficAcquisition from '../traffic-acquisition.js';
+import { getCTRByUrl, getSiteAvgCTR } from '../../common/aggregateFns.js';
+
+const DAILY_EARNED_THRESHOLD = 5000;
+const CTR_THRESHOLD_RATIO = 0.95;
+const DAILY_PAGEVIEW_THRESHOLD = 1000;
+
+function convertToOpportunity(traffic) {
+  const {
+    url, total, ctr, paid, owned, earned, siteAvgCTR,
+  } = traffic;
+
+  return {
+    type: 'high-organic-low-ctr',
+    page: url,
+    screenshot: '',
+    trackedPageKPIName: 'Click Through Rate',
+    trackedPageKPIValue: ctr,
+    pageViews: total,
+    samples: total, // todo: get the actual number of samples
+    metrics: [{
+      type: 'traffic',
+      value: {
+        total,
+        paid,
+        owned,
+        earned,
+      },
+    }, {
+      type: 'ctr',
+      value: {
+        page: ctr,
+        siteAverage: siteAvgCTR,
+      },
+    }],
+  };
+}
+
+function hasHighOrganicTraffic(interval, traffic) {
+  const { earned, owned } = traffic;
+  return earned + owned > DAILY_EARNED_THRESHOLD * interval;
+}
+
+function hasLowerCTR(ctr, siteAvgCTR) {
+  return ctr < CTR_THRESHOLD_RATIO * siteAvgCTR;
+}
+
+function handler(bundles, opts = {}) {
+  const { interval = 7 } = opts;
+
+  const trafficByUrl = trafficAcquisition.handler(bundles);
+  const ctrByUrl = getCTRByUrl(bundles);
+  const siteAvgCTR = getSiteAvgCTR(bundles);
+
+  return trafficByUrl.filter((traffic) => traffic.total > interval * DAILY_PAGEVIEW_THRESHOLD)
+    .filter(hasHighOrganicTraffic.bind(null, interval))
+    .filter((traffic) => hasLowerCTR(ctrByUrl[traffic.url], siteAvgCTR))
+    .map((traffic) => ({ ...traffic, ctr: ctrByUrl[traffic.url], siteAvgCTR }))
+    .map(convertToOpportunity);
+}
+
+export default {
+  handler,
+  checkpoints: ['email', 'enter', 'paid', 'utm', 'click', 'experiment'],
+};

package/src/functions/traffic-acquisition.js

@@ -12,6 +12,8 @@
 
 import { classifyTrafficSource } from '../common/traffic.js';
 
+const MAIN_TYPES = ['total', 'paid', 'earned', 'owned'];
+
 function extractHints(bundle) {
   const findEvent = (checkpoint, source = '') => bundle.events.find((e) => e.checkpoint === checkpoint && (!source || e.source === source)) || {};
 
@@ -31,9 +33,12 @@ function extractHints(bundle) {
 }
 
 function collectByUrlAndTrafficSource(acc, { url, weight, trafficSource }) {
-  acc[url] = acc[url] || { total: 0 };
+  acc[url] = acc[url] || {
+    total: 0, owned: 0, earned: 0, paid: 0,
+  };
   acc[url][trafficSource] = (acc[url][trafficSource] || 0) + weight;
   acc[url].total += weight;
+  acc[url][trafficSource.split(':')[0]] += weight;
   return acc;
 }
 
@@ -41,13 +46,16 @@ function transformFormat(trafficSources) {
   return Object.entries(trafficSources).map(([url, value]) => ({
     url,
     total: value.total,
+    earned: value.earned,
+    owned: value.owned,
+    paid: value.paid,
     sources: Object.entries(value)
-      .filter(([source]) => source !== 'total')
+      .filter(([source]) => !MAIN_TYPES.includes(source))
       .map(([source, views]) => ({ type: source, views })),
   }));
 }
 
-async function handler(bundles) {
+function handler(bundles) {
   const trafficSources = bundles
     .map(extractHints)
     .map((row) => {

package/src/index.js

@@ -15,7 +15,9 @@ import cwv from './functions/cwv.js';
 import experiment from './functions/experiment.js';
 import trafficAcquisition from './functions/traffic-acquisition.js';
 import variant from './functions/variant.js';
-import rageclick from './functions/rageclick.js';
+import rageclick from './functions/opportunities/rageclick.js';
+import highInorganicHighBounceRate from './functions/opportunities/high-inorganic-high-bounce-rate.js';
+import highOrganicLowCtr from './functions/opportunities/high-organic-low-ctr.js';
 
 const HANDLERS = {
   404: notfound,
@@ -24,6 +26,8 @@ const HANDLERS = {
   'traffic-acquisition': trafficAcquisition,
   variant,
   rageclick,
+  'high-inorganic-high-bounce-rate': highInorganicHighBounceRate,
+  'high-organic-low-ctr': highOrganicLowCtr,
 };
 
 export default class RUMAPIClient {
@@ -80,7 +84,7 @@ export default class RUMAPIClient {
       // Execute each query handler sequentially
       for (const { query, handler } of queryHandlers) {
         // eslint-disable-next-line no-await-in-loop
-        results[query] = await handler(bundles);
+        results[query] = await handler(bundles, opts);
       }
 
       return results;