@simplybusiness/services 0.1.1

package/src/services/snowplow/event-definitions.ts

@@ -0,0 +1,256 @@
+import { EventDefinition, ParamsType } from "./types";
+import { snakeCase } from "../../utils";
+
+/**
+ * Event definitions for Snowplow
+ * @type {EventDefinition[]}
+ * @property {string} name - The name of the event, to use when triggering
+ * @property {string} type - The type of the event (structured | unstructured)
+ * @property {makePayload} makePayload
+ *   - Function that creates the payload for the event;
+ *   - Allows optional params object to be passed in
+ *
+ * @example
+ * import { Snowplow } from "./Snowplow";
+ * import { eventDefinitions } from "./event-definitions";
+ *
+ * const snowplow = new Snowplow();
+ * snowplow.addEventHandlers(eventDefinitions);
+ */
+export const eventDefinitions: EventDefinition[] = [
+  {
+    name: "mobileLinkClick",
+    type: "structured",
+    makePayload: () => ({
+      category: "marketing",
+      action: "link-click",
+      label: "mobile_call_button",
+      property: window.location.href,
+    }),
+  },
+  {
+    name: "operatingHoursClick",
+    type: "unstructured",
+    makePayload: () => ({
+      schema:
+        "iglu:com.snowplowanalytics.snowplow/unstruct_event/jsonschema/1-0-0",
+      data: {
+        schema:
+          "iglu:com.simplybusiness/operating_hours_clicked/jsonschema/1-0-2",
+        data: {},
+      },
+    }),
+  },
+  {
+    // QDP details button
+    name: "detailsClicked",
+    type: "structured",
+    makePayload: () => ({
+      category: "comparison_cta",
+      action: "link_click",
+      label: "Details",
+    }),
+  },
+  {
+    // Buy button
+    name: "selectClicked",
+    type: "structured",
+    makePayload: () => ({
+      category: "comparison_cta",
+      action: "link_click",
+      label: "Select",
+    }),
+  },
+  {
+    // Quote Details Slider Next steps button
+    name: "nextStepsClicked",
+    type: "structured",
+    makePayload: () => ({
+      category: "quote_details_slider_next_step_cta",
+      action: "link_click",
+      label: "Next steps",
+    }),
+  },
+  {
+    // Toggle deductibles accordion
+    name: "deductiblesClicked",
+    type: "structured",
+    makePayload: () => ({
+      category: "us-qcp-react",
+      action: "view_deductables_clicked",
+      label: "view_deductables_clicked",
+      property: window.location.href,
+    }),
+  },
+  {
+    name: "deductiblesClickedUk",
+    type: "structured",
+    makePayload: params => {
+      const { label, deviceType } = params as ParamsType;
+      const urlFriendlyLabel = label.replace(/ /g, "-").toLowerCase();
+
+      return {
+        category: `uk-qcp-react-${deviceType}-${urlFriendlyLabel}-view-excess-toggle`,
+        action: "view_excess_clicked",
+        label,
+        property: window.location.href,
+      };
+    },
+  },
+  {
+    // Quote Details Slider opened
+    name: "sliderOpened",
+    type: "structured",
+    makePayload: params => {
+      const { label } = params as ParamsType;
+
+      return {
+        category: "comparison_cta",
+        action: "quote_details_slider_opened",
+        label,
+      };
+    },
+  },
+  {
+    // Coverage modal opened
+    name: "coverageModalOpened",
+    type: "structured",
+    makePayload: params => {
+      const {
+        category,
+        product = "extra_coverage",
+        title,
+      } = params as ParamsType;
+      const productLabel = snakeCase(product);
+
+      return {
+        category,
+        action: `${productLabel}_${snakeCase(title)}_popup_opened`,
+        label: productLabel,
+        property: window.location.href,
+      };
+    },
+  },
+  {
+    // Toggle cover select
+    name: "coverChanged",
+    type: "unstructured",
+    makePayload: params => {
+      const { name = "", fromValue = "", toValue = "" } = params as ParamsType;
+      // Derive data
+      let action = "change";
+
+      // This logic is taken directly from Chopin without documentation:
+      // If a cover has zero value, then change the action to add or remove
+      if (fromValue === "0") {
+        action = "add";
+      }
+      if (toValue === "0") {
+        action = "remove";
+      }
+
+      return {
+        schema:
+          "iglu:com.simplybusiness/comparison_page_cover_changed/jsonschema/1-0-0",
+        data: {
+          name,
+          action,
+          from_value: fromValue,
+          to_value: toValue,
+        },
+      };
+    },
+  },
+  {
+    name: "ratingsModalOpened",
+    type: "structured",
+    makePayload: params => {
+      const { category, label } = params as ParamsType;
+
+      return {
+        category,
+        action: "insurer_rating_help_popup_triggered",
+        label,
+        property: window.location.href,
+      };
+    },
+  },
+  {
+    name: "coverToggleOpened",
+    type: "structured",
+    makePayload: () => ({
+      category: "qcp_limit_interaction",
+      label: "limit_interaction",
+      action: "limit_interaction_clicked",
+      property: window.location.href,
+    }),
+  },
+  {
+    name: "paymentToggleClicked",
+    type: "structured",
+    makePayload: params => {
+      const { category, label } = params as ParamsType;
+
+      return {
+        category,
+        action: "button_click",
+        label,
+        property: window.location.href,
+      };
+    },
+  },
+  {
+    name: "insurerDetailsAccordionClicked",
+    type: "structured",
+    makePayload: () => ({
+      category: "quote_details_slider_insurer_details_description",
+      action: "accordion_clicked",
+      label: "accordion_clicked",
+      property: window.location.href,
+    }),
+  },
+  {
+    name: "priceDetailsPopUpOpened",
+    type: "structured",
+    makePayload: () => ({
+      category: "price_details",
+      action: "price_details_popup_opened",
+      label: "Price details",
+      property: window.location.href,
+    }),
+  },
+  {
+    name: "editLimitButtonClicked",
+    type: "structured",
+    makePayload: () => ({
+      category: "cover_limit_changes",
+      action: "edit_limit_button_clicked",
+      label: "Edit Limit",
+      property: window.location.href,
+    }),
+  },
+  {
+    name: "applyButtonClicked",
+    type: "structured",
+    makePayload: () => ({
+      category: "cover_limit_changes",
+      action: "apply_button_clicked",
+      label: "Apply Button Clicked",
+      property: window.location.href,
+    }),
+  },
+  {
+    name: "coverageInfoClicked",
+    type: "structured",
+    makePayload: params => {
+      const { deviceType } = params as ParamsType;
+
+      return {
+        action: "show_coverage_info_clicked",
+        category: `uk-qcp-react-${deviceType}-show-coverage-info-toggle`,
+        label: "show_coverage_info_clicked",
+        property: window.location.href,
+      };
+    },
+  },
+];

package/src/services/snowplow/getSnowplowConfig.ts

@@ -0,0 +1,8 @@
+import type { TrackingProps, PageDataProps } from "./types";
+
+// Get Snowplow config from page data props
+export const getSnowplowConfig = (
+  pageData: PageDataProps,
+): TrackingProps | undefined =>
+  pageData.scripts?.find(({ metadata }) => metadata.name === "snowplow")
+    ?.props as TrackingProps;

package/src/services/snowplow/index.test.ts

@@ -0,0 +1,194 @@
+import { waitFor } from "@testing-library/dom";
+import * as SnowplowLib from "@snowplow/browser-tracker";
+import { pageData } from "../../data/scripts-mock";
+import eventDefinitions from "../../mocks/eventDefinitions";
+import { getContexts } from "./contexts";
+import { getSnowplowConfig } from "./getSnowplowConfig";
+import { Snowplow } from "./index";
+import { EventDefinition, PageDataProps, TrackingProps } from "./types";
+
+const snowplowProps = getSnowplowConfig(pageData as PageDataProps);
+const contexts = getContexts(snowplowProps as TrackingProps);
+
+let testSnowplow = new Snowplow(snowplowProps as TrackingProps);
+testSnowplow.setContexts(contexts);
+
+describe("Snowplow Analytics Class", () => {
+  describe("given no snowplowProps", () => {
+    it("should render children without Snowplow instance errors", () => {
+      const snowplowInstance = new Snowplow();
+      expect(snowplowInstance).toBeDefined();
+    });
+  });
+
+  describe("given snowplowProps exist", () => {
+    beforeEach(() => {
+      testSnowplow = new Snowplow(snowplowProps as TrackingProps);
+      testSnowplow.setContexts(contexts);
+      jest.clearAllMocks();
+      jest.resetModules();
+    });
+
+    it("exports a Singleton instance with static properties", () => {
+      const secondInstance = new Snowplow(snowplowProps as TrackingProps);
+      secondInstance.setContexts(contexts);
+
+      expect(testSnowplow).toEqual(secondInstance);
+      expect(testSnowplow.bronzeAvalancheTrackerName).toEqual("sb-ava-br");
+    });
+
+    it("sets contexts on instantiation", () => {
+      expect(testSnowplow.contexts).toEqual(contexts);
+    });
+
+    it("tracks page view event and adds contexts", async () => {
+      const trackViewSpy = jest.spyOn(testSnowplow, "trackView");
+      const innerSpy = jest
+        .spyOn(SnowplowLib, "trackPageView")
+        .mockImplementation(() => {});
+
+      await testSnowplow.trackView();
+
+      waitFor(() => {
+        expect(trackViewSpy).toHaveBeenCalledTimes(1);
+        expect(trackViewSpy).toHaveBeenCalledWith();
+        expect(innerSpy).toHaveBeenCalledTimes(1);
+        expect(innerSpy).toHaveBeenCalledWith({ context: contexts });
+      });
+    });
+
+    it("tracks structured event and adds contexts", async () => {
+      const trackStructEventSpy = jest.spyOn(testSnowplow, "trackEvent");
+      const innerSpy = jest
+        .spyOn(SnowplowLib, "trackStructEvent")
+        .mockImplementation(() => {});
+
+      const payload = {
+        category: "mobile-link",
+        action: "clicked",
+        label: "test-label",
+      };
+
+      await testSnowplow.trackEvent(payload);
+
+      expect(trackStructEventSpy).toHaveBeenCalledTimes(1);
+      expect(trackStructEventSpy).toHaveBeenCalledWith(payload);
+      expect(innerSpy).toHaveBeenCalledTimes(1);
+      expect(innerSpy).toHaveBeenCalledWith({ ...payload, context: contexts }, [
+        "sb-ava-br",
+      ]);
+    });
+
+    it("tracks self-describing event and adds contexts", async () => {
+      const trackUnstructEventSpy = jest.spyOn(
+        testSnowplow,
+        "trackUnstructEvent",
+      );
+      const innerSpy = jest
+        .spyOn(SnowplowLib, "trackSelfDescribingEvent")
+        .mockImplementation(() => {});
+
+      const testEvent = {
+        schema:
+          "iglu:com.simplybusiness/comparison_page_cover_changed/jsonschema/1-0-0",
+        data: {
+          name: "Public liability",
+          action: "change",
+          from_value: "1000000",
+          to_value: "2000000",
+        },
+      };
+
+      await testSnowplow.trackUnstructEvent(testEvent);
+      expect(trackUnstructEventSpy).toHaveBeenCalledTimes(1);
+      expect(trackUnstructEventSpy).toHaveBeenCalledWith(testEvent);
+      expect(innerSpy).toHaveBeenCalledTimes(1);
+      expect(innerSpy).toHaveBeenCalledWith(
+        {
+          event: testEvent,
+          context: contexts,
+        },
+        ["sb-ava"],
+      );
+    });
+
+    describe("creates event handlers from definitions", () => {
+      it("adds a list of event handlers", () => {
+        testSnowplow.addEventHandlers(eventDefinitions as EventDefinition[]);
+        expect(Object.keys(testSnowplow.eventHandlers)).toEqual([
+          "navButtonClicked",
+          "questionAnswered",
+        ]);
+      });
+
+      it("triggers an added structured event", async () => {
+        testSnowplow.addEventHandlers(eventDefinitions as EventDefinition[]);
+
+        const trackStructEventSpy = jest.spyOn(testSnowplow, "trackEvent");
+        const innerSpy = jest
+          .spyOn(SnowplowLib, "trackStructEvent")
+          .mockImplementation(() => {});
+
+        await testSnowplow.trigger("navButtonClicked", { label: "test-label" });
+
+        const expectedPayload = {
+          category: "navigation",
+          action: "thankyou_navigation_button_click",
+          label: "test-label",
+          property: "test-property",
+        };
+
+        expect(trackStructEventSpy).toHaveBeenCalledTimes(1);
+        expect(trackStructEventSpy).toHaveBeenCalledWith(expectedPayload);
+        expect(innerSpy).toHaveBeenCalledTimes(1);
+        expect(innerSpy).toHaveBeenCalledWith(
+          { ...expectedPayload, context: contexts },
+          ["sb-ava-br"],
+        );
+      });
+
+      it("triggers an added unstructured event", async () => {
+        testSnowplow.addEventHandlers(eventDefinitions as EventDefinition[]);
+
+        const trackUnstructEventSpy = jest.spyOn(
+          testSnowplow,
+          "trackUnstructEvent",
+        );
+        const innerSpy = jest
+          .spyOn(SnowplowLib, "trackSelfDescribingEvent")
+          .mockImplementation(() => {});
+
+        await testSnowplow.trigger("questionAnswered", {
+          vertical: "shop",
+          question: "test-question",
+          answer: "test-answer",
+        });
+
+        const expectedPayload = {
+          schema:
+            "iglu:com.simplybusiness/form_question_answered/jsonschema/1-0-1",
+          data: {
+            site: "",
+            vertical: "shop",
+            page_index: 1,
+            page_name: "Coverage diagnosis questionnaire",
+            section_name: "Coverage diagnosis questionnaire",
+            question: "test-question",
+            answer: "test-answer",
+          },
+        };
+
+        expect(trackUnstructEventSpy).toHaveBeenCalledTimes(1);
+        expect(trackUnstructEventSpy).toHaveBeenCalledWith(expectedPayload);
+        expect(innerSpy).toHaveBeenCalledTimes(1);
+        expect(innerSpy).toHaveBeenCalledWith(
+          {
+            event: expectedPayload,
+            context: contexts,
+          },
+          ["sb-ava"],
+        );
+      });
+    });
+  });
+});

package/src/services/snowplow/index.ts

@@ -0,0 +1,163 @@
+import {
+  SelfDescribingJson,
+  StructuredEvent,
+  TrackerConfiguration,
+  newTracker,
+  setCookiePath,
+  setUserId,
+  trackPageView,
+  trackSelfDescribingEvent,
+  trackStructEvent,
+} from "@snowplow/browser-tracker";
+import { EventDefinition, TrackingProps } from "./types";
+
+export type FrontOfficeStructuredEvent = StructuredEvent & {
+  serviceChannelIdentifier: string;
+};
+
+/**
+ * This class is an abstraction which wraps Snowplow
+ * and exposes common methods with other services:
+ * - trackEvent            : sends a standard payload
+ * - trackUnstructEvent    : sends a payload for custom schema
+ */
+export class Snowplow {
+  avalancheTrackerName = "sb-ava";
+
+  bronzeAvalancheTrackerName = "sb-ava-br";
+
+  pvAvalancheTrackerName = "sb-ava-pv";
+
+  uid: unknown = "";
+
+  trackPageView: boolean = false;
+
+  contexts: SelfDescribingJson<Record<string, unknown>>[] = [];
+
+  eventHandlers: Record<string, (params?: Record<string, unknown>) => void> =
+    {};
+
+  constructor(props?: TrackingProps) {
+    if (!props) return;
+
+    const {
+      appId,
+      cookieDomain,
+      avalancheCollector,
+      eventMethod,
+      uid,
+      postPath,
+      // includeGAContext,
+      // trackActivity,
+      trackPageView: tpv,
+    } = props;
+    this.uid = uid;
+    this.trackPageView = tpv;
+
+    // Set options
+    const stateStorageStrategy = "cookieAndLocalStorage";
+    const baseOptions: TrackerConfiguration = {
+      appId,
+      cookieDomain,
+      eventMethod,
+      stateStorageStrategy,
+      postPath,
+    };
+    // Initialize trackers
+    newTracker(this.avalancheTrackerName, avalancheCollector, baseOptions);
+
+    newTracker(
+      this.bronzeAvalancheTrackerName,
+      avalancheCollector,
+      baseOptions,
+    );
+
+    // Page view tracker
+    newTracker(this.pvAvalancheTrackerName, avalancheCollector, {
+      ...baseOptions,
+      eventMethod: eventMethod === "post" ? "beacon" : eventMethod,
+    });
+
+    setCookiePath("/");
+    if (uid) {
+      setUserId(uid);
+    }
+  }
+
+  setContexts(contexts: SelfDescribingJson<Record<string, unknown>>[]) {
+    this.contexts = contexts;
+    // Update identity context
+    const index = this.contexts?.findIndex(ctx =>
+      ctx.schema?.includes("identity_context"),
+    );
+    if (index > -1) {
+      this.contexts[index].data.domain_userid = this.uid;
+    }
+    return this;
+  }
+
+  // Send a page view event
+  trackView() {
+    if (this.trackPageView) {
+      trackPageView({ context: this.contexts });
+    }
+    return this;
+  }
+
+  // Send a structured event with contexts
+  async trackEvent(event: StructuredEvent) {
+    await trackStructEvent({ ...event, context: this.contexts }, [
+      this.bronzeAvalancheTrackerName,
+    ]);
+    return this;
+  }
+
+  // Send a custom event with defined schema and optional contexts
+  async trackUnstructEvent(event: SelfDescribingJson<Record<string, unknown>>) {
+    if (!event) {
+      return this;
+    }
+    await trackSelfDescribingEvent({ event, context: this.contexts }, [
+      this.avalancheTrackerName,
+    ]);
+    return this;
+  }
+
+  addEventHandlers(eventDefinitions: EventDefinition[]) {
+    eventDefinitions.forEach(({ name, type, makePayload }) => {
+      // Convert type into relevant function
+      if (type === "structured") {
+        this.addEventHandler(name, (params?: Record<string, unknown>) => {
+          this.trackEvent(makePayload(params) as StructuredEvent);
+        });
+      } else {
+        this.addEventHandler(name, (params?: Record<string, unknown>) => {
+          this.trackUnstructEvent(
+            makePayload(params) as SelfDescribingJson<Record<string, unknown>>,
+          );
+        });
+      }
+    });
+    return this;
+  }
+
+  private addEventHandler(
+    name: string,
+    handler: (params?: Record<string, unknown>) => void,
+  ) {
+    this.eventHandlers[name] = handler;
+    return this;
+  }
+
+  private removeEventHandler(name: string) {
+    delete this.eventHandlers[name];
+    return this;
+  }
+
+  trigger(name: string, params?: Record<string, unknown>) {
+    if (this.eventHandlers[name]) {
+      this.eventHandlers[name](params);
+    }
+    return this;
+  }
+}

package/src/services/snowplow/types.ts

@@ -0,0 +1,65 @@
+import {
+  EventMethod,
+  SelfDescribingJson,
+  StructuredEvent,
+} from "@snowplow/browser-tracker";
+
+type BaseConfig = {
+  appId: string;
+  avalancheCollector: string;
+  eventMethod: EventMethod;
+  trackPageView: boolean;
+  includeGAContext: boolean;
+  uid?: string;
+  postPath?: string;
+};
+
+export type EnvConfig = BaseConfig & {
+  cookieDomain: Record<string, string>;
+};
+
+export type TrackingProps = BaseConfig & {
+  eventMethod: EventMethod;
+  cookieDomain?: string;
+};
+
+export type ChannelContext = {
+  schema: string;
+  data: Record<string, string | number>;
+};
+
+export type ChannelContexts = Record<string, ChannelContext>;
+
+export type ArrayOneOrMore<T> = [T, ...T[]];
+
+export type ParamsType = Record<
+  | "label"
+  | "deviceType"
+  | "category"
+  | "product"
+  | "title"
+  | "label"
+  | "name"
+  | "fromValue"
+  | "toValue",
+  string
+>;
+
+export type EventDefinition = {
+  name: string;
+  type: "structured" | "unstructured";
+  makePayload: (
+    params?: Record<string, unknown>,
+  ) => StructuredEvent | SelfDescribingJson<Record<string, unknown>>;
+};
+
+export interface PageDataProps
+  extends Partial<
+    Record<
+      "scripts",
+      Array<{
+        metadata: { name: string };
+        props?: Record<string, unknown>;
+      }>
+    >
+  > {}

package/src/utils/index.ts

@@ -0,0 +1 @@
+export * from "./text";