Configuration

init(writeKey, options?) accepts an InitOptions object. All fields are optional.

import kilden from '@kilden/sdk';

kilden.init('YOUR_WRITE_KEY', {
  flushAt: 20,
  flushIntervalMs: 5000,
  autocapture: true,
  debug: false,
});

InitOptions

Option	Type	Default	Notes
apiHost	string	https://ingest.kilden.io	Base URL for ingestion. The default is Kilden Cloud — only set it if you self-host. One host serves /capture, /decide and /replay — there is no separate host for feature flags or replay
flushAt	number	20	Queue size that triggers a flush
flushIntervalMs	number	5000	Max time an event waits in the queue
persistence	'localStorage' | 'cookie' | 'memory'	'localStorage'	Where the anonymous id, super properties and opt-out state live. Falls back to memory automatically when the chosen storage is unavailable
autocapture	boolean | AutocaptureOptions	true	Automatic click/submit/pageview capture. With false the autocapture code is never even downloaded. See Autocapture & privacy
debug	boolean	false	Log warnings (invalid input, $-prefixed custom events, no-op calls) to the console. The SDK never throws either way
beforeSend	(event: EventPayload) => EventPayload | null	—	Transform or drop (return null) every event before it is queued — including $autocapture and other automatic events
identityToken	string	—	Identity verification JWT, sent as Authorization: Bearer with each batch. See Identity verification
getIdentityToken	() => Promise<string | null>	—	Token refresh callback: called before the current token expires and after a 401
sessionRecording	boolean | SessionRecordingOptions	unset	Session replay. By default the project’s remote config decides; false is a hard opt-out that never downloads the recording code. See Session replay

AutocaptureOptions

Pass an object instead of true to tune autocapture:

Option	Type	Default	Notes
captureClicks	boolean	true	Emit $autocapture on clicks
captureSubmits	boolean	true	Emit $autocapture on form submits
captureChanges	boolean	false	Emit $autocapture on input changes. Only the fact that something changed is recorded — never the value
ignoreSelectors	string[]	—	CSS selectors to exclude from capture
maskAllText	boolean	false	Replace all element text in $elements with "*"
allowUrls	(string | RegExp)[]	—	Restrict autocapture to matching URLs

SessionRecordingOptions

Pass an object instead of true to tune replay:

Option	Type	Default	Notes
sampleRate	number	0.1	Fraction of sessions to record, 0..1. Decided once per session and sticky across reloads
minimumDurationMs	number	2000	Recordings shorter than this are discarded
maskAllInputs	boolean	true	Mask everything the user types. Deliberately the opposite default of autocapture: a replay shows keystrokes, so masking is opt-out
maskAllText	boolean	false	Mask all page text
blockSelectors	string[]	—	CSS selectors to exclude from the recording entirely
recordCanvas	boolean	false	Record <canvas> contents (heavy, rarely useful)

Batching and delivery

• Events queue in memory and flush when the queue reaches flushAt events or the oldest event is flushIntervalMs old, whichever comes first.
• On pagehide/visibilitychange the queue is flushed immediately. With an identity token present the SDK uses fetch(url, { keepalive: true }) (it can carry the Authorization header); without one — or without keepalive support — it uses sendBeacon, with the token inside the request body as a documented fallback.
• Failed flushes retry with exponential backoff. Every event has a client-generated UUID v7, so retries are idempotent end to end.
• Batches are gzip-compressed via CompressionStream when the browser supports it.

Identifiers the SDK manages

• Anonymous id: anon_ + UUID v7, generated on first visit and persisted in the configured storage.
• Session id ($session_id on every event): UUID v7, rotated after 30 minutes of inactivity.