Custom Events

Use sessionvision.capture() to track events specific to your product. Custom events are enriched with the same automatic properties as auto-tracked events.

Basic Usage

sessionvision.capture('button_clicked', {
  button_name: 'upgrade',
  page: 'pricing',
});

Examples

Feature Usage

sessionvision.capture('feature_used', {
  feature: 'export_csv',
  record_count: 150,
});

Purchase Flow

sessionvision.capture('checkout_completed', {
  plan: 'pro',
  billing_cycle: 'annual',
  amount: 199,
  currency: 'USD',
});

Search

sessionvision.capture('search_performed', {
  query: searchQuery,
  results_count: results.length,
  filters_applied: activeFilters,
});

Errors

sessionvision.capture('error_occurred', {
  error_type: 'api_error',
  status_code: 500,
  endpoint: '/api/users',
});

Event Buffering

Events are not sent immediately. The SDK buffers events and flushes them in batches for efficiency:

Setting	Value
`Batch size`	`10 events`
`Flush interval`	`5 seconds`
`Max retries`	`3 (on 5xx errors)`
`Retry delays`	`1s, 2s, 4s (exponential backoff)`

Flush also triggers when the tab becomes hidden (visibilitychange event). The SDK uses keepalive: true on fetch requests so in-flight batches survive page transitions. Events are not retried on 4xx errors (client errors indicate bad data, not transient failures).

Registered Properties

Use register() to attach properties to every subsequent event:

// These properties will be included in all future events
sessionvision.register({
  app_version: '2.1.0',
  environment: 'production',
});

// registerOnce only sets if the property doesn't already exist
sessionvision.registerOnce({
  initial_referrer: document.referrer,
});