Usage Tracker SDK

Lightweight (~15KB), privacy-first browser analytics tracker. Collects anonymous usage data and sends it to your self-hosted Usage Tracker server.

Installation

Script tag (auto-init)

<script src="https://your-server.com/t.js" data-key="YOUR_API_KEY"></script>

Auto-initializes when data-key is present. The endpoint is auto-detected from the script src.

npm / ESM

npm install @araneadev/usage-tracker-sdk

import { Tracker } from '@araneadev/usage-tracker-sdk';

const tracker = new Tracker({
  apiKey: 'YOUR_API_KEY',
  endpoint: 'https://your-server.com',
});

JSR (Deno / modern runtimes)

npx jsr add @usage-tracker/browser

import { Tracker } from "@usage-tracker/browser";

const tracker = new Tracker({
  apiKey: "YOUR_API_KEY",
  endpoint: "https://your-server.com",
});

Manual initialization

<script src="https://your-server.com/t.js"></script>
<script>
  const tracker = window.UsageTracker.init({
    apiKey: 'YOUR_API_KEY',
  });
</script>

Configuration

| Option | Type | Default | Description | |--------|------|---------|-------------| | apiKey | string | required | Project API key | | endpoint | string | auto-detect | Server URL (auto-detected from script src) | | enabled | boolean | true | Set false for consent mode (start disabled) | | flushInterval | number | 30000 | Milliseconds between event flushes | | batchSize | number | 50 | Max queued events before auto-flush | | debug | boolean | false | Log events to console | | piiFilter | boolean | true | Auto-filter PII field names | | requireHttps | boolean | true (prod) | Require HTTPS endpoint | | scrollTracking | boolean | true | Track scroll depth | | errorTracking | boolean | true | Track JavaScript errors | | performanceTracking | boolean | true | Track Core Web Vitals | | formTracking | boolean | true | Track form interactions | | wireframeCapture | boolean | true | Capture page wireframes for heatmaps | | consentStorageKey | string | 'tracker_consent' | localStorage key for consent state | | persistConsent | boolean | true | Persist consent to localStorage |

Custom Events

tracker.track('custom', { name: 'signup_complete', plan: 'pro' });

Consent Mode

Start disabled and enable after user consent:

const tracker = new Tracker({
  apiKey: 'YOUR_API_KEY',
  enabled: false,
});

// After user gives consent:
tracker.enable();

// Revoke consent:
tracker.disable();

// Check state:
tracker.isEnabled();           // boolean
tracker.getConsentTimestamp();  // Unix ms or null

Consent state persists to localStorage by default.

API

| Method | Description | |--------|-------------| | tracker.track(type, payload?, selector?) | Send a custom event | | tracker.enable() | Enable tracking (consent granted) | | tracker.disable() | Disable tracking (consent revoked) | | tracker.isEnabled() | Check if tracking is active | | tracker.getConsentTimestamp() | Get consent timestamp (ms) or null | | tracker.start() | Start tracking (called automatically) | | tracker.destroy() | Stop tracking and clean up |

Event Types

| Event | Data Captured | |-------|---------------| | pageview | URL, referrer, title, viewport | | click | Selector, text, x, y, width, height | | scroll | Depth (25%, 50%, 75%, 90%, 100%) | | form | Form name, action, field names (never values) | | error | Message, stack, URL, line, column | | performance | loadTime, FCP, LCP, CLS | | wireframe | Page layout skeleton for heatmap overlays | | context | User agent, viewport, referrer (sent once per session) |

Plugin Architecture

The SDK uses a plugin system. Each plugin implements the TrackerPlugin interface:

init(core) → onPageChange(url) → destroy()

Built-in plugins:

• ClickPlugin — Click position and element tracking
• ScrollPlugin — Scroll depth at 25/50/75/90/100% thresholds
• ErrorsPlugin — window.onerror and unhandledrejection capture
• PerformancePlugin — Core Web Vitals (LCP, CLS) and page load time
• FormsPlugin — Form field interactions (names only, never values)
• WireframesPlugin — DOM skeleton capture for heatmap overlays

Session Management

• Sessions use sess_ prefixed random IDs
• Stored in sessionStorage (scoped to the browser tab)
• Automatically expires when the tab is closed
• A new session is created on each new tab/window

Privacy

• No cookies, no fingerprinting
• Session IDs are random, not tied to identity
• PII field names auto-filtered (email, password, ssn, credit card, etc.)
• Form values are never captured — only field names and types
• All data stays on your server
• HTTPS required by default
• Code is unobfuscated and fully inspectable

Development

npm install          # Install dependencies
npm run build        # Build SDK (IIFE + ESM)
npm run build:iife   # Build IIFE only
npm run build:esm    # Build ESM only
npm run dev          # Watch mode
npm test             # Run tests
npm test -- --watch  # Watch mode tests
npm run publish:jsr  # Publish to JSR

Build Output

• dist/t.js — IIFE bundle (~15KB)
• dist/esm.mjs — ES module build

License

MIT