Installation

Install the PRIV SDK in your project for privacy-first analytics tracking.

Package Managers

Install via your preferred package manager:

npm install @priv/sdk

CDN / UMD Script Tag

CDN/UMD distribution is planned for a future release. Currently, use the npm package with a bundler (webpack, Vite, esbuild, etc.).

Browser vs Node.js Compatibility

Environment	Support	Notes
Modern Browsers	Full	Chrome 90+, Firefox 88+, Safari 14+, Edge 90+
Node.js	Partial	Requires fetch polyfill for Node 18
React Native	Planned	Coming in v2.0
Web Workers	Full	Can be used in service workers

The SDK uses standard Web APIs:

fetch for HTTP requests
localStorage for persistence
crypto.getRandomValues() for ID generation

For Node.js environments (SSR), the SDK gracefully degrades when browser APIs are unavailable.

Bundle Size

The SDK is optimized for minimal footprint with zero dependencies:

Build	Size
Minified	~4.5 KB
Gzipped	< 5 KB

This makes it one of the smallest analytics SDKs available, with no impact on your Core Web Vitals.

Tree-Shaking Support

For maximum bundle optimization, import only what you need:

// Import specific functions (recommended for smallest bundle)
import { init, track, identify, page } from '@priv/sdk';

// Or import the full SDK singleton
import { priv } from '@priv/sdk';

// Types only (zero runtime cost)
import type { PrivConfig, EventProperties, UserTraits } from '@priv/sdk';

TypeScript Support

The SDK includes TypeScript definitions out of the box. No additional @types package needed.

import { priv } from '@priv/sdk';
import type { PrivConfig, EventProperties } from '@priv/sdk';

const config: PrivConfig = {
  apiKey: 'pk_your_api_key',
  endpoint: 'https://api.privlabs.io',
  debug: process.env.NODE_ENV === 'development',
};

priv.init(config);

// Full type safety for events
const properties: EventProperties = {
  buttonId: 'signup',
  variant: 'primary',
  position: 1,
};

priv.track('button_click', properties);

Quick Start

After installation, initialize the SDK:

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

// 1. Initialize with your API key
priv.init({
  apiKey: 'pk_your_api_key',
  endpoint: 'https://api.privlabs.io',
});

// 2. Set consent (required for GDPR compliance)
priv.setConsent(true);

// 3. Identify the user (optional)
priv.identify('user_123', {
  plan: 'pro',
  company: 'Acme Inc',
});

// 4. Track events
priv.track('signup_completed', {
  method: 'email',
  referrer: 'google',
});

Verification

Verify the SDK is working correctly:

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

priv.init({
  apiKey: 'pk_your_api_key',
  endpoint: 'https://api.privlabs.io',
  debug: true, // Enable console logging
});

// Check if tracking is active
console.log('Tracking active:', priv.isTracking());

// Get the anonymous ID
console.log('Anonymous ID:', priv.getAnonId());

// Test a track call (will log to console in debug mode)
priv.track('sdk_test', { status: 'working' });

Next Steps

Configuration - Configure batching, auto-tracking, and more
API Reference - Full API documentation
React Integration - Use with React and Next.js

Installation

On this page