feat: add support for conversion subtypes (#486)

This adds support for the addToCart and purchase subtypes of the
conversion event type.

EEX-696

lib/__tests__/conversion.test.ts

@@ -56,6 +56,76 @@ describe("convertedObjectIDsAfterSearch", () => {
   });
 });
 
+describe("addedToCartObjectIDsAfterSearch", () => {
+  const convertParams = {
+    index: "index1",
+    eventName: "Product added to cart",
+    objectIDs: ["12345"],
+    queryID: "test"
+  };
+
+  it("should call sendEvents with proper params", () => {
+    analyticsInstance.addedToCartObjectIDsAfterSearch(convertParams);
+    expect((analyticsInstance as any).sendEvents).toHaveBeenCalledWith(
+      [
+        {
+          eventType: "conversion",
+          eventSubtype: "addToCart",
+          ...convertParams
+        }
+      ],
+      undefined
+    );
+  });
+
+  it("should call sendEvents with additional params if provided", () => {
+    analyticsInstance.addedToCartObjectIDsAfterSearch(
+      convertParams,
+      additionalParameters
+    );
+
+    expect(analyticsInstance.sendEvents).toHaveBeenCalledWith(
+      expect.any(Array),
+      additionalParameters
+    );
+  });
+});
+
+describe("purchasedObjectIDsAfterSearch", () => {
+  const convertParams = {
+    index: "index1",
+    eventName: "Product added to cart",
+    objectIDs: ["12345"],
+    queryID: "test"
+  };
+
+  it("should call sendEvents with proper params", () => {
+    analyticsInstance.purchasedObjectIDsAfterSearch(convertParams);
+    expect((analyticsInstance as any).sendEvents).toHaveBeenCalledWith(
+      [
+        {
+          eventType: "conversion",
+          eventSubtype: "purchase",
+          ...convertParams
+        }
+      ],
+      undefined
+    );
+  });
+
+  it("should call sendEvents with additional params if provided", () => {
+    analyticsInstance.purchasedObjectIDsAfterSearch(
+      convertParams,
+      additionalParameters
+    );
+
+    expect(analyticsInstance.sendEvents).toHaveBeenCalledWith(
+      expect.any(Array),
+      additionalParameters
+    );
+  });
+});
+
 describe("convertedObjectIDs", () => {
   const convertParams = {
     index: "index1",
@@ -86,6 +156,68 @@ describe("convertedObjectIDs", () => {
   });
 });
 
+describe("addedToCartObjectIDs", () => {
+  const convertParams = {
+    index: "index1",
+    eventName: "hit converted",
+    objectIDs: ["12345"]
+  };
+
+  it("should call sendEvents with proper params", () => {
+    analyticsInstance.addedToCartObjectIDs(convertParams);
+    expect((analyticsInstance as any).sendEvents).toHaveBeenCalledWith(
+      [
+        {
+          eventType: "conversion",
+          eventSubtype: "addToCart",
+          ...convertParams
+        }
+      ],
+      undefined
+    );
+  });
+
+  it("should call sendEvents with additional params if provided", () => {
+    analyticsInstance.addedToCartObjectIDs(convertParams, additionalParameters);
+
+    expect(analyticsInstance.sendEvents).toHaveBeenCalledWith(
+      expect.any(Array),
+      additionalParameters
+    );
+  });
+});
+
+describe("purchasedObjectIDs", () => {
+  const convertParams = {
+    index: "index1",
+    eventName: "hit converted",
+    objectIDs: ["12345"]
+  };
+
+  it("should call sendEvents with proper params", () => {
+    analyticsInstance.purchasedObjectIDs(convertParams);
+    expect((analyticsInstance as any).sendEvents).toHaveBeenCalledWith(
+      [
+        {
+          eventType: "conversion",
+          eventSubtype: "purchase",
+          ...convertParams
+        }
+      ],
+      undefined
+    );
+  });
+
+  it("should call sendEvents with additional params if provided", () => {
+    analyticsInstance.purchasedObjectIDs(convertParams, additionalParameters);
+
+    expect(analyticsInstance.sendEvents).toHaveBeenCalledWith(
+      expect.any(Array),
+      additionalParameters
+    );
+  });
+});
+
 describe("convertedFilters", () => {
   const convertParams = {
     index: "index1",

lib/_addEventType.ts

@@ -1,4 +1,8 @@
-import { InsightsEvent, InsightsEventType } from "./types";
+import {
+  InsightsEvent,
+  InsightsEventConversionSubType,
+  InsightsEventType
+} from "./types";
 
 export function addEventType(
   eventType: InsightsEventType,
@@ -9,3 +13,15 @@ export function addEventType(
     ...event
   }));
 }
+
+export function addEventTypeAndSubtype(
+  eventType: InsightsEventType,
+  eventSubtype: InsightsEventConversionSubType,
+  params: Array<Omit<InsightsEvent, "eventType" | "eventSubtype">>
+): InsightsEvent[] {
+  return params.map((event) => ({
+    eventType,
+    eventSubtype,
+    ...event
+  }));
+}

lib/conversion.ts

@@ -1,6 +1,7 @@
-import { addEventType } from "./_addEventType";
+import { addEventType, addEventTypeAndSubtype } from "./_addEventType";
 import AlgoliaAnalytics from "./insights";
 import { extractAdditionalParams, WithAdditionalParams } from "./utils";
+import { InsightsEvent } from "./types";
 
 export interface InsightsSearchConversionEvent {
   eventName: string;
@@ -10,6 +11,7 @@ export interface InsightsSearchConversionEvent {
 
   queryID: string;
   objectIDs: string[];
+  objectData?: InsightsEvent["objectData"];
 }
 
 export function convertedObjectIDsAfterSearch(
@@ -22,13 +24,40 @@ export function convertedObjectIDsAfterSearch(
   return this.sendEvents(addEventType("conversion", events), additionalParams);
 }
 
+export function addedToCartObjectIDsAfterSearch(
+  this: AlgoliaAnalytics,
+  ...params: WithAdditionalParams<InsightsSearchConversionEvent>[]
+) {
+  const { events, additionalParams } =
+    extractAdditionalParams<InsightsSearchConversionEvent>(params);
+
+  return this.sendEvents(
+    addEventTypeAndSubtype("conversion", "addToCart", events),
+    additionalParams
+  );
+}
+
+export function purchasedObjectIDsAfterSearch(
+  this: AlgoliaAnalytics,
+  ...params: WithAdditionalParams<InsightsSearchConversionEvent>[]
+) {
+  const { events, additionalParams } =
+    extractAdditionalParams<InsightsSearchConversionEvent>(params);
+
+  return this.sendEvents(
+    addEventTypeAndSubtype("conversion", "purchase", events),
+    additionalParams
+  );
+}
+
 export interface InsightsSearchConversionObjectIDsEvent {
   eventName: string;
   userToken?: string;
   timestamp?: number;
   index: string;
 
   objectIDs: string[];
+  objectData?: InsightsEvent["objectData"];
 }
 
 export function convertedObjectIDs(
@@ -41,6 +70,32 @@ export function convertedObjectIDs(
   return this.sendEvents(addEventType("conversion", events), additionalParams);
 }
 
+export function addedToCartObjectIDs(
+  this: AlgoliaAnalytics,
+  ...params: WithAdditionalParams<InsightsSearchConversionObjectIDsEvent>[]
+) {
+  const { events, additionalParams } =
+    extractAdditionalParams<InsightsSearchConversionObjectIDsEvent>(params);
+
+  return this.sendEvents(
+    addEventTypeAndSubtype("conversion", "addToCart", events),
+    additionalParams
+  );
+}
+
+export function purchasedObjectIDs(
+  this: AlgoliaAnalytics,
+  ...params: WithAdditionalParams<InsightsSearchConversionObjectIDsEvent>[]
+) {
+  const { events, additionalParams } =
+    extractAdditionalParams<InsightsSearchConversionObjectIDsEvent>(params);
+
+  return this.sendEvents(
+    addEventTypeAndSubtype("conversion", "purchase", events),
+    additionalParams
+  );
+}
+
 export interface InsightsSearchConversionFiltersEvent {
   eventName: string;
   userToken?: string;

lib/insights.ts

@@ -19,7 +19,11 @@ import {
 } from "./click";
 import {
   convertedObjectIDsAfterSearch,
+  addedToCartObjectIDsAfterSearch,
+  purchasedObjectIDsAfterSearch,
   convertedObjectIDs,
+  addedToCartObjectIDs,
+  purchasedObjectIDs,
   convertedFilters
 } from "./conversion";
 import { viewedObjectIDs, viewedFilters } from "./view";
@@ -87,7 +91,11 @@ class AlgoliaAnalytics {
   public clickedFilters: typeof clickedFilters;
 
   public convertedObjectIDsAfterSearch: typeof convertedObjectIDsAfterSearch;
+  public purchasedObjectIDsAfterSearch: typeof purchasedObjectIDsAfterSearch;
+  public addedToCartObjectIDsAfterSearch: typeof addedToCartObjectIDsAfterSearch;
   public convertedObjectIDs: typeof convertedObjectIDs;
+  public addedToCartObjectIDs: typeof addedToCartObjectIDs;
+  public purchasedObjectIDs: typeof purchasedObjectIDs;
   public convertedFilters: typeof convertedFilters;
 
   public viewedObjectIDs: typeof viewedObjectIDs;
@@ -111,7 +119,13 @@ class AlgoliaAnalytics {
 
     this.convertedObjectIDsAfterSearch =
       convertedObjectIDsAfterSearch.bind(this);
+    this.purchasedObjectIDsAfterSearch =
+      purchasedObjectIDsAfterSearch.bind(this);
+    this.addedToCartObjectIDsAfterSearch =
+      addedToCartObjectIDsAfterSearch.bind(this);
     this.convertedObjectIDs = convertedObjectIDs.bind(this);
+    this.addedToCartObjectIDs = addedToCartObjectIDs.bind(this);
+    this.purchasedObjectIDs = purchasedObjectIDs.bind(this);
     this.convertedFilters = convertedFilters.bind(this);
 
     this.viewedObjectIDs = viewedObjectIDs.bind(this);

lib/types.ts

@@ -78,9 +78,17 @@ export type InsightsClient = (<MethodName extends keyof InsightsMethodMap>(
 ) => void) & { version?: string };
 
 export type InsightsEventType = "click" | "conversion" | "view";
+export type InsightsEventConversionSubType = "addToCart" | "purchase";
+
+export type InsightsEventObjectData = {
+  price?: number;
+  discount?: number;
+  quantity?: number;
+};
 
 export type InsightsEvent = {
   eventType: InsightsEventType;
+  eventSubtype?: InsightsEventConversionSubType;
 
   eventName: string;
   userToken?: string | number;
@@ -90,6 +98,7 @@ export type InsightsEvent = {
   queryID?: string;
   objectIDs?: string[];
   positions?: number[];
+  objectData?: InsightsEventObjectData[];
 
   filters?: string[];
 };