MentiQ Analytics SDK

A powerful, lightweight analytics SDK for React and Next.js applications with advanced features like event queuing, batching, heatmap tracking, session monitoring, and performance analytics.

🌟 Features

Core Analytics

• 🎯 Event tracking with custom properties
• 📄 Page view tracking with auto-tracking
• 👤 User identification and management
• 🔄 Event batching and queuing with retry logic
• 📱 Session management and monitoring

Advanced Features

• 🔥 Heatmap Tracking: Click, hover, and scroll tracking
• 📊 Session Monitoring: User activity, scroll depth, engagement metrics
• 🎥 Session Recording: Replay user sessions with rrweb
• ⚡ Performance Tracking: Core Web Vitals, custom performance metrics
• 🚨 Error Tracking: JavaScript errors, unhandled rejections, React errors
• 🎯 Onboarding Tracking: Track user activation funnels and measure completion rates
• 🎭 React Components: Pre-built tracking components and HOCs
• 🧪 A/B Testing: Experiment management and variant tracking

Technical Features

• 📦 Event queuing with configurable batch sizes
• 🔄 Automatic retry with exponential backoff
• 🏪 Local storage for offline support
• 🎣 React hooks for easy integration
• 📱 TypeScript support with full type safety
• 🚀 Next.js optimized utilities

📦 Installation

npm install mentiq-sdk
# or
yarn add mentiq-sdk

🚀 Quick Start

Basic Setup

import React from "react";
import { AnalyticsProvider } from "mentiq-sdk";

function App() {
  return (
    <AnalyticsProvider
      config={{
        apiKey: "your-api-key", // Your Mentiq API Key
        projectId: "your-project-id", // Your Mentiq Project ID
        endpoint: "https://your-endpoint.com/events",
        enableHeatmapTracking: true,
        enableSessionRecording: true,
        enableErrorTracking: true,
        batchSize: 10,
        flushInterval: 5000,
      }}
    >
      <YourApp />
    </AnalyticsProvider>
  );
}

Using Hooks

import React from "react";
import { useAnalytics, useSessionTracking } from "mentiq-sdk";

function MyComponent() {
  const { track, trackError } = useAnalytics();
  const { sessionData } = useSessionTracking();

  const handleButtonClick = () => {
    track("button_clicked", {
      button_id: "hero-cta",
      user_plan: "premium",
    });
  };

  return (
    <div>
      <button onClick={handleButtonClick}>Track Me!</button>
      <p>Session duration: {sessionData?.duration}ms</p>
    </div>
  );
}

⚙️ Configuration

interface AnalyticsConfig {
  apiKey: string;
  projectId: string;
  endpoint?: string;
  debug?: boolean;
  userId?: string;
  sessionTimeout?: number; // Default: 30 minutes
  batchSize?: number; // Default: 20 events
  flushInterval?: number; // Default: 10 seconds
  enableAutoPageTracking?: boolean; // Default: true
  enablePerformanceTracking?: boolean;
  enableHeatmapTracking?: boolean;
  enableSessionRecording?: boolean;
  enableErrorTracking?: boolean;
  maxQueueSize?: number; // Default: 1000
  retryAttempts?: number; // Default: 3
  retryDelay?: number; // Default: 1000ms
}

🎣 Core Hooks

useAnalytics()

Main hook for tracking events and managing users.

const {
  track, // Track custom events
  page, // Track page views
  identify, // Identify users
  reset, // Reset analytics state
  flush, // Force flush events
  trackError, // Track custom errors
  trackPerformance, // Track performance metrics
  getSessionData, // Get current session data
  getQueueSize, // Get current queue size
  startRecording, // Start session recording
  stopRecording, // Stop session recording
  pauseRecording, // Pause session recording
  resumeRecording, // Resume session recording
  isRecordingActive, // Check if recording is active
  trackSubscriptionCancellation, // Track subscription cancellations
} = useAnalytics();

useSessionTracking()

Monitor user session data in real-time.

const {
  sessionData, // Full session object
  sessionId, // Current session ID
  isActive, // Is session active
  duration, // Session duration in ms
  pageViews, // Number of page views
  clicks, // Number of clicks
  scrollDepth, // Current scroll depth %
} = useSessionTracking();

useErrorTracking()

Automatic and manual error tracking.

const {
  trackJavaScriptError, // Track JS errors
  trackCustomError, // Track custom errors
} = useErrorTracking();

usePerformanceTracking()

Track performance metrics and Core Web Vitals.

const {
  measureCustomPerformance, // Create custom performance measurements
} = usePerformanceTracking();

🧩 Components

TrackView - Element Visibility Tracking

<TrackView
  event="hero_viewed"
  properties={{ section: "homepage" }}
  threshold={0.5}
  delay={1000}
>
  <div>Tracked when 50% visible for 1 second</div>
</TrackView>

HeatmapTracker - User Interaction Tracking

<HeatmapTracker trackClicks={true} trackHovers={true} element="product-grid">
  <div>All interactions tracked for heatmap</div>
</HeatmapTracker>

PerformanceMonitor - Component Performance

<PerformanceMonitor measureRender={true} componentName="ProductList">
  <ProductList products={products} />
</PerformanceMonitor>

AnalyticsErrorBoundary - Error Tracking

<AnalyticsErrorBoundary fallback={<ErrorFallback />}>
  <App />
</AnalyticsErrorBoundary>

TrackForm - Form Analytics

<TrackForm formName="contact-form" trackSubmit={true} trackFieldChanges={true}>
  <input name="email" type="email" />
  <textarea name="message" />
  <button type="submit">Submit</button>
</TrackForm>

🎯 Onboarding Tracking

Track user onboarding flows with the OnboardingTracker helper. Perfect for measuring funnel completion, identifying dropoff points, and optimizing user activation.

⚠️ Important: Not Automatic!

The OnboardingTracker is a helper class that formats and sends events. You must manually call tracker methods when users complete steps.

Basic Usage

import { useOnboardingTracker, useMentiqAnalytics } from "mentiq-sdk";

function OnboardingFlow() {
  const analytics = useMentiqAnalytics();

  // Define your onboarding steps
  const config = {
    steps: [
      { name: "account_created", index: 0, required: true },
      { name: "profile_completed", index: 1, required: true },
      { name: "preferences_set", index: 2, required: false },
      { name: "first_action", index: 3, required: true },
    ],
  };

  const tracker = useOnboardingTracker(analytics, config);

  // Start onboarding
  useEffect(() => {
    tracker?.start({
      signup_method: "email",
      source: "landing_page",
    });
  }, []);

  // Track step completion
  const handleProfileComplete = async () => {
    await saveProfile();
    tracker?.completeStep("profile_completed", {
      fields_filled: ["name", "email", "company"],
    });
  };

  // Skip optional steps
  const handleSkip = () => {
    tracker?.skipStep("preferences_set", "user_choice");
  };

  // Get progress
  const progress = tracker?.getProgress();
  console.log(`${progress?.progressPercent}% complete`);

  return <div>{/* Your onboarding UI */}</div>;
}

Onboarding Tracker API

// Start onboarding flow
tracker.start(properties?: Record<string, any>)

// Complete a step
tracker.completeStep(stepName: string, properties?: Record<string, any>)

// Skip optional steps
tracker.skipStep(stepName: string, reason?: string)

// Mark as complete
tracker.complete(properties?: Record<string, any>)

// Abandon onboarding
tracker.abandon(reason?: string)

// Get current progress
const progress = tracker.getProgress()
// Returns: { currentStep, completedSteps, progressPercent, duration }

How It Works

1. You call tracker methods → Events are sent to backend
2. Events stored in database with metadata (step_index, timing, properties)
3. Backend analyzes events → Calculates funnel statistics
4. Dashboard displays analytics → Completion rates, dropoff points, time metrics

Events Sent

The tracker automatically sends these events:

• onboarding_started - When onboarding begins
• onboarding_step_completed - When each step is completed
• onboarding_step_skipped - When optional steps are skipped
• onboarding_completed - When all required steps are done
• onboarding_abandoned - When user exits early

Dashboard Analytics

View onboarding metrics in your dashboard:

• Completion Rate: % of users who finish onboarding
• Step-by-Step Breakdown: Completion rate for each step
• Dropoff Points: Steps where users abandon most
• Average Time: Time taken per step and total
• User Journeys: Individual user progress tracking

Examples

See examples/onboarding-tracking.tsx for complete examples:

• Basic onboarding flow
• Multi-step form tracking
• Product tour / tutorial
• SaaS onboarding with conditional steps
• Progress monitor component
• Vanilla JavaScript (non-React)

🔄 Event Queuing & Batching

The SDK automatically queues events and sends them in batches:

• Batch Size: Configure events per batch
• Flush Interval: Automatic sending frequency
• Retry Logic: Exponential backoff for failed requests
• Offline Support: Queue events when offline

const { flush, getQueueSize } = useAnalytics();

console.log(`${getQueueSize()} events queued`);
await flush(); // Send all events immediately

🚨 Error Handling

Automatic Error Tracking

• JavaScript errors
• Unhandled Promise rejections
• React component errors

Manual Error Tracking

const { trackError } = useAnalytics();

try {
  // risky operation
} catch (error) {
  trackError(error, {
    context: "user-action",
    user_id: userId,
  });
}

⚡ Performance Monitoring

Core Web Vitals

Automatically tracks when enablePerformanceTracking: true:

• LCP (Largest Contentful Paint)
• FID (First Input Delay)
• CLS (Cumulative Layout Shift)
• FCP (First Contentful Paint)

Custom Performance Metrics

const { measureCustomPerformance } = usePerformanceTracking();

const measurement = measureCustomPerformance("api-call");
measurement.start();
await fetchData();
measurement.end(); // Automatically tracked

🎥 Session Recording

Record and replay user sessions with rrweb integration.

Installation

npm install rrweb

Basic Usage

import { AnalyticsProvider } from "mentiq-sdk";

<AnalyticsProvider
  config={{
    apiKey: "your-api-key",
    projectId: "your-project-id",
    enableSessionRecording: true, // Enable automatic recording
  }}
>
  <App />
</AnalyticsProvider>;

Manual Control

import { useAnalytics } from "mentiq-sdk";

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

  return (
    <div>
      <button onClick={() => analytics.startRecording()}>
        Start Recording
      </button>
      <button onClick={() => analytics.stopRecording()}>Stop Recording</button>
      <button onClick={() => analytics.pauseRecording()}>Pause</button>
      <button onClick={() => analytics.resumeRecording()}>Resume</button>
      {analytics.isRecordingActive() && <span>🔴 Recording Active</span>}
    </div>
  );
}

Privacy & Masking

// Add CSS classes to protect sensitive data
<input
  type="password"
  className="mentiq-block" // Completely block from recording
/>

<div className="mentiq-mask">
  Sensitive text content
</div>

<div className="mentiq-ignore">
  This section won't be recorded
</div>

Custom Configuration

import { SessionRecorder } from "mentiq-sdk";

const recorder = new SessionRecorder(
  analytics.config,
  analytics.getSessionId(),
  {
    maxDuration: 10 * 60 * 1000, // 10 minutes
    blockClass: "sensitive",
    maskAllInputs: true,
    sampling: {
      mousemove: 50, // Sample every 50ms
      scroll: 150, // Sample every 150ms
      input: "last", // Only record final value
    },
  }
);

Note: Recordings are automatically uploaded to /api/v1/sessions/:session_id/recordings every 10 seconds. See SESSION-RECORDING.md for detailed documentation.

📱 Session Management

Rich session tracking includes:

• Session duration and activity
• Page views and navigation
• User interactions (clicks, scrolls)
• Scroll depth and engagement
• Activity/inactivity periods

🚀 Next.js Integration

App Router (app/)

// app/layout.tsx
import { AnalyticsProvider } from "mentiq-sdk";

export default function RootLayout({ children }) {
  return (
    <html>
      <body>
        <AnalyticsProvider config={{ apiKey: "your-key" }}>
          {children}
        </AnalyticsProvider>
      </body>
    </html>
  );
}

Pages Router (pages/)

// pages/_app.tsx
import { AnalyticsProvider } from "mentiq-sdk";

export default function App({ Component, pageProps }) {
  return (
    <AnalyticsProvider config={{ apiKey: "your-key" }}>
      <Component {...pageProps} />
    </AnalyticsProvider>
  );
}

📊 Example Use Cases

E-commerce Tracking

function ProductPage({ product }) {
  const { track } = useAnalytics();

  return (
    <TrackView
      event="product_viewed"
      properties={{
        product_id: product.id,
        category: product.category,
        price: product.price,
      }}
    >
      <ProductDetails product={product} />

      <TrackClick event="add_to_cart" properties={{ product_id: product.id }}>
        <button>Add to Cart</button>
      </TrackClick>
    </TrackView>
  );
}

Content Engagement

function BlogPost({ post }) {
  return (
    <TrackScroll milestones={[25, 50, 75, 100]}>
      <TrackTime intervals={[30, 60, 180]}>
        <article>
          <h1>{post.title}</h1>
          <div>{post.content}</div>
        </article>
      </TrackTime>
    </TrackScroll>
  );
}

📚 TypeScript Support

Full TypeScript support with comprehensive types:

import type {
  AnalyticsConfig,
  EventProperties,
  SessionData,
  PerformanceData,
} from "mentiq-sdk";

const config: AnalyticsConfig = {
  apiKey: "key",
  enableHeatmapTracking: true,
};

📋 API Reference

Analytics Class Methods

// Core tracking
analytics.track(event: string, properties?: EventProperties)
analytics.page(properties?: PageProperties)
analytics.identify(userId: string, traits?: UserProperties)

// Queue management
analytics.flush(): Promise<void>
analytics.getQueueSize(): number
analytics.clearQueue(): void

// Advanced tracking
analytics.trackCustomError(error: string | Error, properties?: EventProperties)
analytics.trackPerformance(data: PerformanceData)

✅ Quick Start Checklist

Basic Setup

• [ ] Install SDK: npm install mentiq-sdk
• [ ] Wrap app with <AnalyticsProvider>
• [ ] Add your API key and project ID
• [ ] Verify events in your dashboard

Onboarding Tracking Setup

• [ ] Import OnboardingTracker or useOnboardingTracker
• [ ] Define your onboarding steps configuration
• [ ] Call tracker.start() when onboarding begins
• [ ] Add tracker.completeStep() calls at completion points
• [ ] View funnel analytics in dashboard
• [ ] See examples/onboarding-tracking.tsx for full examples

Session Recording Setup

• [ ] Install rrweb: npm install rrweb
• [ ] Enable enableSessionRecording: true
• [ ] Add privacy CSS classes to sensitive elements
• [ ] Test recording start/stop
• [ ] Verify uploads to backend endpoint

Privacy & Compliance

• [ ] Add .mentiq-block to password inputs
• [ ] Add .mentiq-mask to sensitive text
• [ ] Add .mentiq-ignore to private sections
• [ ] Implement user consent if required
• [ ] Review and test privacy settings

Production Optimization

• [ ] Configure appropriate batch sizes
• [ ] Set reasonable flush intervals
• [ ] Adjust sampling rates for performance
• [ ] Set max session duration
• [ ] Test error handling and retries

See SESSION-RECORDING.md for detailed setup instructions.

🚀 Publishing

To publish the SDK:

npm run build
npm run test
npm publish

📄 License

MIT License - Free for personal and commercial use.

🆘 Support

• 📝 Documentation
• 🐛 Issues
• 💬 Discussions