Quickstart guide

This guide will help you set up MentiQ Analytics SDK and track your first event.

Prerequisites

Before starting, make sure you have:

A React or Next.js application (React 16.8+)
Your MentiQ API key and project ID
The SDK installed (see Installation)

Basic setup

Wrap your app with the provider

Import MentiqAnalyticsProvider and wrap your app at the root level:

app.tsx

import { MentiqAnalyticsProvider } from 'mentiq-sdk';

function App() {
  return (
    <MentiqAnalyticsProvider
      config={{
        apiKey: "your-api-key",
        projectId: "your-project-id",
        enableAutoPageTracking: true,
      }}
    >
      <YourApp />
    </MentiqAnalyticsProvider>
  );
}

Replace your-api-key and your-project-id with your actual credentials from the MentiQ dashboard.

Use the analytics hook

In any component, use the useMentiqAnalytics hook to access tracking methods:

dashboard.tsx

import { useMentiqAnalytics } from 'mentiq-sdk';

function Dashboard() {
  const { track, identify } = useMentiqAnalytics();

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

  return (
    <button onClick={handleButtonClick}>
      Track Me!
    </button>
  );
}

Identify users

When a user logs in, identify them to associate events with their account:

const { identify } = useMentiqAnalytics();

const handleLogin = (userId: string) => {
  identify(userId, {
    email: 'user@example.com',
    signup_date: new Date().toISOString(),
    plan: 'premium',
  });
};

Verify in your dashboard

Open your MentiQ dashboard and verify that events are being received. You should see:

Page view events (if enableAutoPageTracking is enabled)
Custom events from your track() calls
User identification data

Complete working example

Here’s a complete example showing authentication and event tracking:

import React, { useState } from 'react';
import {
  MentiqAnalyticsProvider,
  useMentiqAnalytics,
  TrackView,
  TrackClick,
} from 'mentiq-sdk';

function App() {
  return (
    <MentiqAnalyticsProvider
      config={{
        apiKey: "your-api-key",
        projectId: "your-project-id",
        enableAutoPageTracking: true,
        debug: true, // Enable debug mode during development
      }}
      loading={<div>Loading analytics...</div>}
    >
      <Dashboard />
    </MentiqAnalyticsProvider>
  );
}

function Dashboard() {
  const { track, identify } = useMentiqAnalytics();
  const [user, setUser] = useState<string | null>(null);

  const handleLogin = () => {
    const userId = "user_" + Math.random().toString(36).substr(2, 9);
    setUser(userId);

    // Identify the user
    identify(userId, {
      signup_date: new Date().toISOString(),
      plan: "free",
    });

    track("user_logged_in", {
      method: "demo",
    });
  };

  const handleFeatureClick = (feature: string) => {
    track("feature_clicked", {
      feature_name: feature,
      user_type: user ? "authenticated" : "anonymous",
    });
  };

  return (
    <div>
      <h1>My Application</h1>

      {!user ? (
        <button onClick={handleLogin}>Login</button>
      ) : (
        <div>
          <h2>Welcome back, {user}!</h2>

          <TrackView
            event="feature_card_viewed"
            properties={{ feature: "analytics" }}
          >
            <div className="feature-card">
              <h3>Analytics Dashboard</h3>
              <TrackClick
                event="feature_accessed"
                properties={{ feature: "analytics" }}
              >
                <button onClick={() => handleFeatureClick("analytics")}>
                  View Analytics
                </button>
              </TrackClick>
            </div>
          </TrackView>
        </div>
      )}
    </div>
  );
}

export default App;

Next.js setup

For Next.js applications, the setup differs slightly based on your router:

import { MentiqAnalyticsProvider } from 'mentiq-sdk';

export default function RootLayout({ children }) {
  return (
    <html>
      <body>
        <MentiqAnalyticsProvider
          config={{
            apiKey: process.env.NEXT_PUBLIC_MENTIQ_API_KEY!,
            projectId: process.env.NEXT_PUBLIC_MENTIQ_PROJECT_ID!,
            enableAutoPageTracking: true,
          }}
        >
          {children}
        </MentiqAnalyticsProvider>
      </body>
    </html>
  );
}

import { MentiqAnalyticsProvider } from 'mentiq-sdk';
import type { AppProps } from 'next/app';

export default function App({ Component, pageProps }: AppProps) {
  return (
    <MentiqAnalyticsProvider
      config={{
        apiKey: process.env.NEXT_PUBLIC_MENTIQ_API_KEY!,
        projectId: process.env.NEXT_PUBLIC_MENTIQ_PROJECT_ID!,
        enableAutoPageTracking: true,
      }}
    >
      <Component {...pageProps} />
    </MentiqAnalyticsProvider>
  );
}

Make sure to prefix your environment variables with NEXT_PUBLIC_ to expose them to the browser.

Configuration options

Here are the most common configuration options:

interface AnalyticsConfig {
  // Required
  apiKey: string;
  projectId: string;

  // Optional - Connection
  endpoint?: string; // Custom API endpoint
  debug?: boolean; // Enable console logging

  // Optional - Features
  enableAutoPageTracking?: boolean; // Default: true
  enablePerformanceTracking?: boolean; // Default: false
  enableHeatmapTracking?: boolean; // Default: false
  enableSessionRecording?: boolean; // Default: false
  enableErrorTracking?: boolean; // Default: false

  // Optional - Batching
  batchSize?: number; // Default: 20 events
  flushInterval?: number; // Default: 10000ms (10 seconds)
  maxQueueSize?: number; // Default: 1000 events

  // Optional - Retry Logic
  retryAttempts?: number; // Default: 3
  retryDelay?: number; // Default: 1000ms

  // Optional - Session
  sessionTimeout?: number; // Default: 1800000ms (30 minutes)
}

Using tracking components

MentiQ provides pre-built components for common tracking scenarios:

TrackView - Track element visibility

import { TrackView } from 'mentiq-sdk';

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

TrackClick - Track clicks

import { TrackClick } from 'mentiq-sdk';

<TrackClick
  event="cta_clicked"
  properties={{ location: "header" }}
>
  <button>Click Me</button>
</TrackClick>

TrackForm - Track form submissions

import { TrackForm } from 'mentiq-sdk';

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

Monitoring session data

Track real-time session metrics with the useSessionTracking hook:

import { useSessionTracking } from 'mentiq-sdk';

function SessionMonitor() {
  const {
    sessionId,
    isActive,
    duration,
    pageViews,
    clicks,
    scrollDepth,
  } = useSessionTracking();

  return (
    <div>
      <p>Session ID: {sessionId}</p>
      <p>Duration: {duration}ms</p>
      <p>Page Views: {pageViews}</p>
      <p>Scroll Depth: {scrollDepth}%</p>
    </div>
  );
}

Next steps

Now that you have basic tracking set up, explore more advanced features:

Session recording

Record and replay user sessions with privacy controls

Heatmap tracking

Visualize user interactions with click and scroll heatmaps

Error tracking

Automatically capture JavaScript errors and exceptions

Performance monitoring

Track Core Web Vitals and custom performance metrics

Get Started

Core Concepts

React Integration

Features

Guides

Examples

Quickstart

Quickstart guide

Prerequisites

Basic setup

Complete working example

Next.js setup

Configuration options

Using tracking components

TrackView - Track element visibility

TrackClick - Track clicks

TrackForm - Track form submissions

Monitoring session data

Next steps

Session recording

Heatmap tracking

Error tracking

Performance monitoring

​Quickstart guide

​Prerequisites

​Basic setup

​Complete working example

​Next.js setup

​Configuration options

​Using tracking components

​TrackView - Track element visibility

​TrackClick - Track clicks

​TrackForm - Track form submissions

​Monitoring session data

​Next steps

Session recording

Heatmap tracking

Error tracking

Performance monitoring

Quickstart guide

Prerequisites

Basic setup

Complete working example

Next.js setup

Configuration options

Using tracking components

TrackView - Track element visibility

TrackClick - Track clicks

TrackForm - Track form submissions

Monitoring session data

Next steps