@tribe-nest/forge 3.60.0 → 3.61.0

package/src/ui/analytics/_tests/metaCommerceEvents.spec.tsx

@@ -0,0 +1,159 @@
+// @vitest-environment jsdom
+import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
+import { act, renderHook } from "@testing-library/react";
+import type { ReactNode } from "react";
+import { useMetaInitiateCheckout, useMetaPurchase, useMetaViewContent } from "../useMetaEvents";
+import { resetMetaPolicy, setMetaPolicy } from "../../../utils/metaEvents";
+import { saveCookieConsent, GRANT_ALL } from "../../../utils/cookieConsent";
+import { CartProvider, useCart, type CartItem, type TicketCartItem } from "../../../contexts/CartContext";
+import { ProductDeliveryType } from "../../../types/models";
+
+/**
+ * The commerce funnel's Meta events fire once per act: a re-render, a cart
+ * that refreshes, or a confirmation page reloaded in the same tab must not
+ * count a second ViewContent, InitiateCheckout or Purchase.
+ */
+
+let fetchSpy: ReturnType<typeof vi.fn>;
+let fbq: ReturnType<typeof vi.fn>;
+
+const posted = () => fetchSpy.mock.calls.map((c) => JSON.parse((c[1] as RequestInit).body as string));
+const pixel = () => fbq.mock.calls.filter((c) => c[0] === "trackSingle");
+
+beforeEach(() => {
+  resetMetaPolicy();
+  window.localStorage.clear();
+  window.sessionStorage.clear();
+  fetchSpy = vi.fn().mockResolvedValue({ ok: true });
+  vi.stubGlobal("fetch", fetchSpy);
+  fbq = vi.fn();
+  (window as unknown as { fbq: unknown }).fbq = fbq;
+  saveCookieConsent(GRANT_ALL);
+  setMetaPolicy({
+    pixelId: "777",
+    enabled: true,
+    requireConsent: true,
+    apiUrl: "https://api.test",
+    subdomain: "artist",
+    currency: "GBP",
+    resolved: true,
+  });
+});
+
+afterEach(() => {
+  vi.unstubAllGlobals();
+  resetMetaPolicy();
+});
+
+describe("InitiateCheckout", () => {
+  const line = { productId: "p1", quantity: 2 };
+
+  it("fires once per mount, after the cart is ready and not empty", () => {
+    const { rerender } = renderHook((props: Parameters<typeof useMetaInitiateCheckout>[0]) => useMetaInitiateCheckout(props), {
+      initialProps: { ready: false, cartItems: [], ticketItems: [], subTotal: 0 } as Parameters<typeof useMetaInitiateCheckout>[0],
+    });
+    expect(posted()).toEqual([]);
+
+    rerender({ ready: true, cartItems: [line], ticketItems: [{ eventId: "e1", tickets: { t1: 3 } }], subTotal: 80 });
+    rerender({ ready: true, cartItems: [line], ticketItems: [], subTotal: 50 });
+
+    expect(posted()).toHaveLength(1);
+    expect(posted()[0]).toMatchObject({
+      pixel: "profile",
+      eventName: "InitiateCheckout",
+      customData: { value: 80, currency: "GBP", num_items: 5, content_ids: ["p1", "e1"], content_type: "product" },
+    });
+    expect(pixel()[0][4]).toEqual({ eventID: posted()[0].eventId });
+  });
+
+  it("does not fire for an empty cart", () => {
+    renderHook(() => useMetaInitiateCheckout({ ready: true, cartItems: [], ticketItems: [], subTotal: 0 }));
+    expect(posted()).toEqual([]);
+  });
+});
+
+describe("Purchase", () => {
+  it("fires once with the record id, and not again after a reload", () => {
+    const props = { recordId: "order-9", paid: true, value: 30, currency: "usd" };
+    const first = renderHook(() => useMetaPurchase(props));
+    first.rerender();
+    first.unmount();
+    // A reload: a fresh mount in the same tab.
+    renderHook(() => useMetaPurchase(props));
+
+    expect(pixel()).toEqual([["trackSingle", "777", "Purchase", { value: 30, currency: "USD" }, { eventID: "order-9" }]]);
+    expect(fetchSpy).not.toHaveBeenCalled();
+  });
+
+  it("waits for the record to be paid", () => {
+    const { rerender } = renderHook((p: { paid: boolean }) => useMetaPurchase({ recordId: "order-10", value: 30, ...p }), {
+      initialProps: { paid: false },
+    });
+    expect(pixel()).toEqual([]);
+    rerender({ paid: true });
+    expect(pixel()).toHaveLength(1);
+  });
+});
+
+describe("ViewContent", () => {
+  it("fires once per entity and again for a different one", () => {
+    const { rerender } = renderHook((e: { id: string; name: string; value: number }) => useMetaViewContent(e), {
+      initialProps: { id: "c1", name: "Course", value: 99 },
+    });
+    rerender({ id: "c1", name: "Course", value: 99 });
+    rerender({ id: "c2", name: "Other", value: 10 });
+
+    expect(posted().map((b) => [b.eventName, b.customData])).toEqual([
+      ["ViewContent", { content_ids: ["c1"], content_name: "Course", content_type: "product", value: 99, currency: "GBP" }],
+      ["ViewContent", { content_ids: ["c2"], content_name: "Other", content_type: "product", value: 10, currency: "GBP" }],
+    ]);
+  });
+});
+
+describe("AddToCart", () => {
+  const wrapper = ({ children }: { children: ReactNode }) => <CartProvider>{children}</CartProvider>;
+  const item: CartItem = {
+    productId: "prod-1",
+    productVariantId: "var-1",
+    title: "Tour Tee",
+    price: 25,
+    isGift: false,
+    canIncreaseQuantity: true,
+    quantity: 2,
+    payWhatYouWant: false,
+    deliveryType: ProductDeliveryType.Physical,
+  };
+
+  it("fires for a new line and not for a duplicate", () => {
+    const { result } = renderHook(() => useCart(), { wrapper });
+    act(() => void result.current.addToCart(item));
+    act(() => void result.current.addToCart(item));
+
+    expect(posted().map((b) => [b.eventName, b.customData])).toEqual([
+      [
+        "AddToCart",
+        { content_ids: ["prod-1"], content_name: "Tour Tee", content_type: "product", value: 50, num_items: 2, currency: "GBP" },
+      ],
+    ]);
+  });
+
+  it("fires for tickets only when the selection grows", () => {
+    const { result } = renderHook(() => useCart(), { wrapper });
+    const selection = (qty: number): TicketCartItem => ({
+      eventId: "event-1",
+      eventSlug: "tour",
+      eventTitle: "Spring Tour",
+      tickets: { ga: qty },
+      ticketMeta: { ga: { title: "GA", price: 15 } },
+    });
+    act(() => result.current.setTickets(selection(2)));
+    act(() => result.current.setTickets(selection(1)));
+    act(() => result.current.setTickets(selection(3)));
+
+    expect(posted().map((b) => [b.customData.num_items, b.customData.value])).toEqual([
+      [2, 30],
+      [2, 30],
+    ]);
+    expect(posted()[0].customData.content_ids).toEqual(["event-1"]);
+  });
+});

package/src/ui/analytics/useMetaEvents.ts

@@ -0,0 +1,78 @@
+import { useEffect, useRef } from "react";
+import { trackMeta, trackPurchase } from "../../utils/metaEvents";
+
+export type MetaViewContentInput = {
+  id: string;
+  name?: string;
+  /** The lowest (or selected) price, major units. Ignored unless a finite number. */
+  value?: number | string | null;
+};
+
+/**
+ * Fire `ViewContent` once per loaded entity: a new id (navigating to another
+ * product) fires again, a re-render does not. Pass `null` while loading.
+ */
+export function useMetaViewContent(entity: MetaViewContentInput | null | undefined): void {
+  const firedFor = useRef<string | null>(null);
+  const id = entity?.id;
+  const name = entity?.name;
+  const value = entity?.value;
+  useEffect(() => {
+    if (!id || firedFor.current === id) return;
+    firedFor.current = id;
+    const n = value === null || value === undefined || value === "" ? NaN : Number(value);
+    trackMeta("ViewContent", {
+      content_ids: [id],
+      content_name: name,
+      content_type: "product",
+      value: Number.isFinite(n) ? n : undefined,
+    });
+  }, [id, name, value]);
+}
+
+/**
+ * Fire `InitiateCheckout` once per mount, as soon as the saved cart has loaded
+ * and holds something. Value is the cart's own estimate, before shipping and
+ * coupons.
+ */
+export function useMetaInitiateCheckout(input: {
+  ready: boolean;
+  cartItems: { productId: string; quantity: number }[];
+  ticketItems: { eventId: string; tickets: Record<string, number> }[];
+  subTotal: number;
+}): void {
+  const fired = useRef(false);
+  const { ready, cartItems, ticketItems, subTotal } = input;
+  const hasLines = cartItems.length > 0 || ticketItems.length > 0;
+  useEffect(() => {
+    if (fired.current || !ready || !hasLines) return;
+    fired.current = true;
+    const numItems =
+      cartItems.reduce((sum, item) => sum + (item.quantity || 0), 0) +
+      ticketItems.reduce((sum, t) => sum + Object.values(t.tickets).reduce((a, b) => a + b, 0), 0);
+    trackMeta("InitiateCheckout", {
+      value: subTotal,
+      num_items: numItems,
+      content_ids: [...cartItems.map((item) => item.productId), ...ticketItems.map((t) => t.eventId)],
+      content_type: "product",
+    });
+  }, [ready, hasLines, cartItems, ticketItems, subTotal]);
+}
+
+/**
+ * Fire the browser copy of `Purchase` on a confirmation page once the record
+ * is paid. The id is the record id the server bridge used, so the two dedupe;
+ * a reload in the same tab does not fire it again.
+ */
+export function useMetaPurchase(input: {
+  recordId?: string | null;
+  paid: boolean;
+  value?: number | string | null;
+  currency?: string | null;
+}): void {
+  const { recordId, paid, value, currency } = input;
+  useEffect(() => {
+    if (!paid || !recordId) return;
+    trackPurchase({ recordId, value, currency });
+  }, [paid, recordId, value, currency]);
+}