Initialization

Call init once at application startup. All other SDK functions require init to have run first.


import { init } from '@poluruprvn/pug-web'
 
init('YOUR_PROJECT_ID', {
  apiKey: 'YOUR_SDK_API_KEY',
  endpoint: 'https://api.pug.sh'
})

Options reference

Option	Type	Default	Description
`apiKey`	`string`	required	Project SDK API key from Settings
`endpoint`	`string`	—	Pug API base URL (`https://api.pug.sh`)
`samplingRate`	`number`	`1`	Fraction of events to keep (0–1)
`batch`	`object`	see below	Batch size and flush interval
`session`	`object`	see below	Session timeout settings
`autoTrack`	`object`	all enabled	Enable/disable auto-trackers
`dryRun`	`boolean`	`false`	Log events without sending to API

`batch`

Controls how events are queued before sending:


init('PROJECT_ID', {
  apiKey: 'KEY',
  batch: {
    maxSize: 20,        // flush when queue reaches this many events
    flushIntervalMs: 5000  // flush every 5 seconds regardless of queue size
  }
})

Events persist in localStorage — a page reload doesn’t lose queued events. Use { immediate: true } on individual track() calls to bypass the queue.

`session`


init('PROJECT_ID', {
  apiKey: 'KEY',
  session: {
    timeoutMs: 30 * 60 * 1000  // 30 minutes of inactivity starts a new session
  }
})

`samplingRate`

Reduce event volume in high-traffic apps:


init('PROJECT_ID', {
  apiKey: 'KEY',
  samplingRate: 0.1  // keep 10% of events
})

Sampling applies per-event at track time. Do not use sampling on revenue or conversion events — sample page views instead.

`autoTrack`

See Auto-tracking for the full tracker list:


init('PROJECT_ID', {
  apiKey: 'KEY',
  autoTrack: {
    pageView: true,
    click: true,
    scroll: false,      // disable scroll depth tracking
    form: true,
    frustration: true
  }
})

`dryRun`

Log events to the console without sending — useful during development:


init('PROJECT_ID', {
  apiKey: 'KEY',
  dryRun: true
})

Remove dryRun before deploying to production.

Environment-specific config


const isDev = import.meta.env.DEV
 
init(import.meta.env.VITE_PUG_PROJECT_ID, {
  apiKey: import.meta.env.VITE_PUG_API_KEY,
  endpoint: isDev ? 'http://localhost:8080' : 'https://api.pug.sh',
  dryRun: isDev,
  samplingRate: isDev ? 1 : 1
})

For self-hosted backends, point endpoint at your API URL. See Self-hosting.

Lifecycle functions


import { init, destroy, reset, rotate } from '@poluruprvn/pug-web'
 
init('PROJECT_ID', { apiKey: 'KEY' })
 
// SPA teardown — flush queue, remove listeners
destroy()
 
// Sign-out — clear identity, start fresh anonymous session
reset()
 
// Force new session ID without clearing identity
rotate()

Function	When to call
`destroy()`	Micro-frontend unmount, test teardown
`reset()`	User signs out, account switch
`rotate()`	Explicit new session (e.g. after 30 min idle prompt)

SPA integration

Auto-trackers hook into the History API for client-side routing. Call init() before your router mounts:


// Correct order
init('PROJECT_ID', { apiKey: 'KEY' })  // 1. SDK first
createRouter({ ... })                   // 2. Router second
app.use(router)                         // 3. Mount app

For frameworks where the router mounts before your init code runs (some Next.js setups), use a dedicated client component — see Installation.

Common issues

Symptom	Fix
`track()` does nothing	Confirm `init()` ran first; check for `dryRun: true`
Events from wrong project	Verify project ID and API key match dashboard Settings
Session not syncing across tabs	Confirm `localStorage` is available (not in iframe with restricted storage)
High event volume	Lower `samplingRate` or disable noisy auto-trackers

Next step

Tracking events — custom events, well-known schemas, immediate flush.