@phantomstudios/ft-lib 0.2.0

package/src/utils/yupValidator.ts

@@ -0,0 +1,205 @@
+import {
+  object,
+  string,
+  number,
+  boolean,
+  mixed,
+  InferType,
+  ValidationError,
+} from "yup";
+
+//transform passed values to first character uppercase and replace spaces with underscores
+const unifyValuesTransform = (value: string) => {
+  return (
+    value.trim().charAt(0).toUpperCase() +
+    value.trim().slice(1).toLowerCase().replace(/ /g, "_").replace(/-/g, "_")
+  );
+};
+
+//replace legacy 'AlphaGrid'..
+const authorTransform = (value: string) => {
+  if (value.toLowerCase() === "alphagrid") {
+    return "Alpha_Grid";
+  }
+  return (
+    value.trim().charAt(0).toUpperCase() +
+    value.trim().slice(1).toLowerCase().replace(/ /g, "_").replace(/-/g, "_")
+  );
+};
+
+const configSchema = object({
+  product: string().equals(["paid-post"]),
+  url: string().required(),
+  feature: string().required().oneOf(["channel", "microsite"]),
+  author: string().defined().default("").transform(authorTransform),
+  sponsor: string().defined().default(""),
+  articleName: string().defined().default(""),
+  videoName: string().defined().default(""),
+  videoType: string()
+    .optional()
+    .default("")
+    .transform(unifyValuesTransform)
+    .oneOf(["Feature", "Case_study", "Interview", "Animation", ""]),
+  hasVideo: boolean().optional().nullable(),
+  primaryTopic: string().defined().default("").transform(unifyValuesTransform),
+  secondaryTopic: string()
+    .defined()
+    .default("")
+    .transform(unifyValuesTransform),
+  advertiserIndustry: string().defined().default(""),
+  app: string()
+    .required()
+    .defined()
+    .transform(unifyValuesTransform)
+    .oneOf([
+      "Stream",
+      "Article",
+      "Animated_article",
+      "Immersive_article",
+      "Video",
+      "Article_with_video",
+      "Audio",
+      "Infographic",
+      "Interactive_infographic",
+      "Photo_essay",
+    ]),
+  publishDate: string().nullable().default(""),
+  isBranded: boolean().defined(),
+  contentType: string().defined().default("").transform(unifyValuesTransform),
+  campaign: string().defined().default(""),
+  server: string().equals(["https://spoor-api.ft.com/px.gif"]),
+  title: string().defined().default(""),
+  adbook_campaign_id: string().optional().default(""),
+  source_id: string().optional(),
+  wordCount: number().optional(),
+  commercial_product: string().optional().default("ft"),
+});
+
+const gtmCustomEventSchema = object({
+  category: string()
+    .required()
+    .oneOf([
+      "Internal click",
+      "External click",
+      "Video",
+      "Video:fallback",
+      "Audio",
+      "Scroll",
+      "Share",
+      "Form",
+      "Header",
+      "Footer",
+    ]),
+  action: string().required(),
+  label: string().required(),
+});
+
+const origamiEventSchema = object({
+  category: string()
+    .required()
+    .oneOf([
+      "page",
+      "video",
+      "audio",
+      "cta",
+      "scroll",
+      "brandedContent",
+      "internal click",
+      "external click",
+      "share",
+      "channel",
+    ]),
+  action: string().required(),
+  app: string().nullable().notRequired(),
+  product: string().nullable().notRequired(),
+  source: string().nullable().notRequired(),
+  meta: mixed().nullable().notRequired(),
+  duration: number()
+    .nullable()
+    .notRequired()
+    .when("category", {
+      is: "video" || "audio",
+      then: () => number().required(),
+    }),
+  progress: number()
+    .nullable()
+    .notRequired()
+    .when("category", {
+      is: "video" || "audio",
+      then: () => number().required(),
+    }),
+});
+
+export type ConfigType = InferType<typeof configSchema>;
+export type GTMCustomEventType = InferType<typeof gtmCustomEventSchema>;
+export type OrigamiEventType = InferType<typeof origamiEventSchema>;
+
+export const parseConfig = (config: ConfigType): ConfigType => {
+  try {
+    //Replace app value based on deprecated hasVideo field and then remove hasVideo
+    if (config.hasVideo && config.app.toLowerCase() === "article") {
+      config.app === "Article_with_video";
+    }
+
+    delete config.hasVideo;
+    //Parse wordCount as number if not already
+    if (config.wordCount) {
+      config.wordCount = Number(config.wordCount);
+    }
+    return configSchema.cast(config);
+  } catch (err: any) {
+    err.errors?.map((err: Error) => {
+      console.error("FTTracker - config cast error: " + err);
+    });
+    return config;
+  }
+};
+
+export const validateConfig = (
+  config: ConfigType
+): ValidationError[] | undefined => {
+  try {
+    configSchema.validateSync(config, {
+      strict: false,
+      abortEarly: false,
+    });
+  } catch (err: any) {
+    err.errors?.map((err: ValidationError) => {
+      console.error("FTTracker - config validation error: " + err);
+    });
+  }
+  return undefined;
+};
+
+export const validateGTMCustomEvent = (
+  event: GTMCustomEventType
+): ValidationError[] | undefined => {
+  try {
+    gtmCustomEventSchema.validateSync(event, {
+      strict: true,
+      abortEarly: false,
+    });
+  } catch (err: any) {
+    err.errors?.map((err: ValidationError) => {
+      console.error("FTTracker - GTM custom event validation error: " + err);
+    });
+  }
+  return undefined;
+};
+
+export const validateOrigamiEvent = (
+  config: OrigamiEventType
+): ValidationError[] | undefined => {
+  try {
+    const parsedConfig = origamiEventSchema.cast(config);
+    origamiEventSchema.validateSync(parsedConfig, {
+      strict: true,
+      abortEarly: false,
+    });
+  } catch (err: any) {
+    err.errors?.map((err: ValidationError) => {
+      console.error("FTTracker - Origami event validation error: " + err);
+    });
+  }
+  return undefined;
+};

package/src/ytIframeTracking/index.ts

@@ -0,0 +1,210 @@
+import { FTTracking } from "../FTTracking";
+import { permutiveVideoUtils } from "../permutiveVideoUtils";
+import { OrigamiEventType } from "../utils/yupValidator";
+
+export class ytIframeTracking {
+  FTTracker: FTTracking;
+  progressMilestones = [1, 25, 50, 75];
+  permutiveUtils: permutiveVideoUtils;
+  videoProgressInterval = 0;
+  videoTitle: string;
+  videoUrl: string | undefined;
+
+  constructor(FTTracker: FTTracking, videoTitle?: string, videoUrl?: string) {
+    this.FTTracker = FTTracker;
+    this.videoTitle =
+      videoTitle || window.gtmCategory || window.location.pathname; //reverted fix for channels - use window.gtmCategory to maintain the original label style
+    this.videoUrl = videoUrl;
+    this.permutiveUtils = new permutiveVideoUtils(
+      this.FTTracker.config.campaign,
+      this.videoTitle
+    );
+  }
+
+  progressPercentage = (duration: number, currentTime: number) =>
+    parseInt(((currentTime / duration) * 100).toFixed(2));
+
+  emitProgressEvents = (
+    progress: number,
+    duration: number,
+    isYoutube: boolean
+  ) => {
+    while (progress >= this.progressMilestones[0]) {
+      this.FTTracker.gaEvent(
+        `Video${window.isOvideoPlayer ? ":fallback" : ""}`,
+        `${this.progressMilestones[0]}% watched`,
+        this.videoTitle
+      );
+      if (isYoutube) {
+        this.FTTracker.oEvent({
+          category: "video",
+          action: "progress",
+          duration: duration,
+          progress,
+        } as OrigamiEventType);
+      }
+      this.progressMilestones.shift();
+    }
+  };
+
+  //Fallback oVideo implemented only on channels - uses shared events so added here for now.
+  public oVideoEventHandler(videoEl: HTMLVideoElement) {
+    window.isOvideoPlayer = true;
+    this.permutiveUtils.videoId = videoEl.getAttribute("src") as string;
+    videoEl.addEventListener("play", () => {
+      this.playTracking(videoEl.currentTime, videoEl.duration);
+    });
+    videoEl.addEventListener("progress", () => {
+      this.progressTracking(videoEl.currentTime, videoEl.duration);
+    });
+    videoEl.addEventListener("seeked", () => {
+      this.seekedTracking(videoEl.currentTime, videoEl.duration);
+    });
+    videoEl.addEventListener("pause", () => {
+      this.pausedTracking(videoEl.currentTime, videoEl.duration);
+    });
+    videoEl.addEventListener("ended", () => {
+      this.endedTracking(videoEl.currentTime, videoEl.duration);
+    });
+  }
+
+  public ytIframeEventHandler(event: YT.PlayerEvent) {
+    const player = event.target as YT.Player;
+
+    if (!this.videoUrl) {
+      this.videoUrl = player.getVideoUrl();
+    }
+    this.permutiveUtils.videoId = this.videoUrl;
+    //player.playerInfo.videoUrl
+
+    switch (player.getPlayerState()) {
+      case YT.PlayerState.ENDED:
+        this.endedTracking(player.getCurrentTime(), player.getDuration());
+        break;
+      case YT.PlayerState.PLAYING:
+        this.ytPlayTracking(player);
+        break;
+      case YT.PlayerState.PAUSED:
+        //test if still pause after 1 second, otherwise its a seek
+        setTimeout(() => {
+          if (player.getPlayerState() == YT.PlayerState.PAUSED) {
+            this.pausedTracking(player.getCurrentTime(), player.getDuration());
+          }
+        }, 1000);
+
+        break;
+    }
+  }
+
+  ytPlayTracking(player: YT.Player) {
+    this.videoProgressInterval = window.setInterval(() => {
+      const currentTime = player.getCurrentTime();
+      const duration = player.getDuration();
+      this.permutiveUtils.emitPermutiveProgressEvent(
+        duration - 1,
+        currentTime,
+        this.videoProgressInterval
+      );
+      const progress = this.progressPercentage(duration, currentTime);
+      this.emitProgressEvents(progress, duration, true);
+    }, 1000);
+    const currentTime = player.getCurrentTime();
+    const duration = player.getDuration();
+    const progress = this.progressPercentage(duration, currentTime);
+    if (progress < 100) {
+      this.FTTracker.gaEvent(
+        `Video${window.isOvideoPlayer ? ":fallback" : ""}`,
+        `playing`,
+        this.videoTitle
+      );
+      this.FTTracker.oEvent({
+        category: "video",
+        action: "playing",
+        duration: duration,
+        progress,
+      } as OrigamiEventType);
+    }
+  }
+
+  pausedTracking(currentTime: number, duration: number) {
+    const progress = this.progressPercentage(duration, currentTime);
+    this.FTTracker.gaEvent(
+      `Video${window.isOvideoPlayer ? ":fallback" : ""}`,
+      `pause`,
+      `${this.videoTitle}`
+    );
+    this.FTTracker.oEvent({
+      category: "video",
+      action: "pause",
+      duration: duration,
+      progress,
+    } as OrigamiEventType);
+  }
+
+  endedTracking(currentTime: number, duration: number) {
+    const progress = this.progressPercentage(duration, currentTime);
+    this.FTTracker.gaEvent(
+      `Video${window.isOvideoPlayer ? ":fallback" : ""}`,
+      `100% watched`,
+      `${this.videoTitle}`
+    );
+    this.FTTracker.oEvent({
+      category: "video",
+      action: "ended",
+      duration: duration,
+      progress,
+    } as OrigamiEventType);
+    //force a 100% event on end
+    if (this.permutiveUtils.remainingProgress.length > 0) {
+      this.permutiveUtils.emitPermutiveProgressEvent(
+        currentTime,
+        currentTime,
+        this.videoProgressInterval
+      );
+    }
+  }
+
+  /*** Below events only used for FT-Channels videoJS and Origami players - remove if no longer needed ***/
+
+  /*** videojs and origami player event only  ***/
+  playTracking(currentTime: number, duration: number) {
+    this.videoProgressInterval = window.setInterval(() => {
+      this.permutiveUtils.emitPermutiveProgressEvent(
+        duration - 1,
+        currentTime,
+        this.videoProgressInterval
+      );
+    }, 1000);
+    const progress = this.progressPercentage(duration, currentTime);
+    this.FTTracker.oEvent({
+      category: "video",
+      action: "playing",
+      duration: duration,
+      progress,
+    } as OrigamiEventType);
+  }
+
+  /*** videojs and origami player event only  ***/
+  progressTracking(currentTime: number, duration: number) {
+    const progress = this.progressPercentage(duration, currentTime);
+    this.emitProgressEvents(progress, duration, false);
+    this.FTTracker.oEvent({
+      category: "video",
+      action: "progress",
+      duration: duration,
+      progress,
+    } as OrigamiEventType);
+  }
+
+  /*** videojs and origami player event only  ***/
+  seekedTracking(currentTime: number, duration: number) {
+    const progress = this.progressPercentage(duration, currentTime);
+    this.emitProgressEvents(progress, duration, false);
+    this.FTTracker.oEvent({
+      category: "video",
+      action: "seek",
+      duration: duration,
+      progress,
+    } as OrigamiEventType);
+  }
+}

package/test/index.test.tsx

@@ -0,0 +1,63 @@
+import { consentMonitor } from "../src/consentMonitor";
+import { permutiveVideoUtils } from "../src/permutiveVideoUtils";
+
+let windowSpy: jest.SpyInstance;
+
+beforeEach(() => {
+  windowSpy = jest.spyOn(window, "window", "get");
+});
+
+afterEach(() => {
+  windowSpy.mockRestore();
+});
+
+describe("consentMonitor", () => {
+  it("can be initiated", () => {
+    const obj = new consentMonitor();
+    expect(obj.consent).toBe(false);
+  });
+  it("sets default dev hosts property", async () => {
+    const obj = new consentMonitor("https://FT-staging.com");
+    expect(obj.devHosts).toEqual(["localhost", "phq", ".app", "preview"]);
+  });
+  it("matches hostname to devHosts", async () => {
+    const obj = new consentMonitor("https://FT-staging.devhost.com", [
+      "localhost",
+      "vercel.app",
+      "phq",
+      "devhost",
+    ]);
+    expect(obj.isDevEnvironment).toBe(true);
+  });
+
+  it("Initializes correctly", async () => {
+    jest.useFakeTimers();
+    windowSpy.mockImplementation(() => ({
+      permutive: {
+        consent: ({}) => {
+          return {};
+        },
+      },
+    }));
+    const obj = new consentMonitor("https://FT-staging.devhost.com", [
+      "localhost",
+      "vercel.app",
+      "phq",
+      "devhost",
+    ]);
+    expect(obj.isInitialized).toBe(true);
+  });
+  //TODO - mock document.cookie get/set and test consent value
+  describe("Permutive video progress utils", () => {
+    it("can be initiated", () => {
+      const permutiveVideoTracker = new permutiveVideoUtils(
+        "FT-Campaign",
+        "video title",
+        "videoID"
+      );
+      expect(permutiveVideoTracker.remainingProgress).toEqual([
+        0, 0.25, 0.5, 0.75, 1,
+      ]);
+    });
+  });
+});

package/tsconfig.json

@@ -0,0 +1,26 @@
+{
+  "compilerOptions": {
+    "target": "es5",
+    "module": "commonjs",
+    "types": ["youtube", "jest"],
+    "lib": ["dom", "es2020"],
+    "jsx": "react",
+    "declaration": true,
+    "declarationMap": true,
+    "sourceMap": true,
+    "outDir": "./lib",
+    "rootDir": "./src",
+    "strict": true,
+    "noImplicitAny": true,
+    "strictNullChecks": true,
+    "strictPropertyInitialization": true,
+    "noImplicitThis": true,
+    "alwaysStrict": true,
+    "noImplicitReturns": true,
+    "allowSyntheticDefaultImports": true,
+    "esModuleInterop": true,
+    "allowJs": true,
+  },
+  "include": ["src/**/*.ts", "src/**/*.js"],
+  "exclude": ["test/**/*"]
+}

package/tsconfig.test.json

@@ -0,0 +1,6 @@
+{
+  "extends": "./tsconfig.json",
+  "compilerOptions": {
+    "target": "esNext"
+  }
+}