@akson/cortex-analytics-react

Reusable React analytics components and hooks for the @akson ecosystem. Provides a unified, configuration-driven approach to analytics tracking across multiple platforms.

Features

• 🎯 Unified API: Single interface for GTM, PostHog, GA4, Google Ads, and Meta tracking
• ⚡ Type-Safe: Full TypeScript support with standardized event types
• 🎣 React Hooks: Purpose-built hooks for different tracking scenarios
• 🔧 Configuration-Driven: Easy setup with JSON/TypeScript configuration
• 📊 Funnel Tracking: Advanced funnel analysis with abandonment tracking
• 🎪 Session Management: Built-in session handling and persistence
• 🛡️ Error-Safe: Graceful handling of blocked trackers and storage errors

Installation

npm install @akson/cortex-analytics-react

Quick Start

1. Setup Provider

import React from "react";
import {
  AnalyticsProvider,
  type AnalyticsConfig,
} from "@akson/cortex-analytics-react";
import { LEAD_GENERATION_EVENTS } from "@akson/cortex-utilities/events";

const analyticsConfig: AnalyticsConfig = {
  platforms: {
    gtm: {
      containerId: "GTM-XXXXXXX",
      workspaceId: 40,
    },
    posthog: {
      apiKey: "phc_your_key",
      host: "https://app.posthog.com",
    },
    ga4: {
      measurementId: "G-XXXXXXXXXX",
    },
  },
  conversions: {
    [LEAD_GENERATION_EVENTS.LEAD_FORM_SUBMITTED]: "CONVERSION_LABEL_1",
    [LEAD_GENERATION_EVENTS.LEAD_WHATSAPP_CONTACT]: "CONVERSION_LABEL_2",
  },
  debug: process.env.NODE_ENV === "development",
};

export default function App({ children }) {
  return (
    <AnalyticsProvider config={analyticsConfig}>{children}</AnalyticsProvider>
  );
}

2. Use Analytics Hooks

import React from "react";
import {
  useAnalytics,
  LEAD_GENERATION_EVENTS,
} from "@akson/cortex-analytics-react";

export function ContactForm() {
  const analytics = useAnalytics();

  const handleSubmit = (formData: any) => {
    // Track standardized lead event
    analytics.track(LEAD_GENERATION_EVENTS.LEAD_FORM_SUBMITTED, {
      form_type: "contact",
      source: "header",
      lead_score: 100,
    });
  };

  return <form onSubmit={handleSubmit}>{/* Your form */}</form>;
}

Available Hooks

useAnalytics()

Core analytics hook with full tracking capabilities.

import { useAnalytics } from "@akson/cortex-analytics-react";

function Component() {
  const analytics = useAnalytics();

  // Basic tracking
  analytics.track("custom_event", { property: "value" });
  analytics.trackPageView("/page", "Page Title");
  analytics.trackInteraction("button", "click", "header_cta");

  // User identification
  analytics.identify("user123", { email: "[email protected]" });
  analytics.sendUserData({ email: "[email protected]", phone: "+1234567890" });

  // Session utilities
  const sessionId = analytics.getSessionId();
  const funnelPath = analytics.getFunnelPath();
  const timeInFunnel = analytics.getTimeInFunnel();

  return <div>...</div>;
}

useFunnelTracking()

Specialized hook for funnel analysis.

import { useFunnelTracking } from "@akson/cortex-analytics-react";

function OrderForm() {
  const funnel = useFunnelTracking();

  const handleStepComplete = (step: string) => {
    funnel.trackStage(step, {
      completion_time: 30,
      source: "organic",
    });
  };

  const handleAbandonment = () => {
    funnel.trackAbandonment("step_2", "form_error");
  };

  const handleConversion = () => {
    funnel.trackConversion("order", 149.9, {
      product_type: "custom_badge",
      currency: "CHF",
    });
  };

  return <div>...</div>;
}

useLeadTracking()

Hook for lead generation scenarios.

import {
  useLeadTracking,
  LEAD_GENERATION_EVENTS,
} from "@akson/cortex-analytics-react";

function LeadCapture() {
  const lead = useLeadTracking();

  const handleFormSubmit = (userData: any) => {
    // Track the lead event
    lead.trackLead(LEAD_GENERATION_EVENTS.LEAD_FORM_SUBMITTED, {
      lead_score: 100,
      source: "landing_page",
      form_type: "quote_request",
    });

    // Send user data for enhanced conversions
    lead.sendUserData({
      email: userData.email,
      phone: userData.phone,
      firstName: userData.firstName,
    });
  };

  return <div>...</div>;
}

useEcommerceTracking()

Hook for e-commerce events.

import {
  useEcommerceTracking,
  ECOMMERCE_EVENTS,
} from "@akson/cortex-analytics-react";

function ProductPage() {
  const ecommerce = useEcommerceTracking();

  const handlePurchase = (orderData: any) => {
    ecommerce.trackEcommerce(ECOMMERCE_EVENTS.PURCHASE, {
      value: orderData.total,
      currency: "CHF",
      transaction_id: orderData.id,
      items: orderData.items.map((item) => ({
        item_name: item.name,
        price: item.price,
        quantity: item.quantity,
      })),
    });
  };

  return <div>...</div>;
}

Configuration

Platform Configuration

interface AnalyticsConfig {
  platforms: {
    gtm?: {
      containerId: string;
      workspaceId?: number;
    };
    posthog?: {
      apiKey: string;
      host?: string;
    };
    ga4?: {
      measurementId: string;
    };
    googleAds?: {
      accountId: string;
    };
    meta?: {
      pixelId: string;
    };
  };
  conversions?: Record<string, string>; // Event -> Conversion label mapping
  funnel?: FunnelConfig;
  debug?: boolean;
  enableEnhancedConversions?: boolean;
}

Funnel Configuration

interface FunnelConfig {
  stages?: Record<string, string[]>; // Stage name -> Event names
  scoring?: (stage: string) => number;
  abandonmentTracking?: boolean;
  sessionTimeout?: number; // milliseconds
}

Standardized Events

The package uses standardized events from @akson/cortex-utilities:

import {
  LEAD_GENERATION_EVENTS,
  ECOMMERCE_EVENTS,
} from "@akson/cortex-analytics-react";

// Lead generation events (scored 1-100)
LEAD_GENERATION_EVENTS.LEAD_PAGE_VIEW; // Score: 5
LEAD_GENERATION_EVENTS.LEAD_CONTENT_VIEW; // Score: 15
LEAD_GENERATION_EVENTS.LEAD_INQUIRY_STARTED; // Score: 40
LEAD_GENERATION_EVENTS.LEAD_CONTACT_INFO; // Score: 60
LEAD_GENERATION_EVENTS.LEAD_WHATSAPP_CONTACT; // Score: 85
LEAD_GENERATION_EVENTS.LEAD_FORM_SUBMITTED; // Score: 100

// E-commerce events (with monetary values)
ECOMMERCE_EVENTS.VIEW_ITEM; // Product views
ECOMMERCE_EVENTS.ADD_TO_CART; // Cart additions
ECOMMERCE_EVENTS.BEGIN_CHECKOUT; // Checkout started
ECOMMERCE_EVENTS.PURCHASE; // Completed transactions

Migration from Landing Analytics

If migrating from the landing page analytics system:

// OLD: Landing-specific analytics
import { Analytics, FUNNEL_STAGES } from "@/app/lib/analytics";

// NEW: @akson/cortex-analytics-react
import {
  useAnalytics,
  LEAD_GENERATION_EVENTS,
} from "@akson/cortex-analytics-react";

function Component() {
  const analytics = useAnalytics();

  // OLD: Analytics.trackStage(FUNNEL_STAGES.FORM_SUBMITTED)
  // NEW:
  analytics.track(LEAD_GENERATION_EVENTS.LEAD_FORM_SUBMITTED, {
    lead_score: 100,
  });
}

Development

# Install dependencies
npm install

# Build package
npm run build

# Watch mode for development
npm run dev

# Type checking
npm run type-check

# Run tests (when implemented)
npm test

Architecture

The package follows a layered architecture:

• Adapters: Platform-specific implementations (GTM, PostHog)
• Utilities: Session management, storage, device detection
• Hooks: React integration layer
• Providers: Context and configuration management
• Types: Comprehensive TypeScript definitions

Dependencies

Peer Dependencies

• react ^18.0.0
• react-dom ^18.0.0

Dependencies

• @akson/cortex-utilities - Standardized event definitions
• @akson/cortex-gtm - GTM API client
• @akson/cortex-posthog - PostHog API client

License

MIT