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

bun add @measuremetrics/measure-browser

npm install @measuremetrics/measure-browser

Quick start

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.

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

measure.page(properties?)

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

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

measure.identify(userId, traits?)

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

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:

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

Requirements

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