@od-oneapp/analytics 2026.1.1301

package/src/next/app-router.tsx

@@ -0,0 +1,564 @@
+/**
+ * @fileoverview Next.js App Router specific analytics helpers
+ *
+ * This module provides React hooks and components optimized for Next.js App Router:
+ *
+ * - **Hooks**: `useAnalytics()`, `usePageTracking()`, `useTrackEvent()`, `useIdentifyUser()`
+ * - **Components**: `AnalyticsProvider`, `TrackedButton`, `TrackedLink`, `withViewTracking()`
+ * - **Ecommerce Tracking**: `useEcommerceTracking()` hook
+ * - **Form Tracking**: `useFormTracking()` hook
+ *
+ * **NOTE**: This file is Next.js-specific. Client components can use Next.js hooks
+ * as they're already framework-bound.
+ *
+ * @module @od-oneapp/analytics/next/app-router
+ */
+
+'use client';
+
+// Note: These are Next.js hooks required for App Router integration
+// Client components are already Next.js-specific, so this is acceptable
+import { useCallback, useEffect, useRef, useState } from 'react';
+
+import type { Route } from 'next';
+
+import { useParams, usePathname, useRouter, useSearchParams } from 'next/navigation';
+
+import { createNextJSClientAnalytics } from './client';
+
+import type { NextJSClientAnalyticsConfig, NextJSClientAnalyticsManager } from './client';
+import type { BootstrapData } from '../shared/types/posthog-types';
+import type { AnalyticsConfig, TrackingOptions } from '../shared/types/types';
+
+// Global analytics instance
+let globalAnalytics: NextJSClientAnalyticsManager | null = null;
+
+/**
+ * Hook to get or create analytics instance.
+ *
+ * Returns the global analytics instance, creating it if it doesn't exist.
+ * The instance is shared across all components using this hook.
+ *
+ * @param {AnalyticsConfig} [config] - Analytics configuration (only used on first call)
+ * @returns {NextJSClientAnalyticsManager | null} Analytics manager instance or null if not initialized
+ *
+ * @example
+ * ```typescript
+ * function MyComponent() {
+ *   const analytics = useAnalytics(config);
+ *   if (!analytics) return null;
+ *
+ *   const handleClick = () => {
+ *     analytics.track('Button Clicked');
+ *   };
+ * }
+ * ```
+ */
+export function useAnalytics(config?: AnalyticsConfig): NextJSClientAnalyticsManager | null {
+  const [analytics, setAnalytics] = useState<NextJSClientAnalyticsManager | null>(null);
+
+  useEffect(() => {
+    if (!globalAnalytics && config) {
+      // Convert AnalyticsConfig to NextJSClientAnalyticsConfig
+      // Preserve all bootstrap properties (distinctID is required for BootstrapData)
+      const nextjsConfig = {
+        ...config,
+        nextjs: config.nextjs
+          ? ({
+              ...config.nextjs,
+              posthog: config.nextjs.posthog
+                ? {
+                    ...config.nextjs.posthog,
+                    bootstrap:
+                      config.nextjs.posthog.bootstrap?.distinctID !== undefined
+                        ? ({
+                            distinctID: config.nextjs.posthog.bootstrap.distinctID,
+                            // Preserve other bootstrap properties for PostHog functionality
+                            ...(config.nextjs.posthog.bootstrap.isIdentifiedID !== undefined && {
+                              isIdentifiedID: config.nextjs.posthog.bootstrap.isIdentifiedID,
+                            }),
+                            ...(config.nextjs.posthog.bootstrap.featureFlags && {
+                              featureFlags: config.nextjs.posthog.bootstrap.featureFlags,
+                            }),
+                            ...(config.nextjs.posthog.bootstrap.featureFlagPayloads && {
+                              featureFlagPayloads:
+                                config.nextjs.posthog.bootstrap.featureFlagPayloads,
+                            }),
+                          } as BootstrapData)
+                        : undefined,
+                  }
+                : undefined,
+            } as NextJSClientAnalyticsConfig['nextjs'])
+          : undefined,
+      } as NextJSClientAnalyticsConfig;
+      globalAnalytics = createNextJSClientAnalytics(nextjsConfig);
+      void globalAnalytics.initialize();
+      // Use setTimeout to avoid synchronous setState in effect
+      setTimeout(() => {
+        setAnalytics(globalAnalytics);
+      }, 0);
+    } else if (globalAnalytics) {
+      // Use setTimeout to avoid synchronous setState in effect
+      setTimeout(() => {
+        setAnalytics(globalAnalytics);
+      }, 0);
+    }
+  }, [config]);
+
+  return analytics;
+}
+
+/**
+ * Hook for automatic page view tracking in App Router.
+ *
+ * Automatically tracks page views when the pathname, search params, or route params change.
+ * Uses Next.js `usePathname()`, `useSearchParams()`, and `useParams()` hooks.
+ *
+ * @param {object} [options] - Page tracking options
+ * @param {boolean} [options.trackSearch] - Whether to track search params changes (default: false)
+ * @param {boolean} [options.trackParams] - Whether to track route params changes (default: false)
+ * @param {Record<string, any>} [options.properties] - Additional properties to include with page views
+ * @param {boolean} [options.skip] - Skip tracking (useful for conditional tracking)
+ *
+ * @example
+ * ```typescript
+ * function Page() {
+ *   usePageTracking({
+ *     trackSearch: true,
+ *     properties: { section: 'products' }
+ *   });
+ *   return <div>Page content</div>;
+ * }
+ * ```
+ */
+export function usePageTracking(options?: {
+  trackSearch?: boolean;
+  trackParams?: boolean;
+  properties?: Record<string, any>;
+  skip?: boolean;
+}) {
+  const pathname = usePathname();
+  const searchParams = useSearchParams();
+  const params = useParams();
+  const tracked = useRef<string>('');
+
+  useEffect(() => {
+    if (options?.skip || !globalAnalytics) return;
+
+    // Create unique key for this page view
+    const searchString = options?.trackSearch ? searchParams.toString() : '';
+    const pageKey = `${pathname}${searchString}`;
+
+    // Avoid duplicate tracking
+    if (tracked.current === pageKey) return;
+    tracked.current = pageKey;
+
+    // Build properties
+    const properties: Record<string, any> = {
+      ...options?.properties,
+      url: window.location.href,
+      path: pathname,
+      referrer: document.referrer,
+      title: document.title,
+    };
+
+    if (options?.trackSearch) {
+      properties.search = searchString;
+      properties.search_params = Object.fromEntries(searchParams.entries());
+    }
+
+    if (options?.trackParams && params) {
+      properties.route_params = params;
+    }
+
+    // Track page view
+    void globalAnalytics.page(pathname, properties);
+  }, [
+    pathname,
+    searchParams,
+    params,
+    options?.skip,
+    options?.trackSearch,
+    options?.trackParams,
+    options?.properties,
+  ]);
+}
+
+/**
+ * Hook for tracking events
+ */
+export function useTrackEvent() {
+  return useCallback((event: string, properties?: any, options?: TrackingOptions) => {
+    if (!globalAnalytics) return;
+    void globalAnalytics.track(event, properties, options);
+  }, []);
+}
+
+/**
+ * Hook for user identification
+ */
+export function useIdentifyUser() {
+  return useCallback((userId: string, traits?: any, options?: TrackingOptions) => {
+    if (!globalAnalytics) return;
+    void globalAnalytics.identify(userId, traits, options);
+  }, []);
+}
+
+/**
+ * Hook for analytics consent management
+ */
+export function useAnalyticsConsent() {
+  const [consentGiven, setConsentGiven] = useState(false);
+  const [isLoading, setIsLoading] = useState(false);
+
+  const grantConsent = useCallback(async () => {
+    if (!globalAnalytics) return;
+
+    setIsLoading(true);
+    try {
+      await globalAnalytics.grantConsent();
+      setConsentGiven(true);
+    } finally {
+      setIsLoading(false);
+    }
+  }, []);
+
+  const revokeConsent = useCallback(() => {
+    if (!globalAnalytics) return;
+
+    void globalAnalytics.revokeConsent();
+    setConsentGiven(false);
+  }, []);
+
+  useEffect(() => {
+    if (!globalAnalytics) return;
+
+    const status = globalAnalytics.getStatus();
+    // Use setTimeout to avoid synchronous setState in effect
+    setTimeout(() => {
+      setConsentGiven(status.consentGiven);
+    }, 0);
+  }, []);
+
+  return {
+    consentGiven,
+    grantConsent,
+    isLoading,
+    revokeConsent,
+  };
+}
+
+/**
+ * Analytics provider component for App Router
+ */
+export function AnalyticsProvider({
+  autoPageTracking = true,
+  bootstrapData,
+  children,
+  config,
+  pageTrackingOptions,
+}: {
+  children: React.ReactNode;
+  config: AnalyticsConfig;
+  bootstrapData?: BootstrapData;
+  autoPageTracking?: boolean;
+  pageTrackingOptions?: {
+    trackSearch?: boolean;
+    trackParams?: boolean;
+    properties?: Record<string, unknown>;
+    skip?: boolean;
+  };
+}) {
+  // Initialize analytics
+  useEffect(() => {
+    if (!globalAnalytics) {
+      const analyticsConfig = { ...config };
+
+      // Add bootstrap data if provided
+      if (bootstrapData && config.providers.posthog) {
+        analyticsConfig.nextjs = {
+          ...analyticsConfig.nextjs,
+          posthog: {
+            ...analyticsConfig.nextjs?.posthog,
+            bootstrap: bootstrapData,
+          },
+        };
+      }
+
+      // Convert AnalyticsConfig to NextJSClientAnalyticsConfig
+      // Preserve all bootstrap properties (distinctID is required for BootstrapData)
+      const nextjsConfig = {
+        ...analyticsConfig,
+        nextjs: analyticsConfig.nextjs
+          ? ({
+              ...analyticsConfig.nextjs,
+              posthog: analyticsConfig.nextjs.posthog
+                ? {
+                    ...analyticsConfig.nextjs.posthog,
+                    bootstrap:
+                      analyticsConfig.nextjs.posthog.bootstrap?.distinctID !== undefined
+                        ? ({
+                            distinctID: analyticsConfig.nextjs.posthog.bootstrap.distinctID,
+                            // Preserve other bootstrap properties for PostHog functionality
+                            ...(analyticsConfig.nextjs.posthog.bootstrap.isIdentifiedID !==
+                              undefined && {
+                              isIdentifiedID:
+                                analyticsConfig.nextjs.posthog.bootstrap.isIdentifiedID,
+                            }),
+                            ...(analyticsConfig.nextjs.posthog.bootstrap.featureFlags && {
+                              featureFlags: analyticsConfig.nextjs.posthog.bootstrap.featureFlags,
+                            }),
+                            ...(analyticsConfig.nextjs.posthog.bootstrap.featureFlagPayloads && {
+                              featureFlagPayloads:
+                                analyticsConfig.nextjs.posthog.bootstrap.featureFlagPayloads,
+                            }),
+                          } as BootstrapData)
+                        : analyticsConfig.nextjs.posthog.bootstrap,
+                  }
+                : undefined,
+            } as NextJSClientAnalyticsConfig['nextjs'])
+          : undefined,
+      } as NextJSClientAnalyticsConfig;
+
+      globalAnalytics = createNextJSClientAnalytics(nextjsConfig);
+      void globalAnalytics.initialize();
+    }
+  }, [config, bootstrapData]);
+
+  // Auto page tracking
+  usePageTracking(autoPageTracking ? pageTrackingOptions : { skip: true });
+
+  return children as React.ReactElement;
+}
+
+/**
+ * Higher-order component for tracking component views
+ */
+export function withViewTracking<P extends object>(
+  Component: React.ComponentType<P>,
+  eventName: string,
+  getProperties?: (props: P) => Record<string, any>,
+) {
+  return function TrackedComponent(props: P) {
+    const track = useTrackEvent();
+    const tracked = useRef(false);
+
+    useEffect(() => {
+      if (!tracked.current) {
+        tracked.current = true;
+        const properties = getProperties ? getProperties(props) : {};
+        track(eventName, properties);
+      }
+    }, [track, props]);
+
+    return <Component {...props} />;
+  };
+}
+
+/**
+ * Component for tracking clicks
+ */
+export function TrackedButton({
+  children,
+  eventName,
+  onClick,
+  properties,
+  ...props
+}: React.ButtonHTMLAttributes<HTMLButtonElement> & {
+  eventName: string;
+  properties?: Record<string, any>;
+}) {
+  const track = useTrackEvent();
+
+  const handleClick = useCallback(
+    (e: React.MouseEvent<HTMLButtonElement>) => {
+      track(eventName, properties);
+      onClick?.(e);
+    },
+    [track, eventName, properties, onClick],
+  );
+
+  return (
+    <button type="button" {...props} onClick={handleClick}>
+      {children}
+    </button>
+  );
+}
+
+/**
+ * Component for tracking link clicks
+ */
+export function TrackedLink({
+  children,
+  eventName,
+  href,
+  onClick,
+  properties,
+  ...props
+}: React.AnchorHTMLAttributes<HTMLAnchorElement> & {
+  eventName: string;
+  properties?: Record<string, any>;
+}) {
+  const track = useTrackEvent();
+  const router = useRouter();
+
+  const handleClick = useCallback(
+    (e: React.MouseEvent<HTMLAnchorElement>) => {
+      // Track the event
+      const enhancedProperties = {
+        ...properties,
+        href,
+        link_text: typeof children === 'string' ? children : undefined,
+      };
+      void track(eventName, enhancedProperties);
+
+      // Handle navigation
+      if (onClick) {
+        void onClick(e);
+      } else if (href && !props.target && href.startsWith('/')) {
+        // Internal navigation
+        e.preventDefault();
+        router.push(href as Route);
+      }
+    },
+    [track, eventName, properties, href, onClick, router, children, props.target],
+  );
+
+  return (
+    <a {...props} href={href} onClick={handleClick}>
+      {children}
+    </a>
+  );
+}
+
+/**
+ * Hook for tracking form submissions
+ */
+export function useFormTracking(formName: string) {
+  const track = useTrackEvent();
+
+  const trackFormStart = useCallback(() => {
+    track('Form Started', { form_name: formName });
+  }, [track, formName]);
+
+  const trackFormSubmit = useCallback(
+    (data?: any) => {
+      track('Form Submitted', {
+        form_name: formName,
+        field_count: data ? Object.keys(data).length : undefined,
+      });
+    },
+    [track, formName],
+  );
+
+  const trackFormError = useCallback(
+    (error: any) => {
+      track('Form Error', {
+        form_name: formName,
+        error_message: error?.message ?? String(error),
+      });
+    },
+    [track, formName],
+  );
+
+  const trackFieldInteraction = useCallback(
+    (fieldName: string) => {
+      track('Form Field Interacted', {
+        field_name: fieldName,
+        form_name: formName,
+      });
+    },
+    [track, formName],
+  );
+
+  return {
+    trackFieldInteraction,
+    trackFormError,
+    trackFormStart,
+    trackFormSubmit,
+  };
+}
+
+/**
+ * Hook for e-commerce tracking helpers
+ */
+export function useEcommerceTracking() {
+  const track = useTrackEvent();
+
+  const trackProductView = useCallback(
+    (product: {
+      id: string;
+      name: string;
+      price?: number;
+      category?: string;
+      [key: string]: any;
+    }) => {
+      void track('Product Viewed', {
+        product_id: product.id,
+        product_name: product.name,
+        category: product.category,
+        price: product.price,
+        ...product,
+      });
+    },
+    [track],
+  );
+
+  const trackAddToCart = useCallback(
+    (product: {
+      id: string;
+      name: string;
+      price?: number;
+      quantity?: number;
+      [key: string]: any;
+    }) => {
+      track('Product Added to Cart', {
+        product_id: product.id,
+        product_name: product.name,
+        price: product.price,
+        quantity: product.quantity ?? 1,
+        ...product,
+      });
+    },
+    [track],
+  );
+
+  const trackCheckout = useCallback(
+    (cart: { total: number; items: any[]; [key: string]: any }) => {
+      const { items, total, ...otherProps } = cart;
+      track('Checkout Started', {
+        item_count: items.length,
+        total,
+        ...otherProps,
+      });
+    },
+    [track],
+  );
+
+  const trackPurchase = useCallback(
+    (order: { orderId: string; total: number; items: any[]; [key: string]: any }) => {
+      const { items, orderId, total, ...otherProps } = order;
+      track('Order Completed', {
+        order_id: orderId,
+        item_count: items.length,
+        total,
+        ...otherProps,
+      });
+    },
+    [track],
+  );
+
+  return {
+    trackAddToCart,
+    trackCheckout,
+    trackProductView,
+    trackPurchase,
+  };
+}
+
+/**
+ * Utility to reset analytics (useful for testing)
+ */
+export function resetAnalytics() {
+  globalAnalytics = null;
+}