@financial-times/custom-code-component 1.9.1 → 1.9.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@financial-times/custom-code-component",
-  "version": "1.9.1",
+  "version": "1.9.3",
   "type": "module",
   "exports": {
     ".": {
@@ -26,6 +26,8 @@
     "vite-plugin-dts": "^3.6.0"
   },
   "dependencies": {
+    "@financial-times/o-tracking": "^4.5.4",
+    "ftdomdelegate": "^5.0.0",
     "react": "^18.2.0",
     "react-dom": "^18.2.0"
   },

package/src/analytics.ts

@@ -0,0 +1,137 @@
+import Delegate from "ftdomdelegate";
+import oTracking from "@financial-times/o-tracking";
+import { getTrace } from "./get-trace";
+import {
+  sanitise,
+  assignIfUndefined,
+} from "@financial-times/o-tracking/src/javascript/utils.js";
+
+// default values if nothing is passed into init
+let cccName = "ccc-component";
+let subtype = "interactive";
+
+const eventPropertiesToCollect = ["ctrlKey", "altKey", "shiftKey", "metaKey"];
+
+// Get properties for the event (as opposed to properties of the clicked element)
+// Available properties include mouse x- and y co-ordinates, for example.
+const getEventProperties = (event) => {
+  const eventProperties = {};
+  for (const property of eventPropertiesToCollect) {
+    if (event[property]) {
+      try {
+        eventProperties[property] = sanitise(event[property]);
+      } catch (e) {
+        // eslint-disable-next-line no-console
+        console.log(e);
+      }
+    }
+  }
+
+  return eventProperties;
+};
+
+// Controller for handling click events
+const handleClickEvent = (eventData, root) => (clickEvent, clickElement) => {
+  const context = getEventProperties(clickEvent);
+  const { trace, customContext } = getTrace(clickElement, root);
+  context.custom =
+    clickElement.dataset && clickElement.dataset.custom
+      ? JSON.parse(clickElement.dataset.custom)
+      : null;
+  context.domPathTokens = trace;
+  context.component = {
+    id: cccName,
+    name: cccName,
+    type: "custom-code-component",
+    subtype,
+  };
+  context.teamName = "djd";
+
+  assignIfUndefined(customContext, context);
+
+  eventData.context = context;
+  eventData.method = "ftCustomAnalytics";
+
+  // send spoor event
+  document.body.dispatchEvent(
+    new CustomEvent("oTracking.event", {
+      detail: eventData,
+      bubbles: true,
+      composed: true,
+    })
+  );
+};
+
+function sendSpoorEvent(triggerAction, extraDetail) {
+  const eventData = {
+    category: "component",
+    action: "act",
+    context: {
+      component: {
+        id: cccName,
+        name: cccName,
+        type: "custom-code-component",
+        subtype,
+      },
+      teamName: "djd",
+      trigger_action: triggerAction,
+      custom: extraDetail,
+    },
+    method: "ftCustomAnalytics",
+  };
+
+  // send spoor event
+  document.body.dispatchEvent(
+    new CustomEvent("oTracking.event", {
+      detail: eventData,
+      bubbles: true,
+      composed: true,
+    })
+  );
+}
+
+function init(
+  templateObj: { id?: string; subtype?: string },
+  shadowRoot?: ShadowRoot,
+  category?: string,
+  elements?: []
+) {
+  if (!tracking.isInitialised) {
+    tracking.isInitialised = true;
+    if (templateObj) {
+      cccName = templateObj.id || cccName;
+      subtype = templateObj.subtype || subtype;
+    }
+
+    oTracking.init({ queue: true, test: true }); // @TODO: Flip this to false before using in production
+
+    const elementsToTrack = elements || 'a, button, input, [role="button"]';
+
+    // Note: `context` is the term o-tracking uses for the data that is sent to spoor
+    const eventData = {
+      action: "click",
+      category: category || "cta",
+    };
+
+    const root = shadowRoot?.querySelector("#component-root");
+
+    if (shadowRoot) {
+      const shadowDelegate = new Delegate(root);
+
+      shadowDelegate.on(
+        "click",
+        elementsToTrack,
+        handleClickEvent(eventData, root),
+        true
+      );
+    }
+  }
+}
+
+const tracking = {
+  init,
+  isInitialised: false,
+  sendSpoorEvent,
+};
+
+export default tracking;

package/src/custom-code-component.ts

@@ -5,6 +5,8 @@
 
 import { ContentTree } from "@financial-times/content-tree";
 import { BaseRenderer } from "../../ccc-sdk/src/renderers/AbstractBaseRenderer";
+import tracking from "./analytics";
+
 class FTCustomCodeComponent extends HTMLElement {
   app: typeof BaseRenderer.prototype.render;
 
@@ -46,7 +48,12 @@ class FTCustomCodeComponent extends HTMLElement {
     const { unmount, onmessage } =
       App(
         shadow,
-        { ...extraProps, data, port: this.channel.port2 },
+        {
+          ...extraProps,
+          data,
+          port: this.channel.port2,
+          tracking,
+        },
         ...this.children
       ) || {};
 
@@ -153,6 +160,21 @@ class FTCustomCodeComponent extends HTMLElement {
 
       delete this.dataset.cccReady;
     }
+
+    try {
+      tracking.init(
+        {
+          id: this.getAttribute("path") as string,
+          subtype: "interactive",
+        },
+        this.shadowRoot
+      );
+    } catch (e) {
+      console.info(
+        `Error initialising tracking on <custom-code-component> ${path}@${componentVersionRange}`
+      );
+      console.error(e);
+    }
   }
 
   disconnectedCallback() {

package/src/get-trace.js

@@ -0,0 +1,135 @@
+// Trace the element and all of its parents, collecting properties as we go
+import {
+  sanitise,
+  assignIfUndefined,
+} from "@financial-times/o-tracking/src/javascript/utils.js";
+
+// For a given container element, get the number of elements that match the
+// original element (siblings); and the index of the original element (position).
+const getSiblingsAndPosition = (el, originalEl, selector) => {
+  const siblings = Array.from(el.querySelectorAll(selector));
+  const position = siblings.findIndex((item) => item === originalEl);
+  if (position === -1) {
+    return;
+  }
+  return {
+    siblings: siblings.length,
+    position,
+  };
+};
+
+const elementPropertiesToCollect = [
+  "nodeName",
+  "className",
+  "id",
+  "href",
+  "text",
+  "role",
+];
+// Get all (sanitised) properties of a given element.
+const getAllElementProperties = (element) => {
+  const properties = {};
+  for (const property of elementPropertiesToCollect) {
+    const value =
+      element[property] ||
+      element.getAttribute(property) ||
+      element.hasAttribute(property);
+    if (value !== undefined) {
+      if (typeof value === "boolean") {
+        properties[property] = value;
+      } else {
+        properties[property] = sanitise(value);
+      }
+    }
+  }
+
+  return properties;
+};
+
+const parseRawValue = (rawValue) => {
+  try {
+    const parsedValue = JSON.parse(rawValue);
+    const type = Object.prototype.toString.call(parsedValue);
+    const isJSON = type === "[object Object]" || type === "[object Array]";
+
+    return [isJSON, parsedValue];
+  } catch (error) {
+    return [false, null];
+  }
+};
+
+const getAttributeValue = (rawValue) => {
+  const [isJSON, value] = parseRawValue(rawValue);
+
+  return isJSON ? value : rawValue;
+};
+
+// Get some properties of a given element.
+const getDomPathProps = (attrs, props) => {
+  // Collect any attribute that matches given strings.
+  attrs
+    .filter((attribute) =>
+      attribute.name.match(/^data-trackable|^data-o-|^aria-/i)
+    )
+    .forEach((attribute) => {
+      props[attribute.name] = attribute.value;
+    });
+
+  return props;
+};
+
+// Get only the custom data-trackable-context-? properties of a given element
+const getContextProps = (attrs, props, isOriginalEl) => {
+  const customProps = {};
+
+  // for the original element collect properties like className, nodeName
+  if (isOriginalEl) {
+    elementPropertiesToCollect.forEach((name) => {
+      if (typeof props[name] !== "undefined" && name !== "id") {
+        customProps[name] = props[name];
+      }
+    });
+  }
+
+  // Collect any attribute that matches given strings.
+  attrs
+    .filter((attribute) => attribute.name.match(/^data-trackable-context-/i))
+    .forEach((attribute) => {
+      customProps[attribute.name.replace("data-trackable-context-", "")] =
+        getAttributeValue(attribute.value);
+    });
+
+  return customProps;
+};
+
+export function getTrace(el, rootEl) {
+  const originalEl = el;
+  const selector = originalEl.getAttribute("data-trackable")
+    ? `[data-trackable="${originalEl.getAttribute("data-trackable")}"]`
+    : originalEl.nodeName;
+  const trace = [];
+  const customContext = {};
+  while (el && el !== rootEl) {
+    const props = getAllElementProperties(el);
+    const attrs = Array.from(el.attributes);
+    let domPathProps = getDomPathProps(attrs, props);
+
+    // If the element happens to have a data-trackable attribute, get the siblings
+    // and position of the element (relative to the current element).
+    if (domPathProps["data-trackable"]) {
+      domPathProps = Object.assign(
+        domPathProps,
+        getSiblingsAndPosition(el, originalEl, selector)
+      );
+    }
+
+    trace.push(domPathProps);
+
+    const contextProps = getContextProps(attrs, props, el === originalEl);
+
+    assignIfUndefined(contextProps, customContext);
+
+    el = el.parentNode;
+  }
+  return { trace, customContext };
+}