npm package: @measuremetrics/measure-browser
Description: Lightweight browser tracking SDK for Measure
Author: Measure Team
Latest version: 1.0.1

# Measure Browser SDK

Lightweight browser tracking SDK for page views, custom events, and user identity, so you can capture frontend analytics without managing event queues or session logic yourself.

## Installation

```bash
bun add @measuremetrics/measure-browser
```

```bash
npm install @measuremetrics/measure-browser
```

## Quick start

```typescript
import { MeasureBrowser } from '@measuremetrics/measure-browser';

const measure = MeasureBrowser.init({
  publicKey: 'pk_live_...',
});

// Track a custom event
measure.track('button_clicked', { button: 'signup' });

// Identify a logged-in user
measure.identify('user_123', { plan: 'pro' });
```

## Configuration

| Field | Type | Default | Description |
|-------|------|---------|-------------|
| `publicKey` | `string` | *required* | Write-only public API key (safe to expose in client code) |
| `baseURL` | `string` | `https://measure.dev` | Base URL for the Measure API |
| `autoPageView` | `boolean` | `true` | Automatically track page views on navigation |
| `autoUtmCapture` | `boolean` | `true` | Automatically capture UTM parameters from the URL |
| `batchSize` | `number` | `10` | Number of events to batch before flushing |
| `flushIntervalMs` | `number` | `5000` | Interval in ms between automatic flushes |
| `sessionTimeoutMs` | `number` | `1800000` | Session timeout in ms of inactivity (default: 30 minutes) |
| `debug` | `boolean` | `false` | Enable debug logging to console |
| `respectDoNotTrack` | `boolean` | `false` | Respect the browser's Do Not Track setting |

## API

### `MeasureBrowser.init(config)`

Initialize the SDK. Returns a singleton instance. Subsequent calls return the existing instance.

### `measure.track(event, properties?)`

Track a custom event with optional properties.

```typescript
measure.track('purchase_completed', { amount: 49.99, currency: 'USD' });
```

### `measure.page(properties?)`

Manually track a page view. Called automatically if `autoPageView` is enabled.

```typescript
measure.page({ section: 'pricing' });
```

### `measure.identify(userId, traits?)`

Associate future events with a known user ID. Optionally include user traits.

```typescript
measure.identify('user_123', { plan: 'pro', company: 'Acme' });
```

### `measure.resetIdentity()`

Clear the current user identity (e.g., on logout). Future events use the anonymous ID only.

### `measure.optOut()`

Opt out of tracking. Queued events are flushed before tracking stops.

### `measure.optIn()`

Opt back in to tracking after a previous `optOut()`.

### `measure.flush()`

Immediately flush all queued events to the server.

### `MeasureBrowser.reset()`

Destroy the singleton instance and stop all tracking. Primarily useful for testing.

## How it works

- **Batching** -- Events are queued and sent in batches (default: 10 events or every 5 seconds) to minimize network requests.
- **Sessions** -- A session ID is generated and refreshed after 30 minutes of inactivity. Session boundaries are tracked automatically.
- **Anonymous IDs** -- Every visitor gets a stable anonymous ID stored in `localStorage`. This persists across page loads until `resetIdentity()` is called.
- **UTM capture** -- When `autoUtmCapture` is enabled, UTM parameters (`utm_source`, `utm_medium`, `utm_campaign`, `utm_term`, `utm_content`) are extracted from the URL and attached to every event.
- **Auto page views** -- When `autoPageView` is enabled, the SDK listens for `popstate` events and History API calls to automatically track page navigations.

## Privacy

- **Write-only key** -- The public key can only send events; it cannot read data from the API.
- **Do Not Track** -- When `respectDoNotTrack` is enabled, the SDK checks the browser's DNT setting and disables tracking if set.
- **Opt out** -- Call `measure.optOut()` to stop tracking immediately. Queued events are flushed first.
- **No cookies** -- The SDK uses `localStorage` for session and identity storage, not cookies.

## TypeScript

The SDK exports all configuration and event types:

```typescript
import type { MeasureBrowserConfig } from '@measuremetrics/measure-browser';
```

## Requirements

- Modern browser with `fetch` and `localStorage` support
- Public API key from your Measure dashboard