mentiq-sdk

v1.0.9

Published

18 days ago

A powerful analytics SDK for React and Next.js with heatmap tracking, session monitoring, and performance analytics

Downloads

587

MentiQ Analytics SDK

A powerful, full-featured analytics SDK for React and Next.js with advanced features including A/B testing, subscription tracking, churn prediction, conversion funnels, session recording, heatmaps, and performance analytics. Also supports vanilla JavaScript for framework-agnostic integration.

🌟 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: Full-featured experimentation with hooks and components
💳 Subscription Tracking: Revenue tracking with Stripe/Paddle/Chargebee auto-detection
📈 Funnel Analytics: Multi-step conversion funnel tracking
🎲 Churn Prediction: Real-time churn risk scoring and monitoring

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 (One File Setup)

Add <Mentiq> to your root layout — that's it. Page views and errors are tracked automatically.

// app/layout.tsx (Next.js) or App.tsx (React)
import { Mentiq } from "mentiq-sdk";

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html>
      <body>
        <Mentiq apiKey="your-api-key" projectId="your-project-id">
          {children}
        </Mentiq>
      </body>
    </html>
  );
}

Then track custom events anywhere with useMentiq():

import { useMentiq } from "mentiq-sdk";

function SignupButton() {
  const { track, identify } = useMentiq();

  return (
    <button onClick={() => track("signup_clicked", { plan: "pro" })}>
      Sign Up
    </button>
  );
}

Mentiq Props

| Prop | Type | Default | Description | |------|------|---------|-------------| | apiKey | string | required | Your MentiQ API key | | projectId | string | required | Your MentiQ project ID | | endpoint | string | https://api.mentiq.io | API endpoint URL | | userId | string | — | Pre-identify a user | | trackPageViews | boolean | true | Auto-track page views | | trackErrors | boolean | true | Auto-track JS errors | | trackPerformance | boolean | false | Track Core Web Vitals | | trackHeatmaps | boolean | false | Track clicks/scrolls/hovers | | trackSessions | boolean | false | Record sessions (requires rrweb) |

Advanced Setup

For more control, use the full AnalyticsProvider:

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

function App() {
  return (
    <AnalyticsProvider
      config={{
        apiKey: "your-api-key",
        projectId: "your-project-id",
        endpoint: "https://your-endpoint.com",
        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;
  enableABTesting?: boolean; // Enable A/B testing features
  maxQueueSize?: number; // Default: 1000
  retryAttempts?: number; // Default: 3
  retryDelay?: number; // Default: 1000ms
}

🎣 Core Hooks

useAnalytics()

Main hook for tracking events and managing users.

const {
  // Core tracking
  track, // Track custom events
  page, // Track page views
  identify, // Identify users
  alias, // Merge user identities
  reset, // Reset analytics state

  // Queue management
  flush, // Force flush events
  getQueueSize, // Get current queue size

  // Error & Performance
  trackError, // Track custom errors
  trackPerformance, // Track performance metrics

  // Session data
  getSessionData, // Get current session data
  getActiveSession, // Get active session object
  calculateEngagementScore, // Get engagement score (0-100)

  // Session recording
  startRecording, // Start session recording
  stopRecording, // Stop session recording
  pauseRecording, // Pause session recording
  resumeRecording, // Resume session recording
  isRecordingActive, // Check if recording is active

  // Funnel tracking
  startFunnel, // Start a conversion funnel
  advanceFunnel, // Move to next funnel step
  completeFunnel, // Complete a funnel
  abandonFunnel, // Abandon a funnel
  getFunnelState, // Get funnel state
  trackFunnelStep, // Track individual funnel step

  // Feature usage
  trackFeatureUsage, // Track feature usage

  // Subscription tracking
  trackSubscriptionStarted,
  trackSubscriptionUpgraded,
  trackSubscriptionDowngraded,
  trackSubscriptionCanceled,
  trackSubscriptionPaused,
  trackSubscriptionReactivated,
  trackTrialStarted,
  trackTrialConverted,
  trackTrialExpired,
  trackPaymentFailed,
  trackPaymentSucceeded,
  getSubscriptionData,
  calculateChurnRisk,
} = 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

You call tracker methods → Events are sent to backend
Events stored in database with metadata (step_index, timing, properties)
Backend analyzes events → Calculates funnel statistics
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)

🧪 A/B Testing

Full-featured experimentation platform with React hooks and components for running A/B tests and feature flags.

Setup

import { MentiqAnalyticsProvider } from "mentiq-sdk";

<MentiqAnalyticsProvider
  config={{
    apiKey: "your-api-key",
    projectId: "your-project-id",
    enableABTesting: true, // Enable A/B testing
  }}
>
  <App />
</MentiqAnalyticsProvider>;

A/B Testing Hooks

useExperiment()

Get experiment assignment for a user.

import { useExperiment } from "mentiq-sdk";

function MyComponent() {
  const { assignment, loading, error, variantKey, trackConversion } =
    useExperiment("button-color-test");

  if (loading) return <div>Loading...</div>;
  if (error) return <div>Error loading experiment</div>;

  return (
    <button
      style={{ backgroundColor: variantKey === "red" ? "red" : "blue" }}
      onClick={() => trackConversion("button_click")}
    >
      Click Me
    </button>
  );
}

useVariant()

Check if a specific variant is enabled.

import { useVariant } from "mentiq-sdk";

function Feature() {
  const { isEnabled, loading } = useVariant("new-feature", "variant-a");

  if (loading) return null;

  return isEnabled ? <NewFeature /> : <OldFeature />;
}

useVariantValue()

Get different values based on variant assignment.

import { useVariantValue } from "mentiq-sdk";

function PricingPage() {
  const { value, loading, variant } = useVariantValue(
    "pricing-test",
    29.99, // Control value
    {
      "price-high": 39.99,
      "price-low": 19.99,
    }
  );

  return <div>Price: ${value}/month</div>;
}

useConversionTracking()

Track conversions for experiments.

import { useConversionTracking } from "mentiq-sdk";

function CheckoutButton() {
  const { trackConversion } = useConversionTracking();

  const handleCheckout = () => {
    trackConversion({
      experimentId: "checkout-flow-test",
      eventName: "purchase_completed",
      eventValue: 99.99,
      properties: { plan: "premium" },
    });
  };

  return <button onClick={handleCheckout}>Complete Purchase</button>;
}

A/B Testing Components

`<Variants>` - Render Different Content Per Variant

import { Variants } from "mentiq-sdk";

<Variants
  experimentKey="hero-test"
  variants={{
    control: <HeroV1 />,
    "variant-a": <HeroV2 />,
    "variant-b": <HeroV3 />,
  }}
  fallback={<DefaultHero />}
/>;

`<Variant>` - Show Content for Specific Variant

import { Variant } from "mentiq-sdk";

<Variant experimentKey="feature-flag" variantKey="new-ui">
  <NewDashboard />
</Variant>;

`<FeatureFlag>` - Feature Flags

import { FeatureFlag } from "mentiq-sdk";

<FeatureFlag experimentKey="beta-feature" fallback={<ComingSoon />}>
  <BetaFeature />
</FeatureFlag>;

`<ABTestButton>` - Test Different Button Variants

import { ABTestButton } from "mentiq-sdk";

<ABTestButton
  experimentKey="cta-button"
  variants={{
    control: { text: "Sign Up", style: { backgroundColor: "blue" } },
    "variant-a": { text: "Get Started Free", style: { backgroundColor: "green" } },
    "variant-b": { text: "Start Free Trial", style: { backgroundColor: "purple" } },
  }}
  onClick={handleSignup}
  onConversion={() => console.log("Conversion!")}
/>;

`<ABTestText>` - Test Different Copy

import { ABTestText } from "mentiq-sdk";

<h1>
  <ABTestText
    experimentKey="headline-test"
    variants={{
      control: "Welcome to Our Platform",
      "variant-a": "Build Better Products Faster",
      "variant-b": "Ship Features Users Love",
    }}
  />
</h1>;

All A/B Testing Hooks

// Get experiment assignment
const { assignment, loading, error, variantKey, trackConversion } =
  useExperiment("experiment-key");

// Check if specific variant is enabled
const { isEnabled, loading, error } = useVariant("experiment-key", "variant-a");

// Get variant-based value
const { value, loading, variant, isControl } = useVariantValue(
  "experiment-key",
  controlValue,
  variantValues
);

// Track conversions
const { trackConversion } = useConversionTracking();

// Get all active experiments
const { activeVariants, loading, count } = useActiveExperiments();

// Get experiment metadata
const { experiment, loading, isRunning, variants } =
  useExperimentInfo("experiment-key");

// Run variant-specific code
useVariantRunner("experiment-key", {
  control: () => console.log("Control"),
  "variant-a": () => console.log("Variant A"),
});

💳 Subscription Tracking

Track subscription lifecycle events, revenue metrics, and churn risk with automatic provider detection for Stripe, Paddle, and Chargebee.

Features

🔍 Auto-Detection: Automatically detect subscription data from Stripe, Paddle, or Chargebee
📊 Revenue Tracking: Track MRR, ARR, upgrades, downgrades, and cancellations
⚠️ Churn Prediction: Real-time churn risk scoring and alerts
🎯 Lifecycle Events: Track trials, conversions, payments, and more

Subscription Hooks

useSubscriptionTracking()

Access subscription tracking methods.

import { useSubscriptionTracking } from "mentiq-sdk";

function SubscriptionManager() {
  const {
    trackSubscriptionStarted,
    trackSubscriptionUpgraded,
    trackSubscriptionCanceled,
    trackTrialStarted,
    trackPaymentFailed,
  } = useSubscriptionTracking();

  const handleUpgrade = (plan) => {
    trackSubscriptionUpgraded({
      plan_id: plan.id,
      plan_name: plan.name,
      mrr: plan.price,
      billing_interval: "month",
      status: "active",
      previous_plan: "basic",
    });
  };

  return <button onClick={() => handleUpgrade(premiumPlan)}>Upgrade</button>;
}

useChurnRisk()

Monitor churn risk in real-time.

import { useChurnRisk } from "mentiq-sdk";

function ChurnMonitor() {
  const { churnRisk, isHighRisk, isCriticalRisk, refresh } = useChurnRisk({
    refreshInterval: 60000, // 1 minute
    onHighRisk: (risk) => console.log("High churn risk detected!", risk),
    onCriticalRisk: (risk) => alert("Critical churn risk!"),
  });

  return (
    <div>
      {churnRisk && (
        <div>
          <p>Churn Risk Score: {churnRisk.risk_score}/100</p>
          <p>Risk Category: {churnRisk.risk_category}</p>
          {isCriticalRisk && <p>⚠️ Action required to prevent churn!</p>}
        </div>
      )}
    </div>
  );
}

useSubscriptionData()

Get current subscription information.

import { useSubscriptionData } from "mentiq-sdk";

function SubscriptionBadge() {
  const { subscription, isPaidUser, isTrialing, isCanceled, refresh } =
    useSubscriptionData();

  return (
    <div>
      {isPaidUser && <span>Premium User</span>}
      {isTrialing && <span>Trial: {subscription?.trial_end}</span>}
      {isCanceled && <span>Subscription Canceled</span>}
    </div>
  );
}

useSubscriptionAutoDetect()

Automatically detect subscription from payment providers.

import { useSubscriptionAutoDetect } from "mentiq-sdk";

function AutoDetectSubscription() {
  const { detect, isDetecting, result } = useSubscriptionAutoDetect();

  useEffect(() => {
    detect(); // Auto-detect Stripe/Paddle/Chargebee
  }, []);

  return (
    <div>
      {result?.detected && (
        <p>
          Found {result.provider} subscription (confidence: {result.confidence}%)
        </p>
      )}
    </div>
  );
}

Subscription Components

`<SubscriptionTracker>` - Auto-track Changes

import { SubscriptionTracker } from "mentiq-sdk";

<SubscriptionTracker subscription={userSubscription} trackChanges={true}>
  <App />
</SubscriptionTracker>;

`<ChurnRiskMonitor>` - Display Churn Warnings

import { ChurnRiskMonitor } from "mentiq-sdk";

<ChurnRiskMonitor
  refreshInterval={60000}
  showWarning={true}
  onCriticalRisk={(risk) => sendAlert(risk)}
>
  <Dashboard />
</ChurnRiskMonitor>;

`<ChurnRiskBadge>` - Show Risk Level

import { ChurnRiskBadge } from "mentiq-sdk";

<ChurnRiskBadge refreshInterval={60000} />;
// Displays: HIGH RISK (85/100)

`<SubscriptionMetric>` - Display Metrics

import { SubscriptionMetric } from "mentiq-sdk";

<div>
  <SubscriptionMetric metric="mrr" prefix="MRR: " />
  <SubscriptionMetric metric="plan" />
  <SubscriptionMetric metric="status" />
</div>;

`<ConditionalRender>` - Conditional UI Based on Subscription

import { ConditionalRender } from "mentiq-sdk";

<ConditionalRender showFor="paid" fallback={<UpgradePrompt />}>
  <PremiumFeature />
</ConditionalRender>;

Subscription Methods

// Lifecycle events
trackSubscriptionStarted(properties);
trackSubscriptionUpgraded(properties);
trackSubscriptionDowngraded(properties);
trackSubscriptionCanceled(properties);
trackSubscriptionPaused(properties);
trackSubscriptionReactivated(properties);

// Trial events
trackTrialStarted(properties);
trackTrialConverted(properties);
trackTrialExpired(properties);

// Payment events
trackPaymentSucceeded(properties);
trackPaymentFailed(properties);

// Get data
const subscriptionData = getSubscriptionData();
const churnRisk = calculateChurnRisk();

Auto-Detection

The SDK can automatically detect subscription data from these providers:

Stripe

Detects Stripe object in window
Reads subscription data from localStorage
Extracts customer ID, plan, MRR/ARR, trial info

Paddle

Detects Paddle object in window
Reads Paddle subscription data
Handles Paddle-specific field names

Chargebee

Detects Chargebee object in window
Reads subscription data from Chargebee storage
Maps Chargebee billing periods

import { autoDetectSubscription } from "mentiq-sdk";

const detection = autoDetectSubscription();
if (detection.detected) {
  console.log(`Found ${detection.provider} with ${detection.confidence}% confidence`);
  console.log(detection.subscription); // Full subscription object
}

📈 Funnel Tracking

Track multi-step conversion funnels beyond onboarding.

Basic Usage

import { useMentiqAnalytics } from "mentiq-sdk";

function CheckoutFlow() {
  const { analytics } = useMentiqAnalytics();

  // Start funnel
  const startCheckout = () => {
    analytics.startFunnel("checkout", {
      cart_value: 99.99,
      items_count: 3,
    });
  };

  // Advance through steps
  const completeShipping = () => {
    analytics.advanceFunnel("checkout", "shipping_info", {
      shipping_method: "express",
    });
  };

  const completePayment = () => {
    analytics.advanceFunnel("checkout", "payment_info", {
      payment_method: "credit_card",
    });
  };

  // Complete funnel
  const completeOrder = () => {
    analytics.completeFunnel("checkout", {
      order_id: "ORD-123",
      total: 99.99,
    });
  };

  // Or abandon
  const abandonCheckout = () => {
    analytics.abandonFunnel("checkout", "user_cancelled");
  };

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

Funnel Methods

// Start a funnel
analytics.startFunnel("funnel-name", properties);

// Advance to next step
analytics.advanceFunnel("funnel-name", "step-name", properties);

// Complete funnel
analytics.completeFunnel("funnel-name", properties);

// Abandon funnel
analytics.abandonFunnel("funnel-name", "reason", properties);

// Get funnel state
const state = analytics.getFunnelState("funnel-name");

// Track individual step (alternative approach)
analytics.trackFunnelStep("funnel-name", "step-name", stepIndex, properties);

Use Cases

E-commerce: Cart → Shipping → Payment → Confirmation
Sign-up: Email → Verification → Profile → Preferences
Booking: Search → Select → Details → Payment
Application: Form → Documents → Review → Submit

🎯 Feature Usage & Engagement

Track Feature Usage

import { useMentiqAnalytics } from "mentiq-sdk";

function FeatureButton() {
  const { analytics } = useMentiqAnalytics();

  const handleFeatureUse = () => {
    analytics.trackFeatureUsage("export-pdf", {
      format: "pdf",
      pages: 10,
      premium_feature: true,
    });
  };

  return <button onClick={handleFeatureUse}>Export PDF</button>;
}

Calculate Engagement Score

const { analytics } = useMentiqAnalytics();

// Get real-time engagement score
const score = analytics.calculateEngagementScore();
console.log(`User engagement: ${score}/100`);

The engagement score is calculated based on:

Session duration
Page views
Click interactions
Scroll depth
Feature usage
Time since last activity

🔄 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

Optimized Provider (Recommended)

Use MentiqAnalyticsProvider for better SSR support and performance:

// app/layout.tsx (App Router)
import { MentiqAnalyticsProvider } from "mentiq-sdk";

export default function RootLayout({ children }) {
  return (
    <html>
      <body>
        <MentiqAnalyticsProvider
          config={{
            apiKey: "your-key",
            projectId: "your-project-id",
            enableABTesting: true,
            enableSessionRecording: true,
          }}
        >
          {children}
        </MentiqAnalyticsProvider>
      </body>
    </html>
  );
}

Using the Hook

import { useMentiqAnalytics } from "mentiq-sdk";

function MyComponent() {
  const { analytics, isReady } = useMentiqAnalytics();

  const handleClick = () => {
    if (isReady) {
      analytics.track("button_clicked");
    }
  };

  return <button onClick={handleClick}>Track Me</button>;
}

Higher-Order Component

import { withMentiqAnalytics } from "mentiq-sdk";

function MyComponent({ analytics }) {
  return <button onClick={() => analytics.track("event")}>Click</button>;
}

export default withMentiqAnalytics(MyComponent);

Pages Router (pages/)

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

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

📦 Vanilla JavaScript (Non-React)

Use MentiQ SDK in vanilla JavaScript applications without React.

Installation & Setup

npm install mentiq-sdk

import { init, track, page, identify, flush } from "mentiq-sdk";

// Initialize the SDK
const analytics = init({
  apiKey: "your-api-key",
  projectId: "your-project-id",
  endpoint: "https://api.mentiq.com",
  enableHeatmapTracking: true,
  enableSessionRecording: true,
});

// Track events
track("button_clicked", {
  button_id: "signup",
  location: "hero",
});

// Track page views
page({
  title: "Home Page",
  url: window.location.href,
});

// Identify users
identify("user-123", {
  name: "John Doe",
  email: "[email protected]",
  plan: "premium",
});

// Flush events immediately
flush();

All Available Methods

import {
  init,
  track,
  page,
  identify,
  alias,
  reset,
  flush,
  getInstance,
  // Session recording
  startRecording,
  stopRecording,
  pauseRecording,
  resumeRecording,
  isRecordingActive,
  // Funnel tracking
  startFunnel,
  advanceFunnel,
  completeFunnel,
  abandonFunnel,
  getFunnelState,
  trackFunnelStep,
  // Feature tracking
  trackFeatureUsage,
  // Subscription tracking
  trackSubscriptionStarted,
  trackSubscriptionUpgraded,
  trackSubscriptionDowngraded,
  trackSubscriptionCanceled,
  trackTrialStarted,
  trackTrialConverted,
  trackPaymentFailed,
  trackPaymentSucceeded,
  getSubscriptionData,
  calculateChurnRisk,
  // Engagement
  getActiveSession,
  calculateEngagementScore,
} from "mentiq-sdk";

// Initialize
init({ apiKey: "key", projectId: "project" });

// Track events
track("purchase", { amount: 99.99, product: "Premium" });
page({ title: "Pricing Page" });
identify("user-456", { email: "[email protected]" });
alias("new-id", "old-id"); // Merge user identities

// Session recording
startRecording();
stopRecording();
pauseRecording();
resumeRecording();
const isRecording = isRecordingActive();

// Funnel tracking
startFunnel("checkout", { cart_value: 199.99 });
advanceFunnel("checkout", "shipping");
completeFunnel("checkout", { order_id: "ORD-123" });
abandonFunnel("checkout", "user_cancelled");

// Feature usage
trackFeatureUsage("export-report", { format: "pdf" });

// Subscription tracking
trackSubscriptionStarted({
  plan_id: "premium",
  mrr: 2999,
  status: "active",
});

trackSubscriptionUpgraded({
  plan_id: "enterprise",
  mrr: 9999,
  previous_plan: "premium",
});

trackPaymentSucceeded({
  amount: 2999,
  currency: "usd",
});

// Get data
const subscription = getSubscriptionData();
const churnRisk = calculateChurnRisk();
const engagement = calculateEngagementScore();

// Utility
reset(); // Clear user data
flush(); // Send queued events immediately
const instance = getInstance(); // Get Analytics instance

HTML/CDN Usage

<!DOCTYPE html>
<html>
  <head>
    <script type="module">
      import {
        init,
        track,
        identify,
      } from "https://cdn.jsdelivr.net/npm/mentiq-sdk@latest/+esm";

      // Initialize
      init({
        apiKey: "your-api-key",
        projectId: "your-project-id",
      });

      // Track page view
      track("page_view", {
        path: window.location.pathname,
      });

      // Button click tracking
      document
        .getElementById("signup-btn")
        .addEventListener("click", function () {
          track("signup_clicked");
        });
    </script>
  </head>
  <body>
    <button id="signup-btn">Sign Up</button>
  </body>
</html>

Other Frameworks

The vanilla JavaScript API can be integrated with other frameworks like Vue, Angular, Svelte, etc. Simply use the init() function and standalone methods in your framework's service/plugin pattern.

📊 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 <MentiqAnalyticsProvider> (recommended) or <AnalyticsProvider>
[ ] Add your API key and project ID
[ ] Verify events in your dashboard

A/B Testing Setup

[ ] Enable enableABTesting: true in config
[ ] Create experiments in dashboard
[ ] Use useExperiment() hook or <Variants> component
[ ] Track conversions with trackConversion()
[ ] Monitor experiment results

Subscription Tracking Setup

[ ] Add subscription hooks: useSubscriptionTracking()
[ ] Track lifecycle events (started, upgraded, canceled, etc.)
[ ] Enable auto-detection for Stripe/Paddle/Chargebee (optional)
[ ] Use useChurnRisk() for churn monitoring
[ ] Display subscription metrics with components

Funnel Tracking Setup

[ ] Identify your conversion funnels
[ ] Use startFunnel() → advanceFunnel() → completeFunnel()
[ ] Track abandonment with abandonFunnel()
[ ] View funnel analytics in 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

Framework-Specific Setup

[ ] Next.js: Use MentiqAnalyticsProvider in layout
[ ] Vanilla JS: Use init() and standalone methods
[ ] Other Frameworks: Integrate using vanilla JS API

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.

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

MentiQ Analytics SDK

🌟 Features

Core Analytics

Advanced Features

Technical Features

📦 Installation

🚀 Quick Start (One File Setup)

Mentiq Props

Advanced Setup

Using Hooks

⚙️ Configuration

🎣 Core Hooks

useAnalytics()

useSessionTracking()

useErrorTracking()

usePerformanceTracking()

🧩 Components

TrackView - Element Visibility Tracking

HeatmapTracker - User Interaction Tracking

PerformanceMonitor - Component Performance

AnalyticsErrorBoundary - Error Tracking

TrackForm - Form Analytics

🎯 Onboarding Tracking

⚠️ Important: Not Automatic!

Basic Usage

Onboarding Tracker API

How It Works

Events Sent

Dashboard Analytics

Examples

🧪 A/B Testing

Setup

A/B Testing Hooks

useExperiment()

useVariant()

useVariantValue()

useConversionTracking()

A/B Testing Components

<Variants> - Render Different Content Per Variant

<Variant> - Show Content for Specific Variant

<FeatureFlag> - Feature Flags

<ABTestButton> - Test Different Button Variants

<ABTestText> - Test Different Copy

All A/B Testing Hooks

💳 Subscription Tracking

Features

Subscription Hooks

useSubscriptionTracking()

useChurnRisk()

useSubscriptionData()

useSubscriptionAutoDetect()

Subscription Components

<SubscriptionTracker> - Auto-track Changes

<ChurnRiskMonitor> - Display Churn Warnings

<ChurnRiskBadge> - Show Risk Level

<SubscriptionMetric> - Display Metrics

<ConditionalRender> - Conditional UI Based on Subscription

Subscription Methods

Auto-Detection

📈 Funnel Tracking

Basic Usage

Funnel Methods

Use Cases

🎯 Feature Usage & Engagement

Track Feature Usage

Calculate Engagement Score

🔄 Event Queuing & Batching

🚨 Error Handling

Automatic Error Tracking

Manual Error Tracking

⚡ Performance Monitoring

Core Web Vitals

Custom Performance Metrics

🎥 Session Recording

`<Variants>` - Render Different Content Per Variant

`<Variant>` - Show Content for Specific Variant

`<FeatureFlag>` - Feature Flags

`<ABTestButton>` - Test Different Button Variants

`<ABTestText>` - Test Different Copy

`<SubscriptionTracker>` - Auto-track Changes

`<ChurnRiskMonitor>` - Display Churn Warnings

`<ChurnRiskBadge>` - Show Risk Level

`<SubscriptionMetric>` - Display Metrics

`<ConditionalRender>` - Conditional UI Based on Subscription