gunma-behavioral-tracking-nextjs

v1.0.0

Published

7 months ago

Behavioral tracking SDK for Next.js E-commerce and POS applications

0High
0Medium
0Low

ringkubd

behavioral tracking analytics next.js e-commerce

Gunma Behavioral Tracking SDK for Next.js

Professional-grade behavioral tracking for Next.js E-commerce and POS applications.

Installation

From npm (if published)

npm install @gunma/behavioral-tracking-nextjs

From local SDK folder

# 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

# 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

// 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 (
    <html>
      <body>
        <TrackingProvider>
          {children}
          <ConsentBanner />
        </TrackingProvider>
      </body>
    </html>
  );
}

2. Configure environment variables

# .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

'use client';

import { useBehavioralTracking } from '@/sdk/nextjs/src/hooks/useBehavioralTracking';

export function ProductCard({ product }) {
  const { trackProductView, trackAddToCart } = useBehavioralTracking();
  
  return (
    <div onClick={() => trackProductView(product.id, product.price)}>
      <h3>{product.name}</h3>
      <p>${product.price}</p>
      <button onClick={() => trackAddToCart(product.id, 1, product.price)}>
        Add to Cart
      </button>
    </div>
  );
}

API Reference

`useBehavioralTracking()`

Main tracking hook with all tracking methods.

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<BehavioralEvent>) - Track custom events

`useTracking()`

Consent management hook.

const { hasConsent, grantConsent, revokeConsent, isLoading } = useTracking();

`useAnalytics()`

Analytics data fetching hook.

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

// Product page
useEffect(() => {
  trackProductView(product.id, product.price);
}, [product.id]);

// Add to cart button
<button onClick={() => trackAddToCart(product.id, 1, product.price)}>
  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

// 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

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 (
    <div>
      <h1>Total Events: {data?.total_events}</h1>
      <h2>Cart Abandonment: {data?.cart_abandonment?.abandonment_rate}%</h2>
    </div>
  );
}

Advanced Configuration

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:

Check queue worker is running: php artisan queue:work redis
Check browser console for errors
Verify API URL in .env.local
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