Merge pull request #3 from EcomDev/feature/module

feat: Magento Module for RUM Beacon

Author: IvanChepurnyi

.gitignore

@@ -0,0 +1,2 @@
+/vendor/
+/node_modules/

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 EcomDev B.V.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

composer.json

@@ -0,0 +1,21 @@
+{
+  "name": "ecomdev/magento2-module-rum-beacon",
+  "description": "Magento 2 RUM Beacon",
+  "type": "magento2-module",
+  "require": {
+    "magento/framework": "*",
+    "magento/module-page-cache": "*",
+    "magento/module-catalog": "*"
+  },
+  "license": [
+    "MIT"
+  ],
+  "autoload": {
+    "files": [
+      "src/registration.php"
+    ],
+    "psr-4": {
+      "EcomDev\\RUMBeacon\\": "src/"
+    }
+  }
+}

lib/beacon.ts

@@ -0,0 +1,43 @@
+import {loadConfiguration} from "./configuration";
+import collectPageData from "./page-info";
+import {canSend, Payload, send} from "./payload";
+import timeToFirstByte from "./time-to-first-byte";
+import firstContentfulPaint from "./first-contentful-paint";
+import largestContentfulPaint from "./largest-contentful-paint";
+import comulativeLayoutShift from "./comulative-layout-shift";
+import interactionToNextPaint from "./interaction-to-next-paint";
+
+
+/**
+ * Main beacon routine
+ *
+ * Sets up event handers and send data to external service when page visibility changes
+ */
+function initializeIngestor() {
+    const config = loadConfiguration();
+
+    if (config === false) {
+        return;
+    }
+
+    const payload: Payload = {
+        pageInfo: collectPageData(config)
+    };
+
+    timeToFirstByte(payload);
+    firstContentfulPaint(payload);
+    largestContentfulPaint(payload);
+    comulativeLayoutShift(payload);
+    interactionToNextPaint(payload);
+
+    addEventListener('visibilitychange', () => {
+        if (document.visibilityState === 'hidden') {
+            if (canSend(payload)) {
+                send(config, payload)
+            }
+        }
+    });
+}
+
+// Make sure we don't block main thread on load
+setTimeout(initializeIngestor);

lib/common.ts

@@ -0,0 +1,3 @@
+export interface SimpleDictionary {
+    [Key: string]: string | number | boolean;
+}

lib/comulative-layout-shift.ts

@@ -0,0 +1,13 @@
+import {Payload} from "./payload";
+import {onCLS} from "web-vitals/attribution.js";
+
+export default function (payload: Payload) {
+    onCLS(metric => {
+        payload.cls = {
+            value: metric.value,
+            navigationType: metric.navigationType,
+            target: metric.attribution.largestShiftTarget ?? '',
+            time: metric.attribution.largestShiftTime ?? 0
+        }
+    })
+}

lib/configuration.ts

@@ -0,0 +1,28 @@
+import { SimpleDictionary } from "./common";
+
+interface AllowedQueryParameters {
+    [Key: string]: boolean,
+}
+
+export interface BeaconConfig {
+    allowedQueryParams: AllowedQueryParameters,
+    isEnabled: boolean,
+    isUrlCollected: boolean,
+    ingestionUrl: string,
+    pageInfo: SimpleDictionary
+}
+
+export function loadConfiguration(): BeaconConfig | false {
+    const beaconIngestElement = document.querySelector('script[type="ecomdev/rum-beacon-ingest"]');
+    if (!beaconIngestElement) {
+        return false;
+    }
+
+    const beaconConfig: BeaconConfig = JSON.parse(beaconIngestElement.textContent);
+
+    if (!beaconConfig.isEnabled || !beaconConfig.ingestionUrl || !beaconConfig.pageInfo) {
+        return false;
+    }
+
+    return beaconConfig;
+}

lib/first-contentful-paint.ts

@@ -0,0 +1,13 @@
+import {Payload} from "./payload";
+import {onFCP} from "web-vitals/attribution.js";
+
+export default function(payload: Payload) {
+    onFCP(metric => {
+        payload.fcp = {
+            value: metric.value,
+            navigationType: metric.navigationType,
+            renderDelay: metric.attribution.firstByteToFCP,
+            ttfb: metric.attribution.timeToFirstByte
+        }
+    })
+}

lib/interaction-to-next-paint.ts

@@ -0,0 +1,28 @@
+import {InteractionToNextPaint, Payload} from "./payload";
+import {onINP} from "web-vitals/attribution.js";
+
+export default function(payload: Payload) {
+    onINP(metric => {
+        const script = metric.attribution.longestScript;
+
+        const inp: InteractionToNextPaint = {
+            value: metric.value,
+            navigationType: metric.navigationType,
+            intersection: script?.intersectingDuration ?? 0,
+            target: metric.attribution.interactionTarget
+        }
+
+        if (script) {
+            try {
+                const url = new URL(script.entry.sourceURL);
+                inp.script_domain = url.host;
+                inp.script_path = url.pathname;
+            } catch (e) {
+            }
+
+            inp.affected_part = script.subpart;
+        }
+
+        payload.inp = inp;
+    })
+}

lib/largest-contentful-paint.ts

@@ -0,0 +1,17 @@
+import {Payload} from "./payload";
+import {onLCP} from "web-vitals/attribution.js";
+
+export default function(payload: Payload) {
+    onLCP(metric => {
+        payload.lcp = {
+            value: metric.value,
+            navigationType: metric.navigationType,
+            load: metric.attribution.resourceLoadDuration,
+            loadDelay: metric.attribution.resourceLoadDelay,
+            renderDelay: metric.attribution.elementRenderDelay,
+            ttfb: metric.attribution.timeToFirstByte,
+            target: metric.attribution.target ?? '',
+            url: metric.attribution.url ?? ''
+        }
+    })
+}