JavaScript SDK Reference

Full API reference for the sessionvision browser SDK. The SDK is available as @sessionvision/core on npm or via the CDN inline snippet.

sessionvision.init(token, config?)

Initialize the SDK. Must be called before any other method. When using the inline snippet, the stub queues all calls made before the full SDK loads.

sessionvision.init('sv_pub_...', {
  ingestHost: 'https://app.sessionvision.com',
  debug: false,
  optOut: false,
  maskAllInputs: true,
  autocapture: true,
});

sessionvision.capture(event, properties?)

Capture a custom event. Events are buffered and flushed in batches (10 events or 5 seconds).

sessionvision.capture('purchase_completed', {
  amount: 49.99,
  currency: 'USD',
  item_count: 3,
});

sessionvision.identify(userId, traits?)

Identify the current user. Links all future events to this user ID. Forward-only — does not retroactively link past anonymous events.

sessionvision.identify('user_456', {
  email: '[email protected]',
  name: 'Jane Smith',
  plan: 'enterprise',
});

sessionvision.reset()

Reset the current identity. Call on logout. Clears the user ID, generates a new anonymous ID, starts a new session, and clears all registered properties.

// On user logout
sessionvision.reset();

sessionvision.getDistinctId()

Returns the current distinct ID — the user ID if identified, or the anonymous ID otherwise.

const id = sessionvision.getDistinctId();
// "user_456" (if identified) or "550e8400-e29b-..." (anonymous)

sessionvision.register(properties)

Register properties to be included with every subsequent event. Overwrites existing registered properties with the same key.

sessionvision.register({
  app_version: '2.1.0',
  environment: 'production',
});

sessionvision.registerOnce(properties)

Like register(), but only sets properties that don't already exist. Useful for values like initial referrer that should only be set once.

sessionvision.registerOnce({
  initial_referrer: document.referrer,
  first_seen_at: new Date().toISOString(),
});

Event Payload Shape

Each event sent to the server has this structure:

{
  "event": "purchase_completed",
  "timestamp": 1709856000000,
  "properties": {
    "amount": 49.99,
    "$current_url": "https://example.com/checkout",
    "$browser": "Chrome",
    "$os": "macOS",
    "$device_type": "desktop",
    // ... all automatic properties
  },
  "anonymousId": "550e8400-e29b-41d4-a716-446655440000",
  "userId": "user_456",
  "sessionId": "a1b2c3d4-..."
}

Transport

Events are sent via POST {ingestHost}/api/v1/ingest/events as JSON batches. The SDK uses gzip compression (CompressionStream API when available) and keepalive: true for reliable delivery during page transitions. Failed requests are retried with exponential backoff (1s, 2s, 4s) on 5xx errors only.

SDK Architecture