controllers/rum_controller.js

  1. import { Controller } from "@hotwired/stimulus"
  2. import Perfume from "perfume.js"
  4. /**
  5.  * @class RUMController
  6.  * @classdesc Stimulus controller to track Core Vitals and display results on page.
  7.  * @extends Controller
  8.  */
  9. export default class extends Controller {
  10.   /**
  11.    * Will be set on `initialize` with the current Unix timestamp in milliseconds
  12.    * 
  13.    * @type {Number}
  14.    * @memberof RUMController
  15.    */
  16.   rumIdentifier
  18.   /**
  19.    * @property {Function} footer - targets the normal footer section
  20.    * @property {Function} vitalsButton - targets the button to display CWV
  21.    * @property {Function} metrics - targets the CWV section
  22.    * @property {Function} lcp - targets the text result of LCP
  23.    * @property {Function} fid - targets the text result of FID
  24.    * @property {Function} cls - targets the text result of CLS
  25.    * @memberof RUMController
  26.    * @static
  27.    */
  28.   static targets = [ "footer", "vitalsButton", "metrics", "lcp", "fid", "cls" ]
  30.   /**
  31.    * @property {Object} lcp - holds LCP data eg {"data":1201.705,"vitalsScore":"good"}
  32.    * @property {Object} fid - holds FID data eg {"data":1.305,"vitalsScore":"good"}
  33.    * @property {Object} cls - holds CLS data eg {"data":0.0049,"vitalsScore":"good"}
  34.    * @memberof RUMController
  35.    * @static
  36.    */
  37.   static values = { 
  38.     lcp: Object,
  39.     fid: Object,
  40.     cls: Object
  41.   }
  43.   /**
  44.    * @property {String} success - targets the CSS to use for success highlighting on border and text
  45.    * @property {String} warning - targets the CSS to use for warning highlighting on border and text
  46.    * @property {String} error - targets the CSS to use for error highlighting on border and text
  47.    * @memberof RUMController
  48.    * @static
  49.    */
  50.   static classes = [ "success", "warning", "error" ]
  52.   /** 
  53.    * Initialises perfume.js only on DOMContentLoaded. The CWV's are only available on a full page
  54.    * load so this prevents the initialisation on Turbo drive navigations
  55.    *
  56.    * @instance
  57.    * @memberof RUMController
  58.    * @returns {void} N/A
  59.    * */
  60.   initialize() {
  61.     this.rumIdentifier = Date.now()
  62.     // Test for presence of one Core Web Vital metric and display button if present. This is currently
  63.     // a good indicator of Chromium which only support Core Web Vitals metrics
  64.     if (window.LayoutShift) this.vitalsButtonTarget.style.display = "block"
  65.     window.addEventListener("DOMContentLoaded", (event) => {
  66.       try {
  67.         new Perfume({
  68.           analyticsTracker: (options) => {
  69.             const { metricName, data, vitalsScore } = options
  70.       
  71.             switch (metricName) {
  72.               case "navigationTiming":
  73.                 if (data && data.timeToFirstByte) {
  74.                   this.rumLogger("ttfb", data.timeToFirstByte)
  75.                 }
  76.                 break;
  77.               case "networkInformation":
  78.                 if (data && data.effectiveType) {
  79.                   this.rumLogger("networkInfo", data.effectiveType)
  80.                 }
  81.                 break;
  82.               case "fcp":
  83.                 this.rumLogger("fcp", data, vitalsScore)
  84.                 break;
  85.               case "lcp":
  86.                 this.rumLogger("lcp", data, vitalsScore)
  87.                 this.lcpValue = { data, vitalsScore }
  88.                 break;
  89.               case "fid":
  90.                 this.rumLogger("fid", data, vitalsScore)
  91.                 this.fidValue = { data, vitalsScore }
  92.                 break;
  93.               case "cls":
  94.                 this.rumLogger("cls", data, vitalsScore)
  95.                 this.clsValue = { data, vitalsScore }
  96.                 break;
  97.             }
  98.           }
  99.         })
  100.       }
  101.       catch(error) {}
  102.     })
  103.   }
  105.   /** 
  106.    * Displays the normal footer again when the controller disconnects and hides the CWV section
  107.    *
  108.    * @instance
  109.    * @memberof RUMController
  110.    * @returns {void} N/A
  111.    * */
  112.   disconnect() {
  113.     this.footerTarget.style.display = "block"
  114.     this.metricsTarget.style.display = "none"
  115.   }
  117.   /** 
  118.    * Displays the CWV section in the footer and hides the normal footer
  119.    *
  120.    * @instance
  121.    * @memberof RUMController
  122.    * @returns {void} N/A
  123.    * */
  124.   reveal() {
  125.     this.footerTarget.style.display = "none"
  126.     this.metricsTarget.style.display = "block"
  127.     if (window.fathom) fathom.trackGoal("0YWFGYIZ", 0)
  128.   }
  130.   /** 
  131.    * Sends the Real User Metric data to a Netlify background function.
  132.    * 
  133.    * Netlify background functions will immediately return a 202 to indicate that the bckground function
  134.    * has been triggered but we are not to wait for a result as the function will be queued and could
  135.    * take as much as 15 mins to run.
  136.    *
  137.    * @instance rumLogger
  138.    * @property {String} metric - string identifying the RUM metric
  139.    * @property {(String|Number)} data - value associated with the metric
  140.    * @property {String} [vitalsScore] - CWV reading of good, needs improvement or poor
  141.    * 
  142.    * @memberof RUMController
  143.    * @returns {void} N/A
  144.    * @see visitorIsBot
  145.    * @see postRumLoggerData
  146.    * 
  147.    * @example
  148.    * this.rumLogger("cls", 0, "good")
  149.    * @example
  150.    * this.rumLogger("networkInformation", "4g")
  151.    * */
  152.   rumLogger(metric, data, vitals_score = null) {
  153.     const { data_float, data_string } = this.organiseDataBasedOnMetric(metric, data)
  154.     const rumData = {
  155.       identifier: this.rumIdentifier,
  156.       path: window.location.pathname,
  157.       time_zone: Intl.DateTimeFormat().resolvedOptions().timeZone,
  158.       time_stamp: new Date().toISOString(),
  159.       user_agent: window.navigator.userAgent,
  160.       metric,
  161.       data_float,
  162.       data_string,
  163.       vitals_score
  164.     }
  165.     if (this.visitorIsBot(rumData.user_agent)) return
  166.     window.pushr.log({ event: "rum", data: rumData })
  167.   }
  169.   /** 
  170.    * The rum metric could be a float or string and I want to store it appropriately in supabase so
  171.    * this will populate 2 different fields depending on the metric
  172.    *
  173.    * @instance organiseDataBasedOnMetric
  174.    * @property {String} metric - the userAgent string
  175.    * @property {String|Number} data - the userAgent string
  176.    * 
  177.    * @memberof RUMController
  178.    * @returns {Object}
  179.    * */
  180.   organiseDataBasedOnMetric(metric, data) {
  181.     if (metric === "networkInfo") return { data_float: null, data_string: data }
  182.     return { data_float: data, data_string: null }
  183.   }
  185.   /** 
  186.    * Checks if the part of the user_agent matches against one of the given bot names
  187.    *
  188.    * @instance visitorIsBot
  189.    * @property {String} userAgent - the userAgent string
  190.    * 
  191.    * @memberof RUMController
  192.    * @returns {Boolean}
  193.    * */
  194.   visitorIsBot(user_agent) {
  195.     const botNames = [
  196.       "Googlebot" ,"Bingbot", "Slurp", "DuckDuckBot", "Baiduspider", "YandexBot", "Sogou", "Exabot"
  197.     ]
  198.     if (botNames.some(name => user_agent.includes(name))) return true
  199.   }
  201.   /** 
  202.    * LCP value change callback which calls coreWebVitalResponse
  203.    *
  204.    * @instance lcpValueChanged
  205.    * @memberof RUMController
  206.    * @returns {void} N/A
  207.    * @see coreWebVitalResponse
  208.    * */
  209.   lcpValueChanged() {
  210.     this.coreWebVitalResponse("lcp", this.lcpValue, this.lcpTarget)
  211.   }
  213.   /** 
  214.    * FID value change callback which calls coreWebVitalResponse
  215.    *
  216.    * @instance fidValueChanged
  217.    * @memberof RUMController
  218.    * @returns {void} N/A
  219.    * @see coreWebVitalResponse
  220.    * */
  221.   fidValueChanged() {
  222.     this.coreWebVitalResponse("fid", this.fidValue, this.fidTarget)
  223.   }
  225.   /** 
  226.    * CLS value change callback which calls coreWebVitalResponse
  227.    *
  228.    * @instance clsValueChanged
  229.    * @memberof RUMController
  230.    * @returns {void} N/A
  231.    * @see coreWebVitalResponse
  232.    * */
  233.   clsValueChanged() {
  234.     this.coreWebVitalResponse("cls", this.clsValue, this.clsTarget)
  235.   }
  237.   /** 
  238.    * Returns if no value object present. This will happen on the first runs of the value change callbacks
  239.    * on initial page load.
  240.    * 
  241.    * Adds a relevent class for the alert colour.
  242.    * 
  243.    * Replaces the `... waiting` text with the CWV score.
  244.    *
  245.    * @instance coreWebVitalResponse
  246.    * @property {String} cwv - string identifying the CWV
  247.    * @property {Object} value - CWV object with score and reading of good, needs improvement or poor
  248.    * @property {String} target - string identifying the target in the DOM 
  249.    * 
  250.    * @memberof RUMController
  251.    * @returns {void} N/A
  252.    * @see alertColor
  253.    * @see alertSubstring
  254.    * @example
  255.    * this.coreWebVitalResponse("cls", this.clsValue, this.clsTarget)
  256.    * */
  257.   coreWebVitalResponse(cwv, value, target) {
  258.     if (Object.entries(value).length === 0) return
  259.     target.classList.add(this.alertColor(value))
  260.     const replacementContent = `${this.alertSubstring(target.innerHTML)}${value.data}`
  261.     target.innerHTML = cwv === "cls" ? replacementContent : `${replacementContent}ms`
  262.   }
  264.   /** 
  265.    * CLS value change callback which calls coreWebVitalResponse
  266.    *
  267.    * @instance alertColor
  268.    * @property {String} value - CWV rating of good, needsImprovement or poor
  269.    * 
  270.    * @memberof RUMController
  271.    * @returns {String} The Stimulus class target
  272.    * @example
  273.    * this.alertColor("good")
  274.    * */
  275.   alertColor(value) {
  276.     switch (value.vitalsScore) {
  277.       case "good":
  278.         return this.successClass
  279.       case "needsImprovement":
  280.         return this.warningClass
  281.       case "poor":
  282.         return this.errorClass
  283.     }
  284.   }
  286.   /** 
  287.    * Splits the string at `...` and returns the text on LHS with `...` on the end
  288.    *
  289.    * @instance alertSubstring
  290.    * @property {String} currentContent - The text associated with the CWV 
  291.    * 
  292.    * @memberof RUMController
  293.    * @returns {String} eg. Largest Contentful Paint ... 
  294.    * @example
  295.    * this.alertSubstring("Largest Contentful Paint ... waiting")
  296.    * */
  297.   alertSubstring(currentContent) {
  298.     const contentStart = currentContent.split("...")[0]
  299.     return `${contentStart} ... `
  300.   }
  301. }