Configuration

Configure the MentiQ Analytics SDK with custom settings for your application

Overview

The MentiQ Analytics SDK is initialized with an AnalyticsConfig object that controls its behavior, tracking features, and performance characteristics.

Basic Configuration

import { Analytics } from 'mentiq-sdk';

const analytics = new Analytics({
  apiKey: 'your-api-key',
  projectId: 'your-project-id',
});

Configuration Options

Required Parameters

apiKey · string · required

Your MentiQ API key for authentication

projectId · string · required

Your MentiQ project identifier

Endpoint Configuration

endpoint · string · default: "https://api.mentiq.io"

Custom API endpoint URL for self-hosted or regional deployments

User Identification

userId · string

Initial user ID to set on initialization. Can also be set later using identify()

Session Management

sessionTimeout · number · default: "1800000"

Session timeout in milliseconds. Default is 30 minutes (30 * 60 * 1000)

Event Batching

batchSize · number · default: "20"

Number of events to batch before automatic flush

flushInterval · number · default: "10000"

Interval in milliseconds to automatically flush events. Default is 10 seconds

maxQueueSize · number · default: "1000"

Maximum number of events to queue before dropping oldest events

Retry Configuration

retryAttempts · number · default: "3"

Number of times to retry failed event sends

retryDelay · number · default: "1000"

Initial delay in milliseconds before retry (uses exponential backoff)

Automatic Tracking

enableAutoPageTracking · boolean · default: "true"

Automatically track page views, including SPA navigation (pushState/replaceState)

enablePerformanceTracking · boolean · default: "false"

Automatically track page performance metrics (load time, FCP, LCP, etc.)

enableHeatmapTracking · boolean · default: "false"

Enable heatmap tracking for clicks, mouse movements, and scrolls

enableSessionRecording · boolean · default: "false"

Enable session recording functionality

enableErrorTracking · boolean · default: "false"

Automatically track JavaScript errors and unhandled promise rejections

A/B Testing

enableABTesting · boolean · default: "false"

Enable A/B testing features

abTestConfig · ABTestConfig

Additional A/B testing configuration options

Debugging

debug · boolean · default: "false"

Enable debug logging to console

Advanced Configuration Examples

Full-Featured Setup

const analytics = new Analytics({
  apiKey: 'your-api-key',
  projectId: 'your-project-id',
  endpoint: 'https://api.mentiq.io',
  debug: true,
  
  // User identification
  userId: 'user-123',
  
  // Session management
  sessionTimeout: 30 * 60 * 1000, // 30 minutes
  
  // Event batching
  batchSize: 20,
  flushInterval: 10000, // 10 seconds
  maxQueueSize: 1000,
  
  // Retry configuration
  retryAttempts: 3,
  retryDelay: 1000,
  
  // Automatic tracking
  enableAutoPageTracking: true,
  enablePerformanceTracking: true,
  enableHeatmapTracking: true,
  enableSessionRecording: false,
  enableErrorTracking: true,
  
  // A/B Testing
  enableABTesting: true,
  abTestConfig: {
    enableABTesting: true,
    assignmentCacheTTL: 5 * 60 * 1000, // 5 minutes
    autoTrackExposures: true,
  },
});

Minimal Configuration

const analytics = new Analytics({
  apiKey: 'your-api-key',
  projectId: 'your-project-id',
});

Performance-Optimized Configuration

const analytics = new Analytics({
  apiKey: 'your-api-key',
  projectId: 'your-project-id',
  
  // Larger batches, less frequent flushes
  batchSize: 50,
  flushInterval: 30000, // 30 seconds
  
  // Disable resource-intensive features
  enableHeatmapTracking: false,
  enableSessionRecording: false,
  enablePerformanceTracking: false,
});

Development Configuration

const analytics = new Analytics({
  apiKey: 'dev-api-key',
  projectId: 'dev-project',
  debug: true,
  
  // Smaller batches for faster feedback
  batchSize: 5,
  flushInterval: 2000, // 2 seconds
  
  // Enable all tracking for testing
  enableAutoPageTracking: true,
  enablePerformanceTracking: true,
  enableHeatmapTracking: true,
  enableErrorTracking: true,
});

Accessing Configuration

You can access the current configuration using the config property:

const apiKey = analytics.config.apiKey;
const debug = analytics.config.debug;

Runtime Updates

Most configuration options are set at initialization and cannot be changed at runtime. To change configuration, create a new Analytics instance:

// Destroy old instance
analytics.destroy();

// Create new instance with updated config
const analytics = new Analytics({
  apiKey: 'your-api-key',
  projectId: 'your-project-id',
  debug: false, // Updated configuration
});

Best Practices

Use environment variables for sensitive configuration like API keys:

const analytics = new Analytics({
  apiKey: process.env.MENTIQ_API_KEY,
  projectId: process.env.MENTIQ_PROJECT_ID,
});

Be cautious with enableHeatmapTracking and enableSessionRecording as they can generate large amounts of data and impact performance.

Enable debug mode during development to see detailed logs of SDK operations.