Capture, identify & alias

Same API as the browser: capture(), identify(), alias(). Pass distinctId (and optional anonymousId) per call or via setContext().

#Capture

Send custom events. Include anonymousId when linking to browser sessions — for example, when a server-side webhook needs to attach to a still-anonymous browser visitor.

vtilt.capture({
  distinctId: 'user_123',
  event: 'purchase',
  properties: { amount: 99.99 },
  anonymousId: 'anon_from_browser', // optional, for linking
})

Every event automatically carries $lib, $lib_version, and a generated $insert_id. For serverless/edge handlers where there may be no later flush, use captureImmediate() (also identifyImmediate / aliasImmediate), which sends a single event and resolves when the request completes:

await vtilt.captureImmediate({
  distinctId: 'user_123',
  event: 'webhook_received',
})

#Geolocation & end-user metadata

A server can't observe the visitor's browser, so the SDK never sends $browser / $os / device properties. It can geolocate the visitor and record their original User-Agent / referrer — but only if you forward them from the incoming request:

vtilt.capture({
  distinctId: 'user_123',
  event: 'page_view',
  ip: req.ip, // -> $ip, enables GeoIP exactly like the browser
  userAgent: req.headers['user-agent'], // optional -> $raw_user_agent
  referrer: req.headers['referer'], // optional -> $referrer
})

GeoIP is smart by default: it runs only when an ip is available. When you don't forward one, the SDK disables GeoIP so your own server's IP is never geolocated. You can set these once per request with setContext().

#Identify

Attach properties to a person record. Pass anonymousId to link an anonymous browser session to its newly-authenticated identity (e.g. immediately after login). The merge behaviour is the same as the browser identify() — see Browser SDK / Identify & alias for the full model.

vtilt.identify({
  distinctId: 'user_123',
  anonymousId: 'anon_from_cookie', // optional, for merge
  properties: { name: 'Alice', plan: 'pro' },
})

#Alias

Link two distinct ids — for example, joining a legacy auth id with a new SSO id, or stitching two known accounts together.

vtilt.alias({
  distinctId: 'user_123',
  alias: 'legacy_id_456',
})