medusa-storefront-analytics 1.2.0 → 1.4.0

package/src/providers/meta-pixel.ts

@@ -0,0 +1,77 @@
+/**
+ * Meta Pixel standard events — explicit fbq + dedicated dataLayer pushes.
+ */
+
+import {
+    META_STANDARD_EVENTS,
+    type EcommercePayload,
+    type MetaStandardEventName,
+} from "../events/meta-events";
+import { META_EXPLICIT_KEY } from "./meta-pixel-guard";
+
+export { META_STANDARD_EVENTS, type MetaStandardEventName, type EcommercePayload };
+
+export const META_PIXEL_DATALAYER_EVENT = "meta_pixel_track";
+
+type FbqFn = (...args: unknown[]) => void;
+
+function normalizeCurrency(currency?: string) {
+    return (currency ?? "INR").toUpperCase();
+}
+
+function buildMetaParams(payload: EcommercePayload) {
+    const items = payload.items ?? [];
+    const numItems = items.reduce((sum, i) => sum + (i.quantity ?? 1), 0);
+    return {
+        currency: normalizeCurrency(payload.currency),
+        value: payload.value,
+        content_ids: items.map((i) => String(i.item_id)),
+        content_type: "product",
+        contents: items.map((i) => ({
+            id: String(i.item_id),
+            quantity: i.quantity ?? 1,
+            item_price: i.price ?? 0,
+        })),
+        num_items: numItems,
+    };
+}
+
+function pushMetaDataLayer(metaEvent: MetaStandardEventName, params: Record<string, unknown>) {
+    if (typeof window === "undefined") return;
+    const w = window as Window & { dataLayer?: unknown[] };
+    w.dataLayer = w.dataLayer || [];
+    w.dataLayer.push({
+        event: META_PIXEL_DATALAYER_EVENT,
+        meta_event: metaEvent,
+        [META_EXPLICIT_KEY]: true,
+        ...params,
+    });
+}
+
+export function fireMetaPixelEvent(
+    metaEvent: MetaStandardEventName,
+    params: Record<string, unknown> = {}
+) {
+    pushMetaDataLayer(metaEvent, params);
+
+    if (typeof window === "undefined") return;
+    const fbq = (window as Window & { fbq?: FbqFn }).fbq;
+    if (typeof fbq === "function") {
+        fbq("track", metaEvent, { ...params, [META_EXPLICIT_KEY]: true });
+    }
+}
+
+export function fireMetaEcommerceEvent(
+    metaEvent: MetaStandardEventName,
+    payload: EcommercePayload,
+    extra?: Record<string, unknown>
+) {
+    fireMetaPixelEvent(metaEvent, { ...buildMetaParams(payload), ...extra });
+}
+
+export function fireMetaPurchase(payload: EcommercePayload & { transaction_id: string }) {
+    const { transaction_id, ...ecommerce } = payload;
+    fireMetaEcommerceEvent(META_STANDARD_EVENTS.Purchase, ecommerce, {
+        order_id: transaction_id,
+    });
+}