overwatch-sdk

Lightweight browser analytics SDK for comprehensive user behavior tracking. Silent, privacy-conscious, and production-ready.

Features

• Page views, sessions, and user journeys
• Click tracking with coordinates and element data
• Core Web Vitals and performance metrics
• Form interactions and field analytics
• Scroll depth and reading behavior
• JavaScript error monitoring
• Device fingerprinting and environment data
• Resource loading and network analysis
• City-level location tracking via IP geolocation
• 100% type-safe TypeScript
• Universal browser support (IE11+)

Installation

npm install overwatch-sdk
# or
bun add overwatch-sdk
# or
yarn add overwatch-sdk

Quick Start

import { watch } from 'overwatch-sdk';

// Initialize with your API key
watch.init('your-api-key', {
  endpoint: 'https://ingest.overwatch.dev'  // Rust ingestion service
});

// Track user interactions
watch
  .identify('user-123')
  .page({ title: 'Dashboard' })
  .click('#buy-button')
  .track({ type: 'purchase', value: 99.99 });

// Get insights
const analytics = watch.getSnapshot();
const deviceInfo = await watch.getDeviceWithLocation();

API Reference

Initialization

// Basic setup
watch.init('api-key', {
  endpoint: 'https://ingest.overwatch.dev'
});

// Debug mode (verbose logging)
watch.debug('api-key', 'https://ingest.overwatch.dev');

// Performance optimized (10% sampling)
watch.performance('api-key');

// With location tracking
watch.withLocation('api-key');

Tracking Methods

// Identify users
watch.identify('user-id');

// Track page views
watch.page({ title: 'Home', path: '/home' });

// Track clicks
watch.click('#button-id', { text: 'Buy Now' });

// Track form interactions
watch.form('submit', 'checkout-form', 'email-field');

// Track errors
watch.error('Payment failed', { errorType: 'network' });

// Track custom events
watch.track({
  type: 'video_play',
  duration: 30,
  videoId: 'abc123'
});

Performance Measurement

// Synchronous timing
const result = watch.time('api-call', () => fetchData());

// Asynchronous timing
const data = await watch.timeAsync('db-query', () => queryDatabase());

Data Access

// Get performance score (0-100)
const score = watch.getPerformance();

// Get session info
const session = watch.getSession();

// Get device info
const device = watch.getDevice();
const deviceWithLocation = await watch.getDeviceWithLocation();

// Get complete snapshot
const snapshot = watch.getSnapshot();
const snapshotWithLocation = await watch.getSnapshotWithLocation();

Configuration

watch.init('api-key', {
  endpoint: 'https://ingest.overwatch.dev',  // Rust ingestion service
  debug: false,
  sampleRate: 1.0, // Track 100% of users
  batchSize: 50,
  flushInterval: 5000,
  enableAutoTracking: {
    pageViews: true,
    clicks: true,
    scrolling: true,
    forms: true,
    performance: true,
    errors: true,
    visibility: true,
    resources: true,
    location: false
  },
  locationConfig: {
    enableIpLocation: true,
    cacheLocation: true,
    timeout: 5000
  }
});

Browser Support

• Chrome 60+
• Firefox 55+
• Safari 12+
• Edge 79+
• IE 11+ (with polyfills)
• Mobile browsers (iOS Safari, Chrome Mobile)

Event Types

| Event Type | Description | |------------|-------------| | pageview | Page loads with performance data | | pageleave | Time on page and scroll depth | | click | All clicks with element data | | scroll | Scroll depth tracking | | performance | Core Web Vitals (LCP, FID, CLS) | | error | JavaScript errors | | session_start | New sessions with device info | | form_* | Form interactions | | visibility_change | Tab visibility | | resource_load | Network resource timing |

Architecture

Browser → overwatch-sdk → POST /overwatch-ingest → Rust Service → ClickHouse

The SDK sends events to a high-throughput Rust ingestion service which writes to ClickHouse. A separate TS daemon provides query APIs for dashboards.

Privacy

• No cookies by default - uses session storage
• City-level location only - no precise GPS coordinates
• Configurable sampling - track subset of users
• Client-side processing - minimal data sent to server
• Self-hosted option - full data control

License

MIT

Built with TypeScript | Zero dependencies | <10KB gzipped | Production ready