@phantomstudios/ft-lib 0.2.0

package/src/consentMonitor/index.ts

@@ -0,0 +1,120 @@
+import Debug from "debug";
+const debug = Debug("@phntms/ft-lib");
+
+const DEFAULT_DEV_HOSTS = ["localhost", "phq", ".app", "preview"];
+
+export class consentMonitor {
+  protected _consent = false;
+  protected _devHosts: string[];
+  protected _isDevEnvironment = false;
+  protected _hostname: string;
+  protected _isInitialized = false;
+
+  constructor(hostname?: string, devHosts?: string[] | string) {
+    if (Array.isArray(devHosts)) {
+      this._devHosts = devHosts.concat(DEFAULT_DEV_HOSTS);
+    } else if (devHosts === undefined) {
+      this._devHosts = DEFAULT_DEV_HOSTS;
+    } else {
+      this._devHosts = DEFAULT_DEV_HOSTS;
+      this._devHosts.push(devHosts);
+    }
+
+    this._hostname = hostname || window.location.hostname;
+    this.init();
+  }
+
+  get consent(): boolean {
+    return this._consent;
+  }
+
+  get devHosts(): string[] | string {
+    return this._devHosts;
+  }
+
+  get isDevEnvironment(): boolean {
+    return this._isDevEnvironment;
+  }
+
+  get isInitialized(): boolean {
+    return this._isInitialized;
+  }
+
+  getCookieValue = (name: string) =>
+    document.cookie.match("(^|;)\\s*" + name + "\\s*=\\s*([^;]+)")?.pop() || "";
+
+  init = () => {
+    this.cookieConsentTest();
+    setInterval(this.cookieConsentTest, 3000);
+
+    //Simulate cookie consent behaviour in non-prod environments
+    this._devHosts.map(
+      (devHost) =>
+        this._hostname.includes(devHost) && this.setDevCookieHandler()
+    );
+  };
+
+  cookieConsentTest = () => {
+    if (window.permutive) {
+      if (!this._isInitialized) {
+        if (
+          this.getCookieValue("FTConsent").includes("behaviouraladsOnsite%3Aon")
+        ) {
+          this.permutiveConsentOn();
+        } else {
+          this.permutiveConsentOff();
+        }
+        this._isInitialized = true;
+      } else if (
+        this.getCookieValue("FTConsent").includes(
+          "behaviouraladsOnsite%3Aon"
+        ) &&
+        !this.consent
+      ) {
+        debug("setting permutive tracking consent: on");
+        this.permutiveConsentOn();
+      } else if (
+        !this.getCookieValue("FTConsent").includes(
+          "behaviouraladsOnsite%3Aon"
+        ) &&
+        this.consent
+      ) {
+        debug("setting permutive tracking consent: off");
+        this.permutiveConsentOff();
+      }
+    }
+  };
+
+  setDevCookieHandler = () => {
+    this._isDevEnvironment = true;
+    debug("setting development environment from host match");
+    const oCookieMessage =
+      document.getElementsByClassName("o-cookie-message")[0];
+    if (oCookieMessage) {
+      const onCookieMessageAct = () => {
+        debug("setting development FT consent cookies");
+        document.cookie = "FTConsent=behaviouraladsOnsite%3Aon";
+        document.cookie = "FTCookieConsentGDPR=true";
+        oCookieMessage.removeEventListener(
+          "oCookieMessage.act",
+          onCookieMessageAct,
+          false
+        );
+      };
+      oCookieMessage.addEventListener("oCookieMessage.act", onCookieMessageAct);
+    }
+  };
+
+  permutiveConsentOn = () => {
+    window.permutive.consent({
+      opt_in: true,
+      token: "behaviouraladsOnsite:on",
+    });
+    this._consent = true;
+  };
+
+  permutiveConsentOff = () => {
+    window.permutive.consent({ opt_in: false });
+    this._consent = false;
+  };
+}

package/src/gaTracker/index.ts

@@ -0,0 +1,136 @@
+import { TrackingOptions } from "../FTTracking";
+import { validateGTMCustomEvent } from "../utils/yupValidator";
+const HEADER_CATEGORY = "Header";
+const HEADER_SEARCH_ACTION = "Engagement - Search";
+
+export class gaTracker {
+  options;
+  constructor(options: TrackingOptions) {
+    this.options = options;
+    this.setUpFTNavigationLinksTracking();
+    this.addDataAttributesListener();
+    this.setUpFTNavigationSearchTracking(HEADER_CATEGORY, HEADER_SEARCH_ACTION);
+    this.setupFooterLinksTracking();
+  }
+
+  public GTMEventDispatcher(category: string, action: string, label: string) {
+    validateGTMCustomEvent({ category, action, label });
+    //from channels - sets event categories on window on certain pages..replace?
+    if (category === "<category>" && window.gtmCategory) {
+      category = window.gtmCategory;
+    }
+    window.dataLayer.push({
+      event: "customEvent",
+      category,
+      action,
+      label,
+    });
+  }
+
+  public GTMVirtualPageView(pageUrl: string, pageTitle: string) {
+    window.dataLayer.push({
+      event: "virtualPageView",
+      pageUrl,
+      pageTitle,
+    });
+  }
+
+  public GtagEventDispatcher(category: string, action: string, label: string) {
+    validateGTMCustomEvent({ category, action, label });
+    window.gtag("event", action, {
+      event_category: category,
+      event_label: label,
+    });
+  }
+
+  addDataAttributesListener() {
+    document.body.addEventListener("click", (evt) => {
+      //get nearest element with data-gadl attribute
+      const elm = (evt.target as HTMLElement).closest("[data-gadl]");
+      const gaEventString = elm?.getAttribute("data-gadl");
+      if (!gaEventString) return;
+      const [category, action, label] = gaEventString.split("|");
+
+      //TODO validate event fields
+      if (typeof window !== "undefined") {
+        //TBC - GTM customEvent tag vs standard UA event push?
+        if (this.options.isCustomGTMEvent) {
+          this.GTMEventDispatcher(
+            category,
+            action,
+            label || window.location.pathname //use pathname if label section has not been defined
+          );
+        } else {
+          this.GtagEventDispatcher(
+            category,
+            action,
+            label || window.location.pathname
+          );
+        }
+      }
+    });
+  }
+
+  setUpFTNavigationLinksTracking() {
+    const FTNavigationLinks = Array.from(
+      document.querySelectorAll(".o-header__drawer-menu-link")
+    );
+    if (FTNavigationLinks) {
+      FTNavigationLinks.map((navLink) => {
+        const trackingValue = `Header|Engagement - Hamburger|${
+          document.URL
+        } - ${(navLink as HTMLAnchorElement).href}`;
+        navLink.setAttribute("data-gadl", trackingValue);
+      });
+    }
+  }
+
+  setUpFTNavigationSearchTracking(category: string, action: string) {
+    const searchForm = document.querySelector(".o-header__search-form");
+    if (searchForm) {
+      searchForm.addEventListener("submit", (event) => {
+        event.preventDefault();
+        const searchBarContent = (
+          document.querySelector(".o-header__search-term") as HTMLInputElement
+        )?.value;
+        if (typeof window !== "undefined") {
+          if (this.options.isCustomGTMEvent) {
+            window.dataLayer.push({
+              event: "customEvent",
+              category,
+              action: `${action}: ${searchBarContent}`,
+              label: window.location.pathname,
+              eventCallback: () => {
+                (searchForm as HTMLFormElement).submit();
+              },
+              eventTimeout: 2000,
+            });
+          } else {
+            window.gtag("event", action, {
+              event_category: category,
+              event_label: searchBarContent,
+              event_callback: () => {
+                (searchForm as HTMLFormElement).submit();
+              },
+              event_timeout: 2000,
+            });
+          }
+        }
+      });
+    }
+  }
+
+  setupFooterLinksTracking() {
+    const FTFooterLinks = Array.from(
+      document.querySelectorAll(".o-footer__legal-links li a")
+    );
+    if (FTFooterLinks) {
+      FTFooterLinks.forEach((footerLink) => {
+        const trackingValue = `Footer|Click - Footer Nav - ${
+          (footerLink as HTMLAnchorElement).href
+        }|${document.URL}`;
+        footerLink.setAttribute("data-gadl", trackingValue);
+      });
+    }
+  }
+}

package/src/index.ts

@@ -0,0 +1,12 @@
+export { consentMonitor } from "./consentMonitor";
+export { permutiveVideoUtils } from "./permutiveVideoUtils";
+export { reactPlayerTracking } from "./reactPlayerTracking";
+export { gaTracker } from "./gaTracker";
+export { oTracker } from "./oTracker";
+export { ytIframeTracking } from "./ytIframeTracking";
+export { FTTracking, TrackingOptions } from "./FTTracking";
+export {
+  ConfigType,
+  OrigamiEventType,
+  GTMCustomEventType,
+} from "./utils/yupValidator";

package/src/oTracker/index.ts

@@ -0,0 +1,122 @@
+import oTracking from "@financial-times/o-tracking";
+
+import { TrackingOptions } from "../FTTracking";
+import { getValueFromCookie } from "../utils/cookies";
+import getTrace from "../utils/getTrace";
+import {
+  parseConfig,
+  validateConfig,
+  validateOrigamiEvent,
+  ConfigType,
+  OrigamiEventType,
+} from "../utils/yupValidator";
+
+/* oTracking setup for server-rendered (i.e. Wagtail) sites
+The config object is read from the server-rendered o-tracking-data element
+*/
+export class oTracker {
+  private _config: ConfigType;
+  options: TrackingOptions;
+
+  constructor(config: ConfigType, options: TrackingOptions) {
+    this._config = parseConfig(config);
+    validateConfig(this._config);
+    this._config.source_id = oTracking.getRootID();
+    this.options = options;
+
+    //init config data
+    const configData = {
+      server: "https://spoor-api.ft.com/px.gif",
+      context: {
+        ...this._config,
+      },
+      user: {
+        ft_session: getValueFromCookie(/FTSession=([^;]+)/),
+      },
+    };
+    oTracking.init(configData);
+
+    //setup listeners
+    this.OTrackingHandler();
+
+    //send Origami DomLoaded event
+    //document.dispatchEvent(new CustomEvent("o.DOMContentLoaded"));  //TODO this isnt needed on next and breaks the cookie-message eventhandlers - is it needed for the server sites?
+    //send page hits
+    this.broadcastPageView();
+    this.broadcastBrandedContent();
+  }
+
+  set config(c: ConfigType) {
+    this._config = c;
+  }
+  get config() {
+    return this._config;
+  }
+
+  public eventDispatcher(detail: OrigamiEventType) {
+    if (typeof detail === "object" && detail.category && detail.action) {
+      validateOrigamiEvent(detail);
+      detail.app = this.config.app;
+      detail.product = this.config.product;
+      document.body.dispatchEvent(
+        new CustomEvent("oTracking.event", { detail, bubbles: true })
+      );
+    } else {
+      throw "Invalid event type";
+    }
+  }
+
+  public broadcastPageView() {
+    oTracking.page({
+      app: this.config.app,
+      product: this.config.product,
+      title: document.title,
+    });
+  }
+
+  public broadcastBrandedContent() {
+    document.body.dispatchEvent(
+      new CustomEvent("oTracking.event", {
+        detail: {
+          ...this.config,
+          action: "view",
+          category: "brandedContent",
+        },
+        bubbles: true,
+      })
+    );
+  }
+
+  OTrackingHandler() {
+    document.body.addEventListener("click", (event) => {
+      const trackableElement = event
+        .composedPath()
+        .find(
+          (elm) =>
+            elm instanceof HTMLElement &&
+            elm.hasAttribute &&
+            elm.hasAttribute("data-o-event")
+        );
+      if (trackableElement && trackableElement instanceof HTMLElement) {
+        const data = trackableElement.getAttribute("data-o-event");
+        const detail = {};
+        const { trace } = getTrace(trackableElement);
+
+        if (data) {
+          data.split("|").forEach((item) => {
+            const kv = item.split(":");
+            //TODO
+            // @ts-ignore
+            detail[kv[0]] = kv[1];
+          });
+
+          //TODO
+          // @ts-ignore
+          detail.domPathTokens = trace;
+        }
+
+        this.eventDispatcher(detail as OrigamiEventType);
+      }
+    });
+  }
+}

package/src/permutiveVideoUtils/index.ts

@@ -0,0 +1,53 @@
+import Debug from "debug";
+const debug = Debug("@phntms/ft-lib");
+export class permutiveVideoUtils {
+  protected progressPermutiveMilestones: number[] = [0, 0.25, 0.5, 0.75, 1];
+  protected _campaign: string;
+  protected _title: string;
+  protected _videoId;
+
+  constructor(campaign: string, title: string, videoId = "") {
+    this._campaign = campaign;
+    this._title = title;
+    this._videoId = videoId;
+  }
+
+  set videoId(vid: string) {
+    this._videoId = vid;
+  }
+  get videoId() {
+    return this._videoId;
+  }
+
+  get remainingProgress(): number[] {
+    return this.progressPermutiveMilestones;
+  }
+
+  emitPermutiveProgressEvent = (
+    duration: number,
+    currentTime: number,
+    interval: any = undefined
+  ) => {
+    const progress = currentTime / (Math.floor(duration) - 1);
+
+    while (
+      progress >= this.progressPermutiveMilestones[0] &&
+      currentTime > 0 &&
+      window.permutive
+    ) {
+      debug("Emit videoEngagement permutive event");
+      window.permutive.track("VideoEngagement", {
+        campaign: this._campaign,
+        createdAt: new Date().toISOString(),
+        duration: Math.floor(duration),
+        title: this._title,
+        videoId: this._videoId,
+        progress: this.progressPermutiveMilestones[0],
+      });
+      this.progressPermutiveMilestones.shift();
+      if (this.progressPermutiveMilestones.length === 0 && interval) {
+        window.clearInterval(interval);
+      }
+    }
+  };
+}

package/src/reactPlayerTracking/index.ts

@@ -0,0 +1,105 @@
+import Debug from "debug";
+
+import { FTTracking } from "../FTTracking";
+import { permutiveVideoUtils } from "../permutiveVideoUtils";
+import { OrigamiEventType } from "../utils/yupValidator";
+const debug = Debug("@phntms/ft-lib");
+interface PlayerProgressEvent {
+  played: number;
+  loaded: number;
+  playedSeconds: number;
+  loadedSeconds: number;
+}
+export class reactPlayerTracking {
+  duration = 0;
+  playedSeconds = 0;
+  playedPercent = 0;
+  videoTitle: string;
+  videoUrl: string;
+
+  /** 100% is fired with ended event */
+  GA_milestones: number[] = [1, 25, 50, 75];
+  oTracking_milestones: number[] = [25, 50, 75];
+  FTTracker: FTTracking;
+  permutiveTracker: permutiveVideoUtils | undefined;
+
+  constructor(FTTracker: FTTracking, videoTitle: string, videoUrl: string) {
+    /** oTracking dispatch event function */
+    this.FTTracker = FTTracker;
+    this.videoTitle = videoTitle;
+    this.videoUrl = videoUrl;
+    this.permutiveTracker = new permutiveVideoUtils(
+      this.FTTracker.config.campaign,
+      this.videoTitle,
+      this.videoUrl
+    );
+  }
+
+  setDuration = (duration: number) => {
+    this.duration = Math.floor(duration);
+  };
+
+  sendGAEvent = (action: string) => {
+    debug("GA datalayer push - " + action);
+    this.FTTracker.gaEvent("Video", action, this.videoTitle);
+  };
+
+  sendoTrackingEvent = (action: string, progress?: number) => {
+    debug("oTracking event - " + action);
+    this.FTTracker.oEvent({
+      category: "video",
+      action: action,
+      product: this.FTTracker.config.product,
+      app: this.FTTracker.config.app,
+      duration: this.duration,
+      ...(progress && { progress: progress }),
+    } as OrigamiEventType);
+  };
+
+  trackPlay = () => {
+    this.sendGAEvent("playing");
+    this.sendoTrackingEvent("playing");
+  };
+
+  trackPause = () => {
+    this.sendGAEvent("pause");
+    this.sendoTrackingEvent("pause");
+  };
+
+  trackEnded = () => {
+    //fire 100% progress events
+    this.sendGAEvent("100% watched");
+    this.sendoTrackingEvent("progress", 100);
+
+    this.sendGAEvent("ended");
+    this.sendoTrackingEvent("ended", 100);
+  };
+
+  trackProgress = (reactPlayerProgress: PlayerProgressEvent) => {
+    this.playedSeconds = reactPlayerProgress.playedSeconds;
+    if (this.duration > 0) {
+      this.playedPercent = Math.floor(
+        (Math.ceil(reactPlayerProgress.playedSeconds) / this.duration) * 100
+      );
+    }
+
+    while (this.playedPercent >= this.GA_milestones[0]) {
+      debug("GA progress milestone - " + this.GA_milestones[0]);
+      this.sendGAEvent(`${this.GA_milestones[0]}% watched`);
+      this.GA_milestones.shift();
+    }
+
+    while (this.playedPercent >= this.oTracking_milestones[0]) {
+      debug("oTracking progress milestone - " + this.oTracking_milestones[0]);
+      this.sendoTrackingEvent("progress", this.oTracking_milestones[0]);
+      this.oTracking_milestones.shift();
+    }
+
+    //permutive only tracks progress events and contains its own milestones
+    debug("edit permutive progress event- " + this.playedSeconds);
+    this.permutiveTracker?.emitPermutiveProgressEvent(
+      this.duration,
+      this.playedSeconds
+    );
+  };
+}

package/src/types.d.ts

@@ -0,0 +1,33 @@
+declare module "@financial-times/o-tracking";
+declare module "@financial-times/o-viewport";
+
+interface Window {
+  dataLayer: any;
+  gtag: any;
+  permutive: {
+    addon: any;
+    consent: CallableConsent;
+    track: any;
+  };
+  gtmCategory?: string; //channels only
+  isOvideoPlayer?: boolean; //channels only
+}
+
+interface ConsentOptions {
+  opt_in?: boolean;
+  token?: string;
+}
+
+interface CallableConsent {
+  ({}: ConsentOptions): void;
+}
+
+interface VideoTrackingOptions {
+  isOTracking?: boolean;
+  isGATracking?: boolean;
+  isPermutiveTracking?: boolean;
+  GA_datalayer?: any;
+  GA_milestones?: number[];
+  oTracking_milestones?: number[];
+  route_url?: string;
+}