Configure the PRIV SDK with options for batching, auto-tracking, debugging, and GDPR compliance.

Configuration

Customize SDK behavior with comprehensive configuration options.

Basic Configuration

import { priv } from '@priv/sdk';

priv.init({
  apiKey: 'pk_your_api_key',
  endpoint: 'https://api.priv.io/v1',
});

Complete PrivConfig Interface

interface PrivConfig {
  /** API key for authentication (format: pk_xxx) */
  apiKey: string;

  /** Analytics endpoint URL */
  endpoint: string;

  /** Enable debug logging (default: false) */
  debug?: boolean;

  /** Flush interval in milliseconds (default: 5000) */
  flushInterval?: number;

  /** Max events before auto-flush (default: 10) */
  flushAt?: number;

  /** Auto-track page views (default: true) */
  autoTrackPageViews?: boolean;

  /** Auto-track clicks (default: false) */
  autoTrackClicks?: boolean;

  /** Auto-track scroll depth (default: false) */
  autoTrackScroll?: boolean;
}

Configuration Options

`apiKey` (required)

Your PRIV API key. Get this from the PRIV Dashboard.

priv.init({
  apiKey: 'pk_live_xxxxx', // Production key
  endpoint: 'https://api.priv.io/v1',
});

API keys use the format:

pk_live_* - Production keys
pk_test_* - Test/development keys

`endpoint` (required)

The analytics API endpoint URL.

priv.init({
  apiKey: 'pk_your_key',
  endpoint: 'https://api.priv.io/v1', // Default PRIV endpoint
});

For self-hosted deployments:

priv.init({
  apiKey: 'pk_your_key',
  endpoint: 'https://analytics.yourdomain.com/v1',
});

`debug`

Enable debug mode. Logs all events to the console.

priv.init({
  apiKey: 'pk_your_key',
  endpoint: 'https://api.priv.io/v1',
  debug: process.env.NODE_ENV === 'development',
});

Default: false

When enabled, you'll see logs like:

[PRIV] Initialized with config: {...}
[PRIV] Track: button_click {...}
[PRIV] Flushing 5 events...
[PRIV] Flush complete

`flushInterval`

How often to send batched events to the server (in milliseconds).

priv.init({
  apiKey: 'pk_your_key',
  endpoint: 'https://api.priv.io/v1',
  flushInterval: 5000, // Flush every 5 seconds
});

Default: 5000 (5 seconds)

Lower values = more real-time data but more network requests. Higher values = better battery/network efficiency but delayed data.

`flushAt`

Number of events to batch before automatically flushing.

priv.init({
  apiKey: 'pk_your_key',
  endpoint: 'https://api.priv.io/v1',
  flushAt: 10, // Flush when 10 events are queued
});

Default: 10

Events are sent when either flushInterval expires OR flushAt count is reached, whichever comes first.

`autoTrackPageViews`

Automatically track page views on route changes.

priv.init({
  apiKey: 'pk_your_key',
  endpoint: 'https://api.priv.io/v1',
  autoTrackPageViews: true, // Auto-track page views
});

Default: true

When enabled, page views are automatically tracked on:

Initial page load
History API changes (pushState/replaceState)
Hash changes

Disable this if you want to manually control page view tracking:

priv.init({
  apiKey: 'pk_your_key',
  endpoint: 'https://api.priv.io/v1',
  autoTrackPageViews: false,
});

// Manually track page views
priv.page('Dashboard', { section: 'overview' });

`autoTrackClicks`

Automatically track all click events with element metadata.

priv.init({
  apiKey: 'pk_your_key',
  endpoint: 'https://api.priv.io/v1',
  autoTrackClicks: true,
});

Default: false

When enabled, click events include:

Element tag name
Element ID and classes
Button/link text
data-track-* attributes

`autoTrackScroll`

Automatically track scroll depth milestones.

priv.init({
  apiKey: 'pk_your_key',
  endpoint: 'https://api.priv.io/v1',
  autoTrackScroll: true,
});

Default: false

Tracks when users reach 25%, 50%, 75%, and 100% scroll depth on a page.

Environment-Based Configuration

Use environment variables for different configurations:

priv.init({
  apiKey: process.env.NEXT_PUBLIC_PRIV_API_KEY!,
  endpoint: process.env.NEXT_PUBLIC_PRIV_ENDPOINT ?? 'https://api.priv.io/v1',
  debug: process.env.NODE_ENV === 'development',
  autoTrackPageViews: true,
  autoTrackClicks: process.env.NODE_ENV === 'production',
  flushInterval: process.env.NODE_ENV === 'production' ? 5000 : 1000,
});

Recommended Configurations

Development

priv.init({
  apiKey: 'pk_test_xxxxx',
  endpoint: 'https://api.priv.io/v1',
  debug: true,
  flushInterval: 1000, // Faster for debugging
  flushAt: 1, // Send immediately
  autoTrackPageViews: true,
});

Production

priv.init({
  apiKey: 'pk_live_xxxxx',
  endpoint: 'https://api.priv.io/v1',
  debug: false,
  flushInterval: 5000,
  flushAt: 10,
  autoTrackPageViews: true,
  autoTrackClicks: true,
  autoTrackScroll: true,
});

High-Traffic Sites

priv.init({
  apiKey: 'pk_live_xxxxx',
  endpoint: 'https://api.priv.io/v1',
  flushInterval: 10000, // Less frequent flushes
  flushAt: 20, // Larger batches
  autoTrackPageViews: true,
  autoTrackClicks: false, // Reduce event volume
  autoTrackScroll: false,
});

The SDK is designed to be GDPR-compliant. No tracking occurs until consent is granted:

priv.init({
  apiKey: 'pk_your_key',
  endpoint: 'https://api.priv.io/v1',
});

// SDK is initialized but NOT tracking yet

// After user grants consent:
priv.setConsent(true);

// Now tracking is active
priv.track('consent_granted');

Check if tracking is active:

if (priv.isTracking()) {
  // User has consented and tracking is active
  priv.track('action_performed');
}

Next Steps

API Reference - Full method documentation
React Integration - React and Next.js setup

Configuration

On this page