@tagadapay/plugin-sdk 3.1.5 → 3.1.9

package/dist/v2/react/hooks/usePixelTracking.js

@@ -0,0 +1,508 @@
+'use client';
+import { jsx as _jsx } from "react/jsx-runtime";
+/**
+ * usePixelTracking Hook & Provider
+ *
+ * SDK-level pixel tracking based on runtime stepConfig.pixels injected
+ * by the CRM. This mirrors the CMS pixel context pattern but uses the
+ * funnel step configuration as the source of truth instead of store
+ * integrations.
+ */
+import { createContext, useCallback, useContext, useEffect, useMemo, useRef, useState, } from 'react';
+import { minorUnitsToMajorUnits } from '../../../react/utils/money';
+import { useStepConfig } from './useStepConfig';
+const PixelTrackingContext = createContext(null);
+/**
+ * Simple per-page duplicate guard (time-window based)
+ * Avoids accidental double-fires during rerenders.
+ */
+function createDuplicateGuard(windowMs) {
+    const lastEvents = new Map();
+    return (eventName, parameters) => {
+        try {
+            const key = JSON.stringify({ eventName, parameters });
+            const now = Date.now();
+            const last = lastEvents.get(key);
+            if (last && now - last < windowMs)
+                return false;
+            lastEvents.set(key, now);
+            return true;
+        }
+        catch {
+            // If hashing fails for any reason, just allow the event
+            return true;
+        }
+    };
+}
+const shouldTrackEvent = createDuplicateGuard(5000);
+/**
+ * Provider that initializes pixels based on stepConfig.pixels
+ * and exposes a simple track(event, params) API.
+ */
+export function PixelTrackingProvider({ children }) {
+    const { pixels } = useStepConfig();
+    const [pixelsInitialized, setPixelsInitialized] = useState(false);
+    const isMountedRef = useRef(true);
+    useEffect(() => {
+        isMountedRef.current = true;
+        return () => {
+            isMountedRef.current = false;
+        };
+    }, []);
+    // Initialize pixels once when configuration is available
+    useEffect(() => {
+        if (!pixels || pixelsInitialized || !isMountedRef.current)
+            return;
+        try {
+            // Facebook / Meta - support multiple pixels
+            const facebookPixels = pixels.facebook; // Support both 'facebook' and legacy 'meta'
+            if (facebookPixels) {
+                if (Array.isArray(facebookPixels)) {
+                    facebookPixels.forEach((pixel) => {
+                        if (pixel.enabled && pixel.pixelId) {
+                            initMetaPixel(pixel.pixelId);
+                        }
+                    });
+                }
+            }
+            // TikTok - support multiple pixels
+            const tiktokPixels = pixels.tiktok;
+            if (tiktokPixels) {
+                if (Array.isArray(tiktokPixels)) {
+                    tiktokPixels.forEach((pixel) => {
+                        if (pixel.enabled && pixel.pixelId) {
+                            initTikTokPixel(pixel.pixelId);
+                        }
+                    });
+                }
+            }
+            // Snapchat - support multiple pixels
+            const snapchatPixels = pixels.snapchat;
+            if (snapchatPixels) {
+                if (Array.isArray(snapchatPixels)) {
+                    snapchatPixels.forEach((pixel) => {
+                        if (pixel.enabled && pixel.pixelId) {
+                            initSnapchatPixel(pixel.pixelId);
+                        }
+                    });
+                }
+            }
+            // GTM - support multiple containers
+            const gtmPixels = pixels.gtm;
+            if (gtmPixels) {
+                if (Array.isArray(gtmPixels)) {
+                    gtmPixels.forEach((pixel) => {
+                        if (pixel.enabled && pixel.containerId) {
+                            initGTM(pixel.containerId);
+                        }
+                    });
+                }
+            }
+            if (isMountedRef.current) {
+                setPixelsInitialized(true);
+            }
+        }
+        catch (error) {
+            // Fail-safe: never break the host page because of pixel issues
+            if (typeof console !== 'undefined') {
+                console.error('[SDK Pixels] Error during pixel initialization:', error);
+            }
+        }
+    }, [pixels, pixelsInitialized]);
+    const track = useCallback((eventName, parameters = {}) => {
+        if (!pixels || !pixelsInitialized || !isMountedRef.current) {
+            return;
+        }
+        // Duplicate guard
+        if (!shouldTrackEvent(eventName, parameters)) {
+            return;
+        }
+        try {
+            // Facebook / Meta - track to all enabled pixels
+            const facebookPixels = pixels.facebook; // Support both 'facebook' and legacy 'meta'
+            if (facebookPixels) {
+                const pixelArray = Array.isArray(facebookPixels)
+                    ? facebookPixels
+                    : [facebookPixels];
+                const enabledPixels = pixelArray.filter((p) => p.enabled);
+                if (enabledPixels.length > 0) {
+                    const { name, params } = mapMetaEvent(eventName, parameters);
+                    // Track to all enabled Facebook pixels
+                    enabledPixels.forEach(() => {
+                        trackMetaEvent(name, params);
+                    });
+                }
+            }
+            // TikTok - track to all enabled pixels
+            const tiktokPixels = pixels.tiktok;
+            if (tiktokPixels) {
+                const pixelArray = Array.isArray(tiktokPixels)
+                    ? tiktokPixels
+                    : [tiktokPixels];
+                const enabledPixels = pixelArray.filter((p) => p.enabled);
+                if (enabledPixels.length > 0) {
+                    const { name, params } = mapTikTokEvent(eventName, parameters);
+                    // Track to all enabled TikTok pixels
+                    enabledPixels.forEach(() => {
+                        trackTikTokEvent(name, params);
+                    });
+                }
+            }
+            // Snapchat - track to all enabled pixels
+            const snapchatPixels = pixels.snapchat;
+            if (snapchatPixels) {
+                const pixelArray = Array.isArray(snapchatPixels)
+                    ? snapchatPixels
+                    : [snapchatPixels];
+                const enabledPixels = pixelArray.filter((p) => p.enabled);
+                if (enabledPixels.length > 0) {
+                    const { name, params } = mapSnapchatEvent(eventName, parameters);
+                    // Track to all enabled Snapchat pixels
+                    enabledPixels.forEach(() => {
+                        trackSnapchatEvent(name, params);
+                    });
+                }
+            }
+            // GTM - track to all enabled containers
+            const gtmPixels = pixels.gtm;
+            if (gtmPixels) {
+                const pixelArray = Array.isArray(gtmPixels)
+                    ? gtmPixels
+                    : [gtmPixels];
+                const enabledPixels = pixelArray.filter((p) => p.enabled);
+                if (enabledPixels.length > 0) {
+                    const { name, params } = mapGTMEvent(eventName, parameters);
+                    // Track to all enabled GTM containers
+                    enabledPixels.forEach(() => {
+                        console.log('trackGTMEvent', name, params);
+                        trackGTMEvent(name, params);
+                    });
+                }
+            }
+        }
+        catch (error) {
+            if (typeof console !== 'undefined') {
+                console.error('[SDK Pixels] Error tracking pixel event:', error);
+            }
+        }
+    }, [pixels, pixelsInitialized]);
+    // Track page views automatically when pixels are initialized
+    useEffect(() => {
+        if (!pixelsInitialized || !isMountedRef.current)
+            return;
+        // Small delay to ensure we don't double fire during strict mode remounts
+        const pageViewTimeoutId = setTimeout(() => {
+            if (isMountedRef.current) {
+                track('PageView', {
+                    path: typeof window !== 'undefined' ? window.location.pathname : '',
+                });
+            }
+        }, 0);
+        return () => {
+            if (pageViewTimeoutId) {
+                clearTimeout(pageViewTimeoutId);
+            }
+        };
+    }, [pixelsInitialized, track]);
+    const value = useMemo(() => ({
+        track,
+        pixelsInitialized,
+    }), [track, pixelsInitialized]);
+    return _jsx(PixelTrackingContext.Provider, { value: value, children: children });
+}
+/**
+ * Hook to access SDK pixel tracking.
+ * Must be used within TagadaProvider (which wraps PixelTrackingProvider).
+ */
+export function usePixelTracking() {
+    const context = useContext(PixelTrackingContext);
+    if (!context) {
+        throw new Error('usePixelTracking must be used within a PixelTrackingProvider');
+    }
+    return context;
+}
+function initMetaPixel(pixelId) {
+    if (typeof window === 'undefined')
+        return;
+    if (window.fbq)
+        return;
+    // Standard Facebook Pixel bootstrap
+    (function (f, b, e) {
+        if (f.fbq)
+            return;
+        const n = function (...args) {
+            if (n.callMethod) {
+                n.callMethod(...args);
+            }
+            else {
+                n.queue.push(args);
+            }
+        };
+        f.fbq = n;
+        if (!f._fbq)
+            f._fbq = n;
+        n.queue = n.queue ?? [];
+        n.loaded = true;
+        n.version = '2.0';
+        n.queue = [];
+        const t = b.createElement(e);
+        t.async = true;
+        t.src = 'https://connect.facebook.net/en_US/fbevents.js';
+        const s = b.getElementsByTagName(e)[0];
+        s.parentNode?.insertBefore(t, s);
+    })(window, document, 'script');
+    const fbq = window.fbq;
+    if (fbq) {
+        fbq('init', pixelId);
+    }
+}
+function trackMetaEvent(name, params) {
+    if (typeof window === 'undefined' || !window.fbq)
+        return;
+    const fbq = window.fbq;
+    fbq?.('track', name, params);
+}
+function initTikTokPixel(pixelId) {
+    if (typeof window === 'undefined')
+        return;
+    if (window.ttq)
+        return;
+    (function (w, d, t) {
+        const ttq = w.ttq ||
+            function (...args) {
+                ttq.queue.push(args);
+            };
+        if (!ttq.queue) {
+            ttq.queue = [];
+        }
+        w.ttq = ttq;
+        ttq.methods = [
+            'page',
+            'track',
+            'identify',
+            'instances',
+            'debug',
+            'on',
+            'off',
+            'once',
+            'ready',
+            'alias',
+            'group',
+            'enableCookie',
+            'disableCookie',
+        ];
+        ttq.setAndDefer = function (target, method) {
+            target[method] = function (...args) {
+                target.queue.push([method, ...args]);
+            };
+        };
+        for (const method of ttq.methods) {
+            ttq.setAndDefer(ttq, method);
+        }
+        ttq.load = function (e) {
+            const n = 'https://analytics.tiktok.com/i18n/pixel/events.js';
+            const a = d.createElement(t);
+            a.type = 'text/javascript';
+            a.async = true;
+            a.src = n + '?sdkid=' + e + '&lib=ttq';
+            const s = d.getElementsByTagName(t)[0];
+            s.parentNode.insertBefore(a, s);
+        };
+    })(window, document, 'script');
+    const ttqInstance = window.ttq;
+    if (!ttqInstance)
+        return;
+    ttqInstance.load?.(pixelId);
+    ttqInstance.page?.();
+}
+function trackTikTokEvent(name, params) {
+    if (typeof window === 'undefined' || !window.ttq)
+        return;
+    const ttq = window.ttq;
+    ttq?.track?.(name, params);
+}
+function initSnapchatPixel(pixelId) {
+    if (typeof window === 'undefined')
+        return;
+    if (window.snaptr)
+        return;
+    (function (w, d, tagName) {
+        if (w.snaptr)
+            return;
+        const a = (function (...args) {
+            if (a.handleRequest) {
+                a.handleRequest(...args);
+            }
+            else {
+                a.queue.push(args);
+            }
+        });
+        a.queue = [];
+        w.snaptr = a;
+        const s = 'script';
+        const r = d.createElement(s);
+        r.async = true;
+        r.src = 'https://sc-static.net/scevent.min.js';
+        const u = d.getElementsByTagName(tagName)[0];
+        u.parentNode?.insertBefore(r, u);
+    })(window, document, 'script');
+    const snaptr = window.snaptr;
+    snaptr?.('init', pixelId);
+}
+function trackSnapchatEvent(name, params) {
+    if (typeof window === 'undefined' || !window.snaptr)
+        return;
+    const snaptr = window.snaptr;
+    snaptr?.('track', name, params);
+}
+function initGTM(containerId) {
+    if (typeof window === 'undefined' || typeof document === 'undefined')
+        return;
+    if (!containerId)
+        return;
+    // Check if GTM script is already loaded for this container
+    const existingScript = document.querySelector(`script[src*="googletagmanager.com/gtm.js?id=${containerId}"]`);
+    if (existingScript) {
+        return; // GTM already initialized for this container
+    }
+    // Initialize dataLayer before GTM script (Google's official pattern)
+    window.dataLayer = window.dataLayer || [];
+    // Push gtm.start event (must be done before script loads)
+    window.dataLayer.push({
+        'gtm.start': new Date().getTime(),
+        event: 'gtm.js',
+    });
+    // Create and inject GTM script (Google's official pattern)
+    // This matches Google's exact implementation from their documentation
+    (function (w, d, s, l, i) {
+        const f = d.getElementsByTagName(s)[0];
+        const j = d.createElement(s);
+        const dl = l != 'dataLayer' ? '&l=' + l : '';
+        j.async = true;
+        j.src = 'https://www.googletagmanager.com/gtm.js?id=' + i + dl;
+        // Insert before first script tag (typically in head)
+        if (f && f.parentNode) {
+            f.parentNode.insertBefore(j, f);
+        }
+        else {
+            // Fallback: append to head if no script tags found
+            const head = d.head || d.getElementsByTagName('head')[0];
+            if (head) {
+                head.appendChild(j);
+            }
+        }
+    })(window, document, 'script', 'dataLayer', containerId);
+    // Also add noscript fallback in body (Google's official pattern)
+    // This ensures GTM works even if JavaScript is disabled
+    const noscript = document.createElement('noscript');
+    const iframe = document.createElement('iframe');
+    iframe.src = `https://www.googletagmanager.com/ns.html?id=${containerId}`;
+    iframe.height = '0';
+    iframe.width = '0';
+    iframe.style.display = 'none';
+    iframe.style.visibility = 'hidden';
+    noscript.appendChild(iframe);
+    // Insert noscript at the beginning of body
+    const body = document.body || document.getElementsByTagName('body')[0];
+    if (body) {
+        body.insertBefore(noscript, body.firstChild);
+    }
+}
+function trackGTMEvent(event, params = {}) {
+    if (typeof window === 'undefined') {
+        console.warn('[SDK GTM] Window not available, event not tracked:', event);
+        return;
+    }
+    // Ensure dataLayer exists (should be initialized by initGTM, but double-check)
+    if (!window.dataLayer) {
+        console.warn('[SDK GTM] dataLayer not initialized, initializing now...');
+        window.dataLayer = [];
+    }
+    try {
+        const eventData = {
+            event,
+            ...params,
+        };
+        console.log('[SDK GTM] Pushing event to dataLayer:', eventData);
+        window.dataLayer.push(eventData);
+        console.log('[SDK GTM] Event pushed successfully. Current dataLayer length:', window.dataLayer.length);
+    }
+    catch (error) {
+        if (typeof console !== 'undefined') {
+            console.error('[SDK GTM] Error tracking event:', error);
+        }
+    }
+}
+// --- Basic event mapping (can be extended later if needed) ---
+function mapMetaEvent(eventName, parameters) {
+    return { name: eventName, params: parameters };
+}
+function mapTikTokEvent(eventName, parameters) {
+    // TikTok naming is usually aligned; adjust here if needed later
+    return { name: eventName, params: parameters };
+}
+function mapSnapchatEvent(eventName, parameters) {
+    return { name: eventName, params: parameters };
+}
+function mapGTMEvent(eventName, parameters) {
+    // Map standard event names to GTM event names
+    const gtmEventMap = {
+        PageView: 'page_view',
+        AddPaymentInfo: 'add_payment_info',
+        AddToCart: 'add_to_cart',
+        InitiateCheckout: 'begin_checkout',
+        Purchase: 'purchase',
+        ViewContent: 'view_item',
+        CompleteRegistration: 'sign_up',
+    };
+    const gtmEventName = gtmEventMap[eventName] ?? eventName.toLowerCase();
+    // Transform parameters for GTM
+    const gtmParams = transformGTMParameters(eventName, parameters);
+    return { name: gtmEventName, params: gtmParams };
+}
+function transformGTMParameters(eventName, parameters) {
+    const gtmParameters = { ...parameters };
+    // Ensure currency is uppercase
+    if (gtmParameters.currency) {
+        gtmParameters.currency = String(gtmParameters.currency).toUpperCase();
+    }
+    // Transform currency values to major units if needed
+    if (gtmParameters.currency && gtmParameters.value) {
+        try {
+            gtmParameters.value = minorUnitsToMajorUnits(Number(gtmParameters.value), String(gtmParameters.currency));
+        }
+        catch (error) {
+            // If conversion fails, try simple division by 100 as fallback
+            if (typeof console !== 'undefined') {
+                console.warn('[SDK GTM] Currency conversion failed, using fallback:', error);
+            }
+            gtmParameters.value = Number(gtmParameters.value) / 100;
+        }
+    }
+    // Ensure numeric values
+    if (gtmParameters.value !== undefined) {
+        gtmParameters.value = Number(gtmParameters.value);
+    }
+    if (gtmParameters.num_items !== undefined) {
+        gtmParameters.num_items = Number(gtmParameters.num_items);
+    }
+    // Transform contents to a format better suited for GTM
+    if (gtmParameters.contents && Array.isArray(gtmParameters.contents)) {
+        gtmParameters.items = gtmParameters.contents.map((item) => ({
+            item_id: item.content_id,
+            item_name: item.content_name,
+            item_category: item.content_category,
+            price: item.price ? Number(item.price) : undefined,
+            quantity: item.quantity ? Number(item.quantity) : undefined,
+        }));
+        // Keep original contents for compatibility
+        gtmParameters.contents = gtmParameters.contents.map((item) => ({
+            id: item.content_id,
+            name: item.content_name,
+            category: item.content_category,
+            price: item.price ? Number(item.price) : undefined,
+            quantity: item.quantity ? Number(item.quantity) : undefined,
+        }));
+    }
+    return gtmParameters;
+}

package/dist/v2/react/hooks/useStepConfig.d.ts

@@ -0,0 +1,64 @@
+/**
+ * useStepConfig Hook - Access runtime step configuration from HTML injection
+ *
+ * This hook provides access to step-specific configuration that is injected
+ * into the HTML by the CRM when the page is served. This includes:
+ * - Payment flow overrides
+ * - Static resources (offer, product IDs for A/B variants)
+ * - Custom scripts
+ * - Pixel tracking configuration
+ *
+ * Usage:
+ * ```tsx
+ * const { stepConfig, paymentFlowId, staticResources } = useStepConfig();
+ *
+ * // Access payment flow override
+ * if (paymentFlowId) {
+ *   console.log('Using custom payment flow:', paymentFlowId);
+ * }
+ *
+ * // Access static resources (e.g., offer ID for current A/B variant)
+ * const offerId = staticResources?.offer;
+ * ```
+ */
+import { GTMTrackingConfig, MetaConversionTrackingConfig, PixelTrackingConfig, RuntimeStepConfig, SnapchatTrackingConfig, TrackingProvider } from '../../core/funnelClient';
+export interface UseStepConfigResult {
+    /**
+     * Full step configuration object
+     * Contains payment, staticResources, scripts, and pixels
+     */
+    stepConfig: RuntimeStepConfig | undefined;
+    /**
+     * Payment flow ID override for this step
+     * If set, this payment flow should be used instead of the store default
+     */
+    paymentFlowId: string | undefined;
+    /**
+     * Static resources assigned to this step/variant
+     * For A/B tests, this contains the resources for the specific variant the user landed on
+     * e.g., { offer: 'offer_xxx', product: 'product_xxx' }
+     */
+    staticResources: Record<string, string> | undefined;
+    /**
+     * Get scripts for a specific injection position
+     * Only returns enabled scripts
+     * @param position - Where the scripts should be injected
+     */
+    getScripts: (position?: 'head-start' | 'head-end' | 'body-start' | 'body-end') => RuntimeStepConfig['scripts'];
+    pixels: {
+        [TrackingProvider.FACEBOOK]?: PixelTrackingConfig[];
+        [TrackingProvider.TIKTOK]?: PixelTrackingConfig[];
+        [TrackingProvider.SNAPCHAT]?: SnapchatTrackingConfig[];
+        [TrackingProvider.META_CONVERSION]?: MetaConversionTrackingConfig[];
+        [TrackingProvider.GTM]?: GTMTrackingConfig[];
+    } | undefined;
+}
+/**
+ * Hook to access runtime step configuration injected via HTML
+ *
+ * The step config is read from window.__TGD_STEP_CONFIG__ or the x-step-config meta tag.
+ * Values are memoized and only re-computed on mount.
+ *
+ * @returns Step configuration values and helpers
+ */
+export declare function useStepConfig(): UseStepConfigResult;

package/dist/v2/react/hooks/useStepConfig.js

@@ -0,0 +1,53 @@
+/**
+ * useStepConfig Hook - Access runtime step configuration from HTML injection
+ *
+ * This hook provides access to step-specific configuration that is injected
+ * into the HTML by the CRM when the page is served. This includes:
+ * - Payment flow overrides
+ * - Static resources (offer, product IDs for A/B variants)
+ * - Custom scripts
+ * - Pixel tracking configuration
+ *
+ * Usage:
+ * ```tsx
+ * const { stepConfig, paymentFlowId, staticResources } = useStepConfig();
+ *
+ * // Access payment flow override
+ * if (paymentFlowId) {
+ *   console.log('Using custom payment flow:', paymentFlowId);
+ * }
+ *
+ * // Access static resources (e.g., offer ID for current A/B variant)
+ * const offerId = staticResources?.offer;
+ * ```
+ */
+import { useMemo } from 'react';
+import { getAssignedPaymentFlowId, getAssignedPixels, getAssignedScripts, getAssignedStaticResources, getAssignedStepConfig, TrackingProvider } from '../../core/funnelClient';
+/**
+ * Hook to access runtime step configuration injected via HTML
+ *
+ * The step config is read from window.__TGD_STEP_CONFIG__ or the x-step-config meta tag.
+ * Values are memoized and only re-computed on mount.
+ *
+ * @returns Step configuration values and helpers
+ */
+export function useStepConfig() {
+    // Read once on mount - these values don't change during the page lifecycle
+    const stepConfig = useMemo(() => getAssignedStepConfig(), []);
+    const paymentFlowId = useMemo(() => getAssignedPaymentFlowId(), []);
+    const staticResources = useMemo(() => getAssignedStaticResources(), []);
+    const pixels = useMemo(() => getAssignedPixels(), []);
+    // Create a stable reference for getScripts
+    const getScripts = useMemo(() => {
+        return (position) => {
+            return getAssignedScripts(position);
+        };
+    }, []);
+    return {
+        stepConfig,
+        paymentFlowId,
+        staticResources,
+        getScripts,
+        pixels
+    };
+}