Getting Started

Integrate PRIV analytics into your application in under 5 minutes.

Prerequisites

Node.js 18+
A PRIV API key (get one at priv.io/dashboard)

Quick Start

1. Install the SDK

npm install @priv/sdk

Or with other package managers:

pnpm add @priv/sdk
yarn add @priv/sdk

2. Initialize the SDK

import { Priv } from '@priv/sdk'

const priv = new Priv({
  apiKey: 'pk_live_xxxxxxxxxxxxx',
  // Optional configuration
  debug: process.env.NODE_ENV === 'development',
  batchSize: 10,
  flushInterval: 5000,
})

3. Track Your First Event

// Track a page view
priv.trackPageView()

// Track a custom event
priv.track('button_click', {
  button_id: 'signup',
  position: 'header',
})

That's it. Events will batch and send automatically.

API Key Setup

Get Your API Key

Create an account and generate API keys from your PRIV dashboard.

Environment Variables

Store your API key securely using environment variables.

Creating an API Key

Sign up or log in at priv.io
Navigate to Settings > API Keys
Click Create New Key
Copy your key (it won't be shown again)

Key Types

Type	Prefix	Use Case
Publishable	`pk_live_`	Client-side SDK integration
Secret	`sk_live_`	Server-side API calls
Test	`pk_test_`	Development and testing

Environment Configuration

# .env.local
NEXT_PUBLIC_PRIV_KEY=pk_live_xxxxxxxxxxxxx
PRIV_SECRET_KEY=sk_live_xxxxxxxxxxxxx

Security Note: Publishable keys (pk_) are safe to expose in client-side code. Never expose secret keys (sk_) in browsers.

Basic Tracking Examples

Page Views

// Automatic page view with metadata
priv.trackPageView()

// Custom page view with additional data
priv.trackPageView({
  title: 'Product Details',
  path: '/products/123',
  referrer: document.referrer,
})

Custom Events

// Simple event
priv.track('signup_started')

// Event with properties
priv.track('purchase_completed', {
  product_id: 'prod_123',
  amount: 99.99,
  currency: 'USD',
})

// Event with user context
priv.track('subscription_upgraded', {
  plan: 'pro',
  previous_plan: 'free',
  source: 'pricing_page',
})

User Identification

// Identify a user (after login)
priv.identify({
  userId: 'user_123',
  email: 'user@example.com',
  name: 'John Doe',
})

// Identify a Web3 wallet
priv.identifyWallet({
  address: '0x1234...abcd',
  chain: 'base',
  connector: 'metamask',
})

PRIV requires explicit user consent for data collection. The SDK provides built-in consent management.

import { Priv, ConsentStatus } from '@priv/sdk'

const priv = new Priv({
  apiKey: 'pk_live_xxxxxxxxxxxxx',
  // Don't track until consent is given
  autoTrack: false,
})

// Check current consent status
const status = priv.getConsentStatus()

if (status === ConsentStatus.PENDING) {
  // Show your consent UI
  showConsentBanner()
}

// When user grants consent
function onConsentGranted() {
  priv.setConsent({
    analytics: true,
    marketing: false,
    personalization: true,
  })

  // Start tracking
  priv.start()
}

// When user denies consent
function onConsentDenied() {
  priv.setConsent({
    analytics: false,
    marketing: false,
    personalization: false,
  })
}

Using the Compliance SDK

For GDPR/CCPA compliance with a pre-built consent banner:

npm install @priv/compliance-sdk

import { ComplianceBanner } from '@priv/compliance-sdk'

const banner = new ComplianceBanner({
  apiKey: 'pk_live_xxxxxxxxxxxxx',
  position: 'bottom',
  theme: 'dark',
  onConsent: (consent) => {
    console.log('User consent:', consent)
  },
})

banner.show()

Framework Integration

React

import { PrivProvider, usePriv } from '@priv/sdk/react'

function App() {
  return (
    <PrivProvider apiKey="pk_live_xxxxxxxxxxxxx">
      <YourApp />
    </PrivProvider>
  )
}

function SignupButton() {
  const { track } = usePriv()

  return (
    <button onClick={() => track('signup_click')}>
      Sign Up
    </button>
  )
}

Next.js (App Router)

// app/providers.tsx
'use client'

import { PrivProvider } from '@priv/sdk/react'

export function Providers({ children }: { children: React.ReactNode }) {
  return (
    <PrivProvider
      apiKey={process.env.NEXT_PUBLIC_PRIV_KEY!}
      debug={process.env.NODE_ENV === 'development'}
    >
      {children}
    </PrivProvider>
  )
}

// app/layout.tsx
import { Providers } from './providers'

export default function RootLayout({
  children
}: {
  children: React.ReactNode
}) {
  return (
    <html>
      <body>
        <Providers>{children}</Providers>
      </body>
    </html>
  )
}

Vue

// main.ts
import { createApp } from 'vue'
import { PrivPlugin } from '@priv/sdk/vue'

const app = createApp(App)

app.use(PrivPlugin, {
  apiKey: 'pk_live_xxxxxxxxxxxxx',
})

app.mount('#app')

<script setup>
import { usePriv } from '@priv/sdk/vue'

const { track } = usePriv()

function handleClick() {
  track('button_click', { button: 'cta' })
}
</script>

Verify Installation

Check that your integration is working:

Browser Console

// Enable debug mode
priv.debug()

// You should see:
// [PRIV] SDK initialized
// [PRIV] Event queued: page_view
// [PRIV] Batch sent: 1 events

Dashboard Verification

Open your PRIV Dashboard
Navigate to Real-time view
Trigger an event on your site
See it appear within seconds

Common Issues

Issue	Solution
Events not appearing	Check API key is correct and not expired
CORS errors	Ensure your domain is whitelisted in dashboard
SDK not loading	Verify npm package is installed correctly
Consent blocking	Check consent status is not `DENIED`

Configuration Options

const priv = new Priv({
  // Required
  apiKey: 'pk_live_xxxxxxxxxxxxx',

  // Batching
  batchSize: 10,           // Events per batch (default: 10)
  flushInterval: 5000,     // Ms between flushes (default: 5000)

  // Behavior
  autoTrack: true,         // Auto-track page views (default: true)
  trackClicks: false,      // Auto-track clicks (default: false)
  trackScrollDepth: false, // Track scroll depth (default: false)

  // Privacy
  respectDNT: true,        // Honor Do Not Track (default: true)
  anonymizeIP: true,       // Hash IP addresses (default: true)

  // Development
  debug: false,            // Enable console logging (default: false)
  disabled: false,         // Disable all tracking (default: false)
})

Next Steps

SDK Configuration

Advanced configuration options and customization

API Reference

Complete method documentation

React Guide

React-specific patterns and hooks

Authentication Guide

Secure your integration with proper auth