@datlv-trustshop/shopify-inapp-components 0.1.24 → 0.1.26

package/dist/components/FloatingCard.d.ts

@@ -30,9 +30,11 @@ export interface FloatingCardData {
     auto_close_after?: number | null;
     reappear_interval?: number | null;
     display_pages?: string[];
+    campaign_id?: string | number;
 }
 interface FloatingCardProps {
     data: FloatingCardData;
+    shopId?: string;
     onDismiss?: () => void;
     onPrimaryAction?: (data: FloatingCardData) => void;
     onSecondaryAction?: (data: FloatingCardData) => void;

package/dist/components/FloatingCard.js

@@ -2,8 +2,29 @@ import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import React from "react";
 import { Card, BlockStack, InlineStack, Text, Badge, Button, Box, } from "@shopify/polaris";
 import { XIcon } from "@shopify/polaris-icons";
-export const FloatingCard = ({ data, onDismiss, onPrimaryAction, onSecondaryAction, position = 'bottom-right', showCloseButton = true, }) => {
+import { useCampaignTracking } from "../hooks/useCampaignTracking";
+import { DashboardContext } from "../provider/DashboardProvider";
+export const FloatingCard = ({ data, shopId: propsShopId, onDismiss, onPrimaryAction, onSecondaryAction, position = 'bottom-right', showCloseButton = true, }) => {
+    // Get shopId from context if not provided via props
+    const dashboardContext = React.useContext(DashboardContext);
+    const contextShopId = dashboardContext?.engine?.config?.shopId;
+    const shopId = propsShopId || contextShopId;
+    // Use the campaign ID from data or fallback to regular id
+    const campaignId = data.campaign_id || data.id;
+    // Set up campaign tracking
+    const tracking = shopId && campaignId ? useCampaignTracking({
+        shopId,
+        campaignId,
+        threshold: 0.5, // Track when 50% visible
+        visibilityDuration: 1000, // Track view after 1 second
+        metadata: {
+            card_type: data.type,
+            card_key: data.key,
+        },
+    }) : null;
     const handlePrimaryAction = () => {
+        // Track the click
+        tracking?.trackPrimaryAction();
         if (data.primary_action) {
             const url = data.primary_action.url;
             // Check if it's an external URL
@@ -27,6 +48,8 @@ export const FloatingCard = ({ data, onDismiss, onPrimaryAction, onSecondaryActi
         }
     };
     const handleSecondaryAction = () => {
+        // Track the click
+        tracking?.trackSecondaryAction();
         if (data.secondary_action) {
             const url = data.secondary_action.url;
             if (data.secondary_action.external) {
@@ -41,6 +64,11 @@ export const FloatingCard = ({ data, onDismiss, onPrimaryAction, onSecondaryActi
             }
         }
     };
+    const handleDismiss = () => {
+        // Track the dismiss
+        tracking?.trackDismiss();
+        onDismiss?.();
+    };
     // CSS-in-JS styles - no external CSS file needed
     const floatingCardStyles = {
         position: 'fixed',
@@ -111,11 +139,11 @@ export const FloatingCard = ({ data, onDismiss, onPrimaryAction, onSecondaryActi
             document.head.appendChild(style);
         }
     }, []);
-    return (_jsx("div", { style: floatingCardStyles, children: _jsxs(Card, { padding: "0", roundedAbove: "sm", children: [(showCloseButton && data.dismissible !== false) && (_jsx("button", { style: closeButtonStyles, onMouseEnter: (e) => {
+    return (_jsx("div", { ref: tracking?.elementRef, style: floatingCardStyles, children: _jsxs(Card, { padding: "0", roundedAbove: "sm", children: [(showCloseButton && data.dismissible !== false) && (_jsx("button", { style: closeButtonStyles, onMouseEnter: (e) => {
                         e.currentTarget.style.background = 'rgba(255, 255, 255, 0.30)';
                     }, onMouseLeave: (e) => {
                         e.currentTarget.style.background = 'rgba(255, 255, 255, 0.20)';
-                    }, onClick: onDismiss, "aria-label": "Close", children: _jsx(XIcon, { style: { width: '20px', height: '20px', color: 'rgba(255, 255, 255, 0.9)' } }) })), _jsxs(BlockStack, { gap: "0", children: [data.img_url && (_jsx("div", { style: imageContainerStyles, children: _jsx("img", { src: data.img_url, alt: data.image_alt || data.title, style: {
+                    }, onClick: handleDismiss, "aria-label": "Close", children: _jsx(XIcon, { style: { width: '20px', height: '20px', color: 'rgba(255, 255, 255, 0.9)' } }) })), _jsxs(BlockStack, { gap: "0", children: [data.img_url && (_jsx("div", { style: imageContainerStyles, children: _jsx("img", { src: data.img_url, alt: data.image_alt || data.title, style: {
                                     width: "100%",
                                     height: "100%",
                                     objectFit: "cover",

package/dist/core/engine.d.ts

@@ -2,7 +2,7 @@ import { DashboardData, DashboardConfig, BannerItem, AppItem, AppGroup, ArticleI
 export declare class DashboardEngine {
     private static instance;
     private data;
-    private config;
+    config: DashboardConfig;
     private initPromise;
     private lastFetchTime;
     private listeners;

package/dist/hooks/index.d.ts

@@ -6,3 +6,4 @@ export * from "./useWhatsNew";
 export * from "./useGrowApps";
 export * from "./usePartnerIntegration";
 export * from "./useFloatingCards";
+export * from "./useCampaignTracking";

package/dist/hooks/index.js

@@ -6,3 +6,4 @@ export * from "./useWhatsNew";
 export * from "./useGrowApps";
 export * from "./usePartnerIntegration";
 export * from "./useFloatingCards";
+export * from "./useCampaignTracking";

package/dist/hooks/useCampaignTracking.d.ts

@@ -0,0 +1,44 @@
+interface UseCampaignVisibilityOptions {
+    shopId: string;
+    campaignId: string | number;
+    threshold?: number;
+    visibilityDuration?: number;
+    metadata?: Record<string, any>;
+}
+/**
+ * Hook to track campaign visibility using IntersectionObserver
+ * Automatically tracks views when element is visible for specified duration
+ */
+export declare function useCampaignVisibility(options: UseCampaignVisibilityOptions): {
+    elementRef: import("react").RefObject<HTMLDivElement>;
+    isVisible: boolean;
+    hasTrackedView: boolean;
+    getTimeToAction: () => number | undefined;
+};
+interface UseCampaignTrackingOptions {
+    shopId: string;
+    campaignId: string | number;
+    threshold?: number;
+    visibilityDuration?: number;
+    metadata?: Record<string, any>;
+}
+/**
+ * Main hook for campaign tracking
+ * Combines visibility tracking with click tracking utilities
+ */
+export declare function useCampaignTracking(options: UseCampaignTrackingOptions): {
+    trackClick: (clickOptions?: {
+        actionType?: string;
+        ctaId?: string;
+        ctaKey?: string;
+        metadata?: Record<string, any>;
+    }) => void;
+    trackPrimaryAction: () => void;
+    trackSecondaryAction: () => void;
+    trackDismiss: () => void;
+    elementRef: import("react").RefObject<HTMLDivElement>;
+    isVisible: boolean;
+    hasTrackedView: boolean;
+    getTimeToAction: () => number | undefined;
+};
+export {};

package/dist/hooks/useCampaignTracking.js

@@ -0,0 +1,116 @@
+import { useEffect, useRef, useCallback, useState } from 'react';
+import { trackCampaignView, trackCampaignClick } from '../utils/campaignTracking';
+/**
+ * Hook to track campaign visibility using IntersectionObserver
+ * Automatically tracks views when element is visible for specified duration
+ */
+export function useCampaignVisibility(options) {
+    const { shopId, campaignId, threshold = 0.5, // Default: 50% visible
+    visibilityDuration = 1000, // Default: 1 second
+    metadata = {}, } = options;
+    const elementRef = useRef(null);
+    const visibilityTimerRef = useRef(null);
+    const hasTrackedViewRef = useRef(false);
+    const [isVisible, setIsVisible] = useState(false);
+    const firstVisibleTimeRef = useRef(null);
+    useEffect(() => {
+        if (!elementRef.current || typeof window === 'undefined')
+            return;
+        const observer = new IntersectionObserver((entries) => {
+            entries.forEach((entry) => {
+                const nowVisible = entry.isIntersecting && entry.intersectionRatio >= threshold;
+                if (nowVisible && !hasTrackedViewRef.current) {
+                    // Element became visible
+                    setIsVisible(true);
+                    // Record first visible time if not already set
+                    if (!firstVisibleTimeRef.current) {
+                        firstVisibleTimeRef.current = Date.now();
+                    }
+                    // Start timer for view tracking
+                    if (visibilityTimerRef.current) {
+                        clearTimeout(visibilityTimerRef.current);
+                    }
+                    visibilityTimerRef.current = setTimeout(() => {
+                        // Track view after visibility duration
+                        if (!hasTrackedViewRef.current) {
+                            trackCampaignView(shopId, campaignId, metadata);
+                            hasTrackedViewRef.current = true;
+                        }
+                    }, visibilityDuration);
+                }
+                else if (!nowVisible) {
+                    // Element became hidden
+                    setIsVisible(false);
+                    // Clear timer if element becomes hidden before tracking
+                    if (visibilityTimerRef.current && !hasTrackedViewRef.current) {
+                        clearTimeout(visibilityTimerRef.current);
+                        visibilityTimerRef.current = null;
+                    }
+                }
+            });
+        }, {
+            threshold: [0, threshold], // Watch for both becoming visible and hidden
+            rootMargin: '0px',
+        });
+        observer.observe(elementRef.current);
+        return () => {
+            // Cleanup
+            if (visibilityTimerRef.current) {
+                clearTimeout(visibilityTimerRef.current);
+            }
+            observer.disconnect();
+        };
+    }, [shopId, campaignId, threshold, visibilityDuration, metadata]);
+    // Calculate time to action for clicks
+    const getTimeToAction = useCallback(() => {
+        if (firstVisibleTimeRef.current) {
+            return Date.now() - firstVisibleTimeRef.current;
+        }
+        return undefined;
+    }, []);
+    return {
+        elementRef,
+        isVisible,
+        hasTrackedView: hasTrackedViewRef.current,
+        getTimeToAction,
+    };
+}
+/**
+ * Main hook for campaign tracking
+ * Combines visibility tracking with click tracking utilities
+ */
+export function useCampaignTracking(options) {
+    const { shopId, campaignId, ...visibilityOptions } = options;
+    const visibility = useCampaignVisibility({
+        shopId,
+        campaignId,
+        ...visibilityOptions,
+    });
+    const trackClick = useCallback((clickOptions) => {
+        const timeToAction = visibility.getTimeToAction();
+        trackCampaignClick(shopId, campaignId, {
+            ...clickOptions,
+            timeToAction,
+            metadata: {
+                ...options.metadata,
+                ...clickOptions?.metadata,
+            },
+        });
+    }, [shopId, campaignId, visibility, options.metadata]);
+    const trackPrimaryAction = useCallback(() => {
+        trackClick({ actionType: 'primary' });
+    }, [trackClick]);
+    const trackSecondaryAction = useCallback(() => {
+        trackClick({ actionType: 'secondary' });
+    }, [trackClick]);
+    const trackDismiss = useCallback(() => {
+        trackClick({ actionType: 'dismiss' });
+    }, [trackClick]);
+    return {
+        ...visibility,
+        trackClick,
+        trackPrimaryAction,
+        trackSecondaryAction,
+        trackDismiss,
+    };
+}

package/dist/hooks/useFloatingCards.js

@@ -9,7 +9,7 @@ export function useFloatingCards(options = {}) {
     const dashboardContext = useDashboardContext();
     const contextLocale = dashboardContext?.locale;
     // Use props locale if provided, otherwise use context locale, fallback to 'en'
-    const locale = propsLocale || contextLocale || 'en';
+    const locale = propsLocale || contextLocale || "en";
     const [cards, setCards] = useState([]);
     const [loading, setLoading] = useState(false);
     const [error, setError] = useState(null);
@@ -23,7 +23,6 @@ export function useFloatingCards(options = {}) {
         setError(null);
         try {
             const id = shopId;
-            // Use proxy in development
             const apiUrl = typeof window !== "undefined" &&
                 window.location.hostname === "localhost"
                 ? `/api/campaigns?shop_id=${id}&locale=${locale}`
@@ -41,7 +40,6 @@ export function useFloatingCards(options = {}) {
             }
             const data = await response.json();
             if (data.success && Array.isArray(data.data)) {
-                // Transform the API response to match our FloatingCardData interface
                 const transformedCards = data.data.map((card) => ({
                     ...card,
                     // Ensure date format
@@ -138,19 +136,36 @@ export function useVisibleFloatingCards(options = {}) {
             return false;
         }
         // Check display_pages logic
-        if (card.display_pages !== undefined) {
+        if (card.display_pages !== undefined && card.display_pages !== null) {
             // If display_pages is empty array, show on all pages
             if (card.display_pages.length === 0) {
                 return true;
             }
             // If display_pages has values, check if current route matches
-            if (currentRoute) {
-                // Extract the page key from the route (e.g., "/settings" -> "settings")
-                const currentPage = currentRoute.replace(/^\//, '').split('/')[0];
+            if (currentRoute !== undefined) {
+                // Extract the page key from the route
+                // Special handling: "/" or "" should map to "dashboard"
+                let currentPage = currentRoute.replace(/^\//, "").split("/")[0];
+                // Map root route to dashboard (in-app convention)
+                if (!currentPage || currentPage === "" || currentRoute === "/") {
+                    currentPage = "dashboard";
+                }
+                // Debug log for development
+                if (typeof window !== "undefined" &&
+                    window.location.hostname === "localhost") {
+                    console.log("[FloatingCard] Route matching:", {
+                        cardId: card.id,
+                        currentRoute,
+                        currentPage,
+                        display_pages: card.display_pages,
+                        matches: card.display_pages.includes(currentPage),
+                    });
+                }
+                // Check if current page is in display_pages
                 return card.display_pages.includes(currentPage);
             }
-            // If no current route provided, don't show the card
-            return false;
+            // If no current route provided, assume dashboard
+            return card.display_pages.includes("dashboard");
         }
         // If display_pages is not defined, show on all pages (backward compatibility)
         return true;

package/dist/index.d.ts

@@ -10,6 +10,9 @@ export * from "./components";
 export type { SDKTranslations } from './types/translations';
 export { defaultTranslations } from './translations/default';
 export { useTranslations, useTranslation } from './hooks/useTranslations';
+export { trackCampaignView, trackCampaignClick, clearViewTrackingCache } from './utils/campaignTracking';
+export { getSessionId, clearSession, hasSession } from './utils/sessionManager';
+export { useCampaignTracking, useCampaignVisibility } from './hooks/useCampaignTracking';
 import { DashboardEngine } from "./core/engine";
 declare const _default: {
     DashboardEngine: typeof DashboardEngine;

package/dist/index.js

@@ -8,6 +8,10 @@ export * from "./hooks";
 export * from "./components";
 export { defaultTranslations } from './translations/default';
 export { useTranslations, useTranslation } from './hooks/useTranslations';
+// Campaign Tracking
+export { trackCampaignView, trackCampaignClick, clearViewTrackingCache } from './utils/campaignTracking';
+export { getSessionId, clearSession, hasSession } from './utils/sessionManager';
+export { useCampaignTracking, useCampaignVisibility } from './hooks/useCampaignTracking';
 import { DashboardEngine } from "./core/engine";
 import { DashboardProvider } from "./provider/DashboardProvider";
 export default {

package/dist/types/dashboard.d.ts

@@ -29,6 +29,7 @@ export interface DashboardData {
 }
 export interface DashboardConfig {
     apiUrl: string;
+    shopId?: string;
     locale?: string;
     cacheTime?: number;
     retryAttempts?: number;

package/dist/utils/campaignTracking.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Track campaign view
+ * Handles deduplication and fire-and-forget requests
+ */
+export declare function trackCampaignView(shopId: string, campaignId: string | number, metadata?: Record<string, any>): Promise<void>;
+/**
+ * Track campaign click
+ * Tracks immediately without debouncing
+ */
+export declare function trackCampaignClick(shopId: string, campaignId: string | number, options?: {
+    actionType?: string;
+    ctaId?: string;
+    ctaKey?: string;
+    timeToAction?: number;
+    metadata?: Record<string, any>;
+}): Promise<void>;
+/**
+ * Clear view tracking deduplication cache
+ * Useful for testing or when session changes
+ */
+export declare function clearViewTrackingCache(): void;

package/dist/utils/campaignTracking.js

@@ -0,0 +1,130 @@
+import { getSessionId } from './sessionManager';
+const TRACKING_BASE_URL = 'https://ops.trustshop.io';
+/**
+ * View tracking deduplication map
+ * Key: ${sessionId}-${campaignId}
+ * Value: timestamp in milliseconds
+ */
+const viewTrackingMap = new Map();
+/**
+ * Deduplication threshold for view tracking (5 seconds)
+ */
+const VIEW_DEDUP_THRESHOLD_MS = 5000;
+/**
+ * Get current page context from URL
+ */
+function getPageContext() {
+    if (typeof window === 'undefined') {
+        return '/';
+    }
+    // Get the current pathname
+    const pathname = window.location.pathname;
+    // In Shopify admin apps, the actual route might be in hash
+    const hash = window.location.hash;
+    if (hash && hash.startsWith('#/')) {
+        return hash.substring(1); // Remove the '#'
+    }
+    return pathname;
+}
+/**
+ * Track campaign view
+ * Handles deduplication and fire-and-forget requests
+ */
+export async function trackCampaignView(shopId, campaignId, metadata) {
+    const sessionId = getSessionId();
+    const dedupKey = `${sessionId}-${campaignId}`;
+    const now = Date.now();
+    // Check for deduplication
+    const lastTracked = viewTrackingMap.get(dedupKey);
+    if (lastTracked && (now - lastTracked) < VIEW_DEDUP_THRESHOLD_MS) {
+        // Skip tracking - still within dedup threshold
+        console.log(`⏭️ [Campaign Tracking] View skipped (dedup) for campaign ${campaignId} - last tracked ${now - lastTracked}ms ago`);
+        return;
+    }
+    // Update tracking map
+    viewTrackingMap.set(dedupKey, now);
+    const payload = {
+        session_id: sessionId,
+        page_context: getPageContext(),
+        metadata: {
+            source: 'in-app-sdk',
+            placement: 'floating-card',
+            ...metadata,
+        },
+    };
+    const url = `${TRACKING_BASE_URL}/api/shops/${shopId}/campaigns/${campaignId}/track/view`;
+    // Log tracking attempt in development
+    console.log(`👁️ [Campaign Tracking] VIEW tracked for campaign ${campaignId}`);
+    console.log(`📍 URL: ${url}`);
+    console.log(`📦 Payload:`, payload);
+    // Fire and forget - no await, no error handling that would break UI
+    void fetch(url, {
+        method: 'POST',
+        headers: {
+            'Content-Type': 'application/json',
+            'Accept': 'application/json',
+        },
+        body: JSON.stringify(payload),
+        credentials: 'include',
+    }).catch(error => {
+        // Log error in development
+        console.error('[Campaign Tracking] View tracking failed:', error);
+    });
+}
+/**
+ * Track campaign click
+ * Tracks immediately without debouncing
+ */
+export async function trackCampaignClick(shopId, campaignId, options = {}) {
+    const { actionType, ctaId, ctaKey, timeToAction, metadata } = options;
+    // Validate that at least one required field is present
+    if (!actionType && !ctaId && !ctaKey) {
+        console.warn('[Campaign Tracking] Click tracking requires at least one of: action_type, cta_id, cta_key');
+        return;
+    }
+    const sessionId = getSessionId();
+    const payload = {
+        session_id: sessionId,
+        page_context: getPageContext(),
+        metadata: {
+            source: 'in-app-sdk',
+            placement: 'floating-card',
+            ...metadata,
+        },
+    };
+    // Add optional fields if provided
+    if (actionType)
+        payload.action_type = actionType;
+    if (ctaId)
+        payload.cta_id = ctaId;
+    if (ctaKey)
+        payload.cta_key = ctaKey;
+    if (timeToAction !== undefined)
+        payload.time_to_action = timeToAction;
+    const url = `${TRACKING_BASE_URL}/api/shops/${shopId}/campaigns/${campaignId}/track/click`;
+    // Log tracking attempt in development
+    console.log(`🖱️ [Campaign Tracking] CLICK tracked for campaign ${campaignId}`);
+    console.log(`📍 URL: ${url}`);
+    console.log(`📦 Payload:`, payload);
+    console.log(`⏱️ Time to action: ${timeToAction}ms`);
+    // Fire and forget - no await, no error handling that would break UI
+    void fetch(url, {
+        method: 'POST',
+        headers: {
+            'Content-Type': 'application/json',
+            'Accept': 'application/json',
+        },
+        body: JSON.stringify(payload),
+        credentials: 'include',
+    }).catch(error => {
+        // Log error in development
+        console.error('[Campaign Tracking] Click tracking failed:', error);
+    });
+}
+/**
+ * Clear view tracking deduplication cache
+ * Useful for testing or when session changes
+ */
+export function clearViewTrackingCache() {
+    viewTrackingMap.clear();
+}

package/dist/utils/sessionManager.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Session management utility for campaign tracking
+ */
+/**
+ * Get or create session ID
+ * Session persists for the browser session (using sessionStorage)
+ */
+export declare function getSessionId(): string;
+/**
+ * Clear current session
+ */
+export declare function clearSession(): void;
+/**
+ * Check if a session exists
+ */
+export declare function hasSession(): boolean;

package/dist/utils/sessionManager.js

@@ -0,0 +1,62 @@
+/**
+ * Session management utility for campaign tracking
+ */
+const SESSION_ID_KEY = 'trustshop_inapp_session_id';
+/**
+ * Generate a unique session ID
+ */
+function generateSessionId() {
+    const timestamp = Date.now();
+    const random = Math.random().toString(36).substring(2, 15);
+    return `sess_${timestamp}_${random}`;
+}
+/**
+ * Get or create session ID
+ * Session persists for the browser session (using sessionStorage)
+ */
+export function getSessionId() {
+    if (typeof window === 'undefined') {
+        return generateSessionId();
+    }
+    try {
+        // Check if session ID exists in sessionStorage
+        let sessionId = sessionStorage.getItem(SESSION_ID_KEY);
+        if (!sessionId) {
+            // Generate new session ID
+            sessionId = generateSessionId();
+            sessionStorage.setItem(SESSION_ID_KEY, sessionId);
+        }
+        return sessionId;
+    }
+    catch (error) {
+        // Fallback if sessionStorage is not available
+        console.warn('SessionStorage not available, using temporary session ID', error);
+        return generateSessionId();
+    }
+}
+/**
+ * Clear current session
+ */
+export function clearSession() {
+    if (typeof window === 'undefined')
+        return;
+    try {
+        sessionStorage.removeItem(SESSION_ID_KEY);
+    }
+    catch (error) {
+        console.warn('Failed to clear session', error);
+    }
+}
+/**
+ * Check if a session exists
+ */
+export function hasSession() {
+    if (typeof window === 'undefined')
+        return false;
+    try {
+        return sessionStorage.getItem(SESSION_ID_KEY) !== null;
+    }
+    catch {
+        return false;
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@datlv-trustshop/shopify-inapp-components",
-  "version": "0.1.24",
+  "version": "0.1.26",
   "private": false,
   "description": "React TypeScript components for Shopify in-app dashboard content",
   "main": "dist/index.js",