@akson/cortex-analytics-react 2.0.0

package/README.md

@@ -0,0 +1,330 @@
+# @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
+
+```bash
+npm install @akson/cortex-analytics-react
+```
+
+## Quick Start
+
+### 1. Setup Provider
+
+```tsx
+import React from 'react';
+import { AnalyticsProvider, type AnalyticsConfig } from '@akson/cortex-analytics-react';
+import { LEAD_GENERATION_EVENTS } from '@akson/cortex-api-shared/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
+
+```tsx
+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.
+
+```tsx
+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: 'user@example.com' });
+  analytics.sendUserData({ email: 'user@example.com', 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.
+
+```tsx
+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.90, {
+      product_type: 'custom_badge',
+      currency: 'CHF',
+    });
+  };
+  
+  return <div>...</div>;
+}
+```
+
+### `useLeadTracking()`
+Hook for lead generation scenarios.
+
+```tsx
+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.
+
+```tsx
+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
+
+```typescript
+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
+
+```typescript
+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-api-shared`:
+
+```typescript
+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:
+
+```tsx
+// 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
+
+```bash
+# 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-api-shared` - Standardized event definitions
+- `@akson/cortex-api-gtm` - GTM API client
+- `@akson/cortex-api-posthog` - PostHog API client
+
+## License
+
+MIT

package/package.json

@@ -0,0 +1,63 @@
+{
+	"name": "@akson/cortex-analytics-react",
+	"version": "2.0.0",
+	"description": "Reusable React analytics components and hooks for @cortex ecosystem",
+	"main": "dist/index.js",
+	"module": "dist/index.mjs",
+	"types": "dist/index.d.ts",
+	"files": [
+		"dist",
+		"LICENSE",
+		"README.md"
+	],
+	"scripts": {
+		"build": "tsup",
+		"dev": "tsup --watch",
+		"type-check": "tsc --noEmit",
+		"clean": "rm -rf dist",
+		"test": "jest"
+	},
+	"peerDependencies": {
+		"react": "^18.0.0 || ^19.0.0",
+		"react-dom": "^18.0.0 || ^19.0.0"
+	},
+	"dependencies": {
+		"@akson/cortex-api-gtm": "^2.0.0",
+		"@akson/cortex-api-posthog": "^0.1.0",
+		"@akson/cortex-api-shared": "^0.3.0"
+	},
+	"devDependencies": {
+		"@types/react": "^19.0.0",
+		"@types/react-dom": "^19.0.0",
+		"react": "^19.1.0",
+		"react-dom": "^19.1.0",
+		"tsup": "^8.0.2",
+		"typescript": "^5.3.3"
+	},
+	"keywords": [
+		"analytics",
+		"react",
+		"hooks",
+		"gtm",
+		"posthog",
+		"tracking"
+	],
+	"author": "MyArmy <contact@myarmy.ch>",
+	"license": "MIT",
+	"homepage": "https://github.com/antoineschaller/myarmy/tree/main/packages/@akson/cortex-analytics-react",
+	"repository": {
+		"type": "git",
+		"url": "https://github.com/antoineschaller/myarmy.git",
+		"directory": "packages/@akson/cortex-analytics-react"
+	},
+	"engines": {
+		"node": ">=18.0.0"
+	},
+	"exports": {
+		".": {
+			"types": "./dist/index.d.ts",
+			"import": "./dist/index.js"
+		}
+	},
+	"gitHead": "84153813d2b6cc183f00f23d04cf0e887c512fbe"
+}