ABC Mix Panel Package

A comprehensive analytics and tracking package for the ABC system, providing Mixpanel integration with React components and event tracking utilities for user behavior analysis.

📦 Installation

pnpm add abc-mix-pane

🚀 Key Features

1. Mixpanel Integration

• Seamless Mixpanel browser SDK integration
• React component for easy initialization
• Automatic configuration with debug mode and localStorage persistence
• Client-side only execution with "use client" directive

2. Event Tracking

• Application-specific event tracking with automatic prefixing
• Error handling and graceful degradation
• Development environment filtering
• Type-safe event data handling

3. Easy Setup

• Simple React component for initialization
• Automatic token-based configuration
• No additional setup required for basic tracking

📚 API Reference

Components

MixPaneInit

React component for initializing Mixpanel with the provided token.

import { MixPaneInit } from "abc-mix-pane";

<MixPaneInit token="your-mixpanel-token" />

Props:

• token - Mixpanel project token (string)

Features:

• Automatic initialization on component mount
• Debug mode enabled for development
• localStorage persistence for user sessions
• Page view tracking disabled by default

Event Tracking

trackingEventMixpanel

Utility function for tracking custom events with application-specific naming.

import { trackingEventMixpanel } from "abc-mix-pane";

trackingEventMixpanel({
  eventName: "button_click",
  value: { buttonId: "header-cta", page: "home" },
  appShortName: "asvab",
});

Parameters:

• eventName - Name of the event to track (string)
• value - Optional event data object (unknown)
• appShortName - Application short name for event prefixing (string)

Features:

• Automatic event name prefixing with app short name
• Development environment filtering
• Error handling with console logging
• Type-safe data handling

🎨 Usage Examples

Basic Initialization

import { MixPaneInit } from "abc-mix-pane";

export default function App() {
  return (
    <div>
      <MixPaneInit token={process.env.NEXT_PUBLIC_MIXPANEL_TOKEN} />
      {/* Your app content */}
    </div>
  );
}

Event Tracking

import { trackingEventMixpanel } from "abc-mix-pane";

// Track user actions
const handleButtonClick = () => {
  trackingEventMixpanel({
    eventName: "cta_clicked",
    value: {
      buttonText: "Start Test",
      page: "homepage",
      timestamp: Date.now(),
    },
    appShortName: "asvab",
  });
};

// Track page views
const trackPageView = (pageName: string) => {
  trackingEventMixpanel({
    eventName: "page_view",
    value: { page: pageName },
    appShortName: "easyprep",
  });
};

Custom Hook Integration

import { useCallback } from "react";
import { trackingEventMixpanel } from "abc-mix-pane";

export const useAnalytics = (appShortName: string) => {
  const trackEvent = useCallback(
    (eventName: string, value?: unknown) => {
      trackingEventMixpanel({
        eventName,
        value,
        appShortName,
      });
    },
    [appShortName]
  );

  return { trackEvent };
};

🧪 Testing

# Run tests
pnpm test

# Run tests with coverage
pnpm test:coverage

# Run tests once
pnpm test:run

🔧 Development

# Build package
pnpm build

# Development mode
pnpm dev

# Clean dist
pnpm clean

📦 Dependencies

Production Dependencies

• mixpanel-browser - Mixpanel browser SDK for analytics tracking

Development Dependencies

• @types/node - Node.js type definitions
• vitest - Testing framework
• @vitest/coverage-v8 - Coverage reporting
• jsdom - DOM environment for tests

🎯 Use Cases

Application Analytics

• ASVAB Application - Track user interactions and test progress
• CDL Application - Monitor study patterns and completion rates
• EasyPrep Application - Analyze learning behavior and engagement

Event Tracking

• User Actions - Button clicks, form submissions, navigation
• Page Views - Track user journey through the application
• Custom Events - Business-specific metrics and KPIs
• Error Tracking - Monitor application errors and issues

Analytics Features

• Debug Mode - Development-friendly logging and debugging
• Persistence - User session tracking across page reloads
• Error Handling - Graceful degradation when tracking fails
• Environment Filtering - Automatic filtering in development mode

🔗 Integration

With Next.js

// app/layout.tsx
import { MixPaneInit } from "abc-mix-pane";

export default function RootLayout({
  children,
}: {
  children: React.ReactNode;
}) {
  return (
    <html>
      <body>
        <MixPaneInit token={process.env.NEXT_PUBLIC_MIXPANEL_TOKEN} />
        {children}
      </body>
    </html>
  );
}

With Custom Analytics Hook

// hooks/useAnalytics.ts
import { useCallback } from "react";
import { trackingEventMixpanel } from "abc-mix-pane";

export const useAnalytics = (appShortName: string) => {
  const trackEvent = useCallback(
    (eventName: string, value?: unknown) => {
      trackingEventMixpanel({ eventName, value, appShortName });
    },
    [appShortName]
  );

  const trackPageView = useCallback(
    (page: string) => {
      trackEvent("page_view", { page });
    },
    [trackEvent]
  );

  const trackUserAction = useCallback(
    (action: string, data?: unknown) => {
      trackEvent("user_action", { action, ...data });
    },
    [trackEvent]
  );

  return { trackEvent, trackPageView, trackUserAction };
};

📱 Environment Configuration

Development

• Debug mode enabled
• Console logging for troubleshooting
• Event tracking disabled in development

Production

• Debug mode disabled
• Full event tracking enabled
• Error handling with graceful degradation

📄 License

MIT