# Gunma Behavioral Tracking SDK for Next.js Professional-grade behavioral tracking for Next.js E-commerce and POS applications. ## Installation ### From npm (if published) ```bash npm install @gunma/behavioral-tracking-nextjs ``` ### From local SDK folder ```bash # Copy the SDK folder to your project cp -r public/sdk/nextjs path/to/your/nextjs-project/sdk # Install dependencies cd path/to/your/nextjs-project/sdk/nextjs npm install # Build the SDK npm run build ``` ### Use directly in your project ```bash # In your Next.js project npm install axios js-cookie ua-parser-js ``` Then copy the source files from `src/` to your project. ## Quick Start ### 1. Add TrackingProvider to your root layout ```tsx // app/layout.tsx import { TrackingProvider } from '@/sdk/nextjs/src/context'; import { ConsentBanner } from '@/sdk/nextjs/src/components/ConsentBanner'; export default function RootLayout({ children }: { children: React.ReactNode }) { return ( {children} ); } ``` ### 2. Configure environment variables ```env # .env.local NEXT_PUBLIC_API_URL=http://localhost:8000 NEXT_PUBLIC_TRACKING_ENABLED=true NEXT_PUBLIC_TRACKING_CONSENT_REQUIRED=true ``` ### 3. Use the tracking hook ```tsx 'use client'; import { useBehavioralTracking } from '@/sdk/nextjs/src/hooks/useBehavioralTracking'; export function ProductCard({ product }) { const { trackProductView, trackAddToCart } = useBehavioralTracking(); return (

trackProductView(product.id, product.price)}>

{product.name}

${product.price}

); } ``` ## API Reference ### `useBehavioralTracking()` Main tracking hook with all tracking methods. ```tsx const { trackEvent, trackProductView, trackAddToCart, trackRemoveFromCart, trackSearch, trackOrderPlaced, trackCheckoutInitiated, trackAddToWishlist, trackRemoveFromWishlist, } = useBehavioralTracking(); ``` **Methods:** - `trackProductView(productId: number, price?: number)` - Track product page views - `trackAddToCart(productId: number, quantity: number, price: number)` - Track add to cart - `trackRemoveFromCart(productId: number)` - Track remove from cart - `trackSearch(query: string, resultsCount: number)` - Track search queries - `trackOrderPlaced(orderId: number)` - Track completed orders - `trackCheckoutInitiated()` - Track checkout start - `trackAddToWishlist(productId: number)` - Track wishlist additions - `trackRemoveFromWishlist(productId: number)` - Track wishlist removals - `trackEvent(eventType: string, data?: Partial)` - Track custom events ### `useTracking()` Consent management hook. ```tsx const { hasConsent, grantConsent, revokeConsent, isLoading } = useTracking(); ``` ### `useAnalytics()` Analytics data fetching hook. ```tsx const { getDashboard, getProductAffinity, getConversionFunnel } = useAnalytics(); ``` ## Features ✅ **Auto-tracking** - Automatically tracks scroll depth, time spent, page views ✅ **GDPR Compliant** - Built-in consent management ✅ **TypeScript** - Full type safety ✅ **Queue-based** - No performance impact ✅ **Product Recommendations** - Get product affinity data ✅ **Analytics Dashboard** - Complete analytics API client ✅ **Device Detection** - Auto-detects device, browser, platform ✅ **UTM Tracking** - Automatically captures campaign parameters ## Auto-Tracked Events The SDK automatically tracks: - **Page Views** - On component mount - **Scroll Depth** - At 25%, 50%, 75%, 100% - **Time Spent** - On page unload (using sendBeacon) - **Interactions** - Click counts ## Manual Tracking Examples ### E-commerce ```tsx // Product page useEffect(() => { trackProductView(product.id, product.price); }, [product.id]); // Add to cart button // Search page const handleSearch = async (query: string) => { const results = await searchProducts(query); trackSearch(query, results.length); }; // Checkout page useEffect(() => { trackCheckoutInitiated(); }, []); // Order confirmation useEffect(() => { if (order) { trackOrderPlaced(order.id); } }, [order]); ``` ### POS System ```tsx // Barcode scanner const handleScan = async (barcode: string) => { const product = await fetchProduct(barcode); await trackProductView(product.id, product.price); await trackAddToCart(product.id, 1, product.price); addToCart(product); }; ``` ## Analytics Examples ```tsx import { useAnalytics } from '@/sdk/nextjs/src/hooks/useAnalytics'; function DashboardPage() { const { getDashboard } = useAnalytics(); const [data, setData] = useState(null); useEffect(() => { getDashboard({ start_date: '2025-01-01', end_date: '2025-12-31' }) .then(response => setData(response.data)); }, []); return (

Total Events: {data?.total_events}

Cart Abandonment: {data?.cart_abandonment?.abandonment_rate}%

); } ``` ## Advanced Configuration ```tsx import { behavioralTracker } from '@/sdk/nextjs/src/tracker'; // Custom configuration behavioralTracker.setConfig({ enabled: true, consentRequired: false, // Disable consent requirement debugMode: true, // Enable debug logging }); // Check consent if (behavioralTracker.hasConsent()) { // Track event } // Grant consent programmatically behavioralTracker.grantConsent(); // Revoke consent behavioralTracker.revokeConsent(); ``` ## Troubleshooting **Events not tracking:** 1. Check queue worker is running: `php artisan queue:work redis` 2. Check browser console for errors 3. Verify API URL in .env.local 4. Check user has granted consent **CORS errors:** - Add your Next.js URL to backend config/cors.php - Restart Laravel server ## Support For issues, see the complete integration guide in: - `FRONTEND_INTEGRATION_GUIDE.md` - `FRONTEND_QUICK_START.md` ## License MIT