SDK overview & installation

@kilden/sdk is the Kilden web SDK: event capture, identity, autocapture, feature flags and session replay in one client. The core is dependency-free and small (under 15 KB gzipped; autocapture and replay load as separate lazy chunks only when used).

Install with the snippet

Paste this before </head>. It creates window.kilden with a stub queue before the bundle loads, so no call is ever lost — the SDK replays queued calls in their original order once it loads:

<script>
  !(function (w, d) {
    if (w.kilden) return;
    function stub(o, names) {
      o._q = [];
      names.split(' ').forEach(function (m) {
        o[m] = function () { o._q.push([m].concat([].slice.call(arguments))); };
      });
      return o;
    }
    var k = (w.kilden = stub({}, 'init track identify setPersonProperties reset register unregister getDistinctId getSessionId optOut optIn hasOptedOut setIdentityToken flush use removePlugin startSessionRecording stopSessionRecording getReplayId group isFeatureEnabled getFeatureFlag onFeatureFlags'));
    k.flags = stub({}, 'isFeatureEnabled getFeatureFlag getAllFlags onFeatureFlags reload override');
    k.messenger = stub({}, 'open close show hide toggle showNewMessage on off update');
    var s = d.createElement('script');
    s.async = true;
    s.src = 'https://cdn.kilden.io/kilden.iife.js';
    d.head.appendChild(s);
  })(window, document);

  kilden.init('YOUR_WRITE_KEY');
</script>

The project onboarding page in the panel gives you this exact snippet with your write key and API host already filled in.

Install with npm

npm install @kilden/sdk

import kilden from '@kilden/sdk';

kilden.init('YOUR_WRITE_KEY');
kilden.track('signup_completed', { plan: 'pro' });

The default export is a singleton — call init once and import it anywhere. If you need isolated clients (multiple projects on one page, tests), use createClient:

import { createClient } from '@kilden/sdk';

const analytics = createClient('YOUR_WRITE_KEY', { debug: true });
analytics.track('signup_completed');

The client surface

Method	What it does
`init(writeKey, options?)`	Initialize. See Configuration
`track(event, properties?, options?)`	Queue an event. See Tracking events
`identify(userId, traits?, options?)`	Tie the anonymous visitor to your user id. See Identity methods
`setPersonProperties(set, setOnce?)`	Update person traits
`reset()`	Log out: rotate anonymous id, clear token and super properties
`register(properties)` / `unregister(key)`	Persisted super properties merged into every event
`getDistinctId()` / `getSessionId()`	Current distinct id / session id
`optOut()` / `optIn()` / `hasOptedOut()`	Persisted capture kill switch
`setIdentityToken(token)`	Set or clear the identity verification JWT
`flush()`	Force-send the queue. The only method that returns a `Promise`
`use(plugin)` / `removePlugin(name)`	Event pipeline plugins. See Plugins
`isFeatureEnabled(key)` / `getFeatureFlag(key)` / `onFeatureFlags(cb)`	Feature flags. See Feature flags
`startSessionRecording()` / `stopSessionRecording()` / `getReplayId()`	Session replay. See Session replay
`group(groupType, groupKey, properties?)`	Reserved. Group analytics is not yet available; calling it is a safe no-op that logs a warning in debug mode

Guarantees

These behaviors are contractual — the SDK’s public surface is frozen and versioned:

The public API never throws. Invalid input is discarded, with a warning only when debug: true.
Your data is never mutated — no trimming, lowercasing or normalizing.
Calls made before init are queued and processed at init, in order. Nothing is lost.
Events are sent in batches and retried with exponential backoff. Each event carries a client-generated UUID v7, so retries are idempotent — the pipeline deduplicates by UUID.
On page unload the queue is flushed with fetch(keepalive) (or sendBeacon as a fallback) so tail events survive navigation.
optOut() persists and stops all capture and network traffic.