SDKs

View @pug-sh/browser on npm ↗

View pug_flutter on pub.dev ↗

View @pug-sh/node on npm ↗

The Web SDK ships as compiled JavaScript plus type definitions for bundlers (Vite, webpack, esbuild, Next.js, …) and runs in the browser. There is no standalone <script>/CDN build.

Import named exports from the package root:

import { init, track, identify, reset } from '@pug-sh/browser'

init() runs once wherever your app boots — there are no framework-specific packages. For Vite, Vue, and other bundlers, just call it at your entry point.

// components/PugProvider.tsx
'use client'

import { init } from '@pug-sh/browser'
import { useEffect } from 'react'

export function PugProvider({ children }: { children: React.ReactNode }) {
  useEffect(() => {
    init(process.env.NEXT_PUBLIC_PUG_PROJECT_ID!, {
      apiKey: process.env.NEXT_PUBLIC_PUG_PUBLIC_KEY!
    })
  }, [])
  return <>{children}</>
}

Verify by opening your dashboard’s Live view — an auto-tracked page_view appears within ~15 seconds.

pug_flutter is published on pub.dev. flutter pub add pug_flutter adds it to pubspec.yaml and fetches it; to pin the version yourself, add it under dependencies instead:

dependencies:
  pug_flutter: ^0.0.2

Import it wherever you call the SDK:

import 'package:pug_flutter/pug_flutter.dart';

Smoke-test by adding a minimal Pug.init in main() (see Initialize) and running the app — with auto-tracking on, an app_open event appears in Live within a few seconds. (page_view events need the PugRouteObserver — see Auto-tracking.)

The Node SDK is server-side and ships as ESM — it needs Node.js 18+. Import the Pug class:

import { Pug, PugError } from '@pug-sh/node'

Unlike the client SDKs it authenticates with your private key (prv_…), so keep it on the server — in an environment variable, never in code shipped to a browser or app. Construct one instance at boot and reuse it across requests.

Send requests to https://api.pugs.dev — or your self-hosted base URL, e.g. http://localhost:3000 — with three headers:

The public key is write-scoped and safe in server-side code that sends events on behalf of your users. Never use a private key for ingestion.

init returns nothing. It throws if projectId or apiKey is missing, and no-ops (with a console warning) if called a second time or outside a browser.

Tear down and re-init with destroy() (flushes the queue, removes listeners). reset() and rotate() are covered under Identify and sessions.

Pug.init returns Future<void> and throws ArgumentError if projectId or apiKey is empty. A second init while running is silently ignored (a warning is logged via PugLogger); call Pug.destroy() first to reinitialize.

Advanced overrides — logger, storage, transport, autoPropertyProvider, linkProvider — let you inject test doubles or custom collection.

new Pug(options) returns an instance immediately. It authenticates with your private key and batches events in memory — construct it once and share it across requests.

Call await pug.close() on graceful shutdown so buffered events flush — anything still undeliverable is reported through onError. The Node SDK has no destroy(), reset(), or rotate(): a server has no ambient user or session to reset.

There is no initialization step. Authenticate every request with the x-api-key header (your pub_… key) and target your base URL — https://api.pugs.dev, or a self-hosted URL such as http://localhost:3000. Event properties are wrapped by hand (see Track events).

track() never throws and returns nothing — events are queued and flushed in the background, so analytics can’t break or block your app.

Property values accept string (truncated to 1024 bytes client-side), number, boolean, and Date (stored as a timestamp). Objects and arrays are JSON-encoded to a string. null, undefined, and non-finite numbers are dropped. Send numbers as numbers — aggregations like Sum don’t work on strings.

track(event, props?, options?) options:

// Conversion that must arrive before a redirect
track('purchase', { productId: 'sku_789', amount: 99, currency: 'USD' }, { immediate: true })

Pug.track(...) never throws — calls are wrapped in try/catch and queued in the background. The generated Pug.track.* namespace has a typed method per well-known event; pass schema-external properties via extras: {...} (on a key collision, the named argument wins). For runtime-determined names, call Pug.track(kind, props: {...}) directly.

Property values accept String (truncated to 1024 UTF-8 bytes), bool, int, finite double/num (non-finite dropped), and DateTime (UTC epoch ms). Iterable/Map are JSON-encoded to a string; null is dropped — omit the key instead.

TrackOptions (on Pug.track and every typed method):

Pug.track.purchase(
  productId: 'sku-789', amount: 99.0, currency: 'USD',
  options: const TrackOptions(immediate: true),
);

pug.track(distinctId, kind, props?, options?) puts the distinctId first — a server has no ambient user, so you name who each event is for (your external ID, or an anon-… ID forwarded from the client). It never throws and is non-blocking: events are validated, batched, and flushed in the background.

There is no { immediate } on the server — flush explicitly instead:

// track() is non-blocking and batched — there is no { immediate }.
await pug.flush()   // send what's buffered right now
await pug.close()   // drain on graceful shutdown so nothing buffered is lost

track options: timestamp (epoch-millisecond override) and sessionId (per-call session override — otherwise the instance uses one session ID for its lifetime). Property values accept the same JSON scalar types as the other SDKs.

Endpoint: POST /sdk.events.v1.EventsService/BatchCreate (max 1000 events per request).

The SDKs wrap property values for you; over raw HTTP you wrap each value in a typed object yourself — the single most important thing to get right:

customProperties keys must not start with $ (reserved for auto-properties); kind must not start with pug.. The response is { "accepted": <n> }. See Errors and the raw HTTP API for status codes and full examples, and the Events API reference for the complete schema.

identify(externalId, traits?) returns a promise and never throws — invalid input, a call before init(), denied consent, dryRun, and RPC failures are all logged and the promise resolves without sending, so you can await it without a try/catch. On the first identify it includes the anonymous ID so prior anonymous events merge into the profile. reset() clears the stored identity and starts a new anonymous session — it does not delete the profile in the dashboard.

Pug.identify(externalId, {traits}) returns Future<void> and never throws — invalid input and transport failures are logged and the future completes normally; a call before Pug.init() is ignored with a warning. reset() is synchronous — it generates a new device ID, a new anonymous ID, and a new session, and removes the stored externalId (the profile stays in the dashboard). Drain the queue with await Pug.flush(); fully tear down with Pug.destroy().

pug.identify(externalId, traits?, options?) returns a promise and never throws — failures are logged. Pass { anonymousId } (must start with anon-) on the first identify to merge a client’s prior anonymous activity into the profile, and { deviceId } to attach a device. There is no reset() or rotate(): identity isn’t ambient on the server — you name the distinctId on every track() call instead.

Endpoint: POST /sdk.profiles.v1.ProfilesSDKService/Identify

The response is an empty object {} on success. You set each event’s distinctId yourself — the anonymous ID before identify, your external ID after.

Six trackers install with autoCapture on (the default). Pass a per-listener allowlist to run only some — omitted keys stay off — and change the selection at runtime with setAutoCapture():

import { init } from '@pug-sh/browser'

init('YOUR_PROJECT_ID', {
  apiKey: 'pub_YOUR_PUBLIC_KEY',
  autoCapture: { pageView: true, click: true, scroll: false }
})

page_view fires on the initial load and on SPA navigation via the History API (pushState/replaceState/popstate), so call init() before your router mounts. The Next.js App Router navigates without a History push — track those page_views manually. To gate all capture behind a consent banner, see Consent and privacy.

Navigation is captured when you wire a PugRouteObserver into your MaterialApp:

MaterialApp(
  navigatorObservers: [PugRouteObserver()],
  // … rest of your config
)

On each route change the SDK emits a navigation event — screen_view (with screenName set to the route name) on iOS/Android, and page_view on web; desktop targets emit neither. The navigation event itself carries no url props — instead every event picks up the current and previous route as the $url and $referrer auto-properties, so route context is present even when autoPageViews is off. Route names come from route.settings.name, falling back to the route’s runtime type.

App lifecycle is observed automatically (no wiring): app_open when the app enters the foreground, and app_close on background/hidden/paused/detached — sent with immediate: true so it arrives before the OS kills the process.

Campaign capture (autoCaptureCampaigns, on by default) reads UTM parameters and ad click-ids from incoming deep links and attaches them as auto-properties ($utmSource, $utmMedium, $gclid, …) to subsequent events.

There is no client-side auto-tracking on the server — you send every event explicitly with pug.track(distinctId, …). The server still enriches each event during processing, attaching geo ($country, $region, $city) and bot-detection ($bot_score, $verified_bot) auto-properties you don’t set yourself.

There is no client-side auto-tracking over raw HTTP — you send every event explicitly. The server still enriches each event during processing, attaching geo ($country, $region, $city) and bot-detection ($bot_score, $verified_bot) auto-properties you don’t set yourself.