@scoperat/tracker

Browser analytics SDK.

Install

npm install @scoperat/tracker

Quick Start

import scoperat from "@scoperat/tracker";

// Initialize once at app startup (endpoint defaults to window.location.origin)
scoperat.init("tk_live_your_write_key");

// Identify the current user after login
scoperat.identify("user_123", { email: "[email protected]", orgId: "org_456" });

// Track events
scoperat.track("button_clicked", { buttonId: "signup-cta", page: "/pricing" });

// Reset on logout
scoperat.reset();

API

scoperat.init(writeKey, options?)

Initialize the tracker. Must be called before any other method.

| Option | Type | Default | Description | | --------------- | ------------------------- | ------------------------ | ---------------------------- | | endpoint | string | window.location.origin | API base URL | | flushAt | number | 10 | Flush after this many events | | flushInterval | number | 3000 | Auto-flush interval in ms | | timeout | number | 10000 | Request timeout in ms | | onError | (error, events) => void | — | Error callback |

scoperat.identify(userId, traits?)

Associate events with a user. Traits are merged into every event's context.

scoperat.track(event, properties?)

Enqueue a tracking event. Events are batched and flushed automatically.

scoperat.reset()

Clear user identity and generate a new anonymous ID. Call on logout.

scoperat.flush()

Manually flush the event buffer. Returns a Promise<FlushResult>.

scoperat.shutdown()

Flush remaining events and stop the auto-flush timer. Call before app teardown.

Features

• Auto-batching — events are buffered and sent in batches for efficiency
• Anonymous IDs — persistent anonymous ID via localStorage, auto-generated on first visit
• sendBeacon fallback — uses navigator.sendBeacon on page hide for reliable delivery
• Retry on failure — failed batches are re-queued for the next flush
• Zero dependencies — no runtime dependencies
• Tree-shakeable — marked as side-effect-free for optimal bundling
• ESM-only — ships as pure ES modules

License

MIT