Basic Usage

Quick Setup

Get up and running with MentiQ Analytics in under 5 minutes.

Installation

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

Basic Configuration

Wrap your app with the MentiqAnalyticsProvider and configure your API credentials.

import React from "react";
import { MentiqAnalyticsProvider, useMentiqAnalytics } from "mentiq-sdk";

// Your component that uses analytics
function MyComponent() {
  const { track, page, identify } = useMentiqAnalytics();

  React.useEffect(() => {
    // Track page view
    page({ page: "home" });
  }, [page]);

  const handleButtonClick = () => {
    track("button_clicked", { button: "cta", location: "header" });
  };

  const handleUserSignup = () => {
    identify("user-123", {
      email: "user@example.com",
      plan: "pro",
    });
    track("user_signed_up", { method: "email" });
  };

  return (
    <div>
      <h1>My App</h1>
      <button onClick={handleButtonClick}>Click me (tracked)</button>
      <button onClick={handleUserSignup}>Sign Up (tracked)</button>
    </div>
  );
}

// Root App with MentiQ Analytics
function App() {
  return (
    <MentiqAnalyticsProvider
      config={{
        apiKey: "your-api-key",
        projectId: "your-project-id",
        endpoint: "https://analytics.yourapp.com/v1/events",
      }}
      loading={<div>Loading analytics...</div>}
    >
      <MyComponent />
    </MentiqAnalyticsProvider>
  );
}

export default App;

// app/layout.tsx
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,
            debug: process.env.NODE_ENV === "development",
            enableAutoPageTracking: true,
          }}
        >
          {children}
        </MentiqAnalyticsProvider>
      </body>
    </html>
  );
}

// pages/_app.tsx
import type { AppProps } from "next/app";
import { MentiqAnalyticsProvider } from "mentiq-sdk";

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!,
        endpoint: process.env.NEXT_PUBLIC_MENTIQ_ENDPOINT || "https://api.mentiq.io",
        debug: process.env.NODE_ENV === "development",
        enableAutoPageTracking: true,
        enableHeatmapTracking: true,
        batchSize: 10,
        flushInterval: 5000,
      }}
    >
      <Component {...pageProps} />
    </MentiqAnalyticsProvider>
  );
}

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

// Initialize MentiQ Analytics
const analytics = init({
  apiKey: "your-api-key",
  projectId: "your-project-id",
  debug: true,
});

// Track page view
page({ 
  title: "Home Page", 
  path: "/home" 
});

// Identify user
identify("user-123", {
  email: "user@example.com",
  plan: "premium",
});

// Track events
const button = document.getElementById("signup-btn");
button.addEventListener("click", () => {
  track("button_clicked", {
    button_id: "signup-btn",
    location: "header",
  });
});

Core Tracking Methods

Track Custom Events

Track any user action or event with custom properties.

import { useMentiqAnalytics } from "mentiq-sdk";

function MyComponent() {
  const { track } = useMentiqAnalytics();

  const handlePurchase = () => {
    track("purchase_completed", {
      product_id: "prod-123",
      amount: 29.99,
      currency: "USD",
      category: "subscription",
    });
  };

  const handleShare = () => {
    track("content_shared", {
      content_type: "article",
      share_method: "twitter",
    });
  };

  return (
    <div>
      <button onClick={handlePurchase}>Buy Now</button>
      <button onClick={handleShare}>Share</button>
    </div>
  );
}

Track Page Views

Automatically or manually track page navigation.

import { useMentiqAnalytics } from "mentiq-sdk";
import { useEffect } from "react";

function ProductPage({ productId }) {
  const { page } = useMentiqAnalytics();

  useEffect(() => {
    page({
      title: "Product Details",
      path: `/products/${productId}`,
      url: window.location.href,
      referrer: document.referrer,
    });
  }, [page, productId]);

  return <div>Product Page</div>;
}

Identify Users

Associate events with specific users and their traits.

import { useMentiqAnalytics } from "mentiq-sdk";

function LoginSuccess({ user }) {
  const { identify } = useMentiqAnalytics();

  useEffect(() => {
    identify(user.id, {
      email: user.email,
      name: user.name,
      plan: user.subscription.plan,
      signup_date: user.createdAt,
      company: user.company,
    });
  }, [identify, user]);

  return <div>Welcome, {user.name}!</div>;
}

Component-Based Tracking

Use declarative components for automatic tracking.

TrackClick Component

Automatically track clicks on any element.

import { TrackClick } from "mentiq-sdk";

function CallToAction() {
  return (
    <TrackClick 
      event="cta_clicked" 
      properties={{ location: "hero", variant: "primary" }}
    >
      <button className="btn-primary">
        Start Free Trial
      </button>
    </TrackClick>
  );
}

TrackView Component

Track when elements become visible on screen.

import { TrackView } from "mentiq-sdk";

function FeatureSection() {
  return (
    <TrackView
      event="feature_section_viewed"
      properties={{ section: "pricing" }}
      threshold={0.5}  // 50% visible
      delay={1000}     // for 1 second
    >
      <div className="pricing-section">
        <h2>Our Pricing Plans</h2>
        {/* Pricing content */}
      </div>
    </TrackView>
  );
}

Complete Dashboard Example

A full example showing multiple tracking methods together.

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

function App() {
  return (
    <MentiqAnalyticsProvider
      config={{
        apiKey: "your-api-key-here",
        debug: true,
        enableAutoPageTracking: true,
      }}
      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 style={{ padding: "20px" }}>
      <h1>MentiQ Analytics Demo</h1>

      {!user ? (
        <div>
          <h2>Welcome! Please log in to continue.</h2>
          <button onClick={handleLogin}>Demo Login</button>
        </div>
      ) : (
        <div>
          <h2>Welcome back, {user}!</h2>

          <div style={{ display: "grid", gap: "20px" }}>
            <TrackView
              event="feature_card_viewed"
              properties={{ feature: "analytics" }}
            >
              <div className="card">
                <h3>Analytics Dashboard</h3>
                <p>View your analytics data and insights.</p>
                <TrackClick
                  event="feature_accessed"
                  properties={{ feature: "analytics" }}
                >
                  <button onClick={() => handleFeatureClick("analytics")}>
                    View Analytics
                  </button>
                </TrackClick>
              </div>
            </TrackView>

            <TrackView
              event="feature_card_viewed"
              properties={{ feature: "reports" }}
            >
              <div className="card">
                <h3>Reports</h3>
                <p>Generate and download reports.</p>
                <TrackClick
                  event="feature_accessed"
                  properties={{ feature: "reports" }}
                >
                  <button onClick={() => handleFeatureClick("reports")}>
                    View Reports
                  </button>
                </TrackClick>
              </div>
            </TrackView>
          </div>
        </div>
      )}
    </div>
  );
}

export default App;

Configuration Options

string

required

Your MentiQ Analytics API key from the dashboard

string

required

Your project ID from the dashboard

string

Custom analytics endpoint (defaults to MentiQ cloud)

boolean

default:"false"

Enable debug logging for development

boolean

default:"true"

Automatically track page views on route changes

boolean

default:"false"

Track clicks, hovers, and scrolls for heatmap visualization

number

default:"20"

Number of events to batch before sending

number

default:"10000"

Interval in milliseconds to flush events (10 seconds)

Environment Variables

For Next.js projects, create a .env.local file:

NEXT_PUBLIC_MENTIQ_API_KEY=your-api-key-here
NEXT_PUBLIC_MENTIQ_PROJECT_ID=your-project-id-here
NEXT_PUBLIC_MENTIQ_ENDPOINT=https://api.mentiq.io

Next Steps

E-commerce Tracking

Track products, carts, and purchases

SaaS Metrics

Monitor subscriptions and user engagement

Content Engagement

Track reading time and scroll depth

API Reference

Explore all available methods

Get Started

Core Concepts

React Integration

Features

Guides

Examples

Quick Setup

Installation

Basic Configuration

Core Tracking Methods

Track Custom Events

Track Page Views

Identify Users

Component-Based Tracking

TrackClick Component

TrackView Component

Complete Dashboard Example

Configuration Options

Environment Variables

Next Steps

E-commerce Tracking

SaaS Metrics

Content Engagement

API Reference

​Quick Setup

​Installation

​Basic Configuration

​Core Tracking Methods

​Track Custom Events

​Track Page Views

​Identify Users

​Component-Based Tracking

​TrackClick Component

​TrackView Component

​Complete Dashboard Example

​Configuration Options

​Environment Variables

​Next Steps

E-commerce Tracking

SaaS Metrics

Content Engagement

API Reference

Quick Setup

Installation

Basic Configuration

Core Tracking Methods

Track Custom Events

Track Page Views

Identify Users

Component-Based Tracking

TrackClick Component

TrackView Component

Complete Dashboard Example

Configuration Options

Environment Variables

Next Steps