Tracking events

track()

kilden.track('checkout_completed', { plan: 'pro', total: 49.9 });

track(event: string, properties?: Properties, options?: TrackOptions): void

track returns void, not a Promise — events are queued and batched in the background. If you need to wait for delivery (rare; the SDK already flushes on page unload), call flush().

• properties is a JSON object (Record<string, JsonValue>). Kilden never validates or types your properties — the event envelope is typed, the payload is yours.
• options.timestamp (Date | string) backdates the event. Without it, the event is stamped when track is called, and the server corrects for client clock skew.
• Event names have no schema. One convention is enforced softly: names starting with $ are reserved for Kilden system events. Sending one from track logs a warning in debug mode but the event is still sent — the SDK never breaks your calls.

Every event automatically includes context properties: $current_url, $referrer, $session_id, $device_type, $screen_width, $screen_height, $lib, $lib_version, and $utm_source / $utm_medium / $utm_campaign / $utm_term / $utm_content parsed from the URL. See Events & properties.

The event payload

This is the shape of an event as it enters the queue — and as beforeSend and plugins see it:

interface EventPayload {
  uuid: string;          // UUID v7, generated by the SDK
  event: string;
  distinct_id: string;
  properties: Properties; // context $-properties already merged in
  timestamp: string;      // ISO 8601
}

Super properties: register() / unregister()

Super properties are persisted and merged into every subsequent event:

kilden.register({ app_version: '3.2.0', experiment_wave: 'q3' });
kilden.unregister('experiment_wave');

They survive reloads (in the configured persistence) and are cleared by reset().

flush()

await kilden.flush();

Sends everything in the queue now. The only method on the client that returns a Promise.

Reading identifiers

kilden.getDistinctId(); // "anon_018f..." or your user id after identify()
kilden.getSessionId();  // current $session_id (rotates after 30 min idle)

Opt-out

kilden.optOut();       // persisted: stops all capture and network traffic
kilden.optIn();        // re-enable
kilden.hasOptedOut();  // boolean

While opted out nothing is captured or sent, including feature-flag loads from /decide (already-cached flag values keep answering).

group() — reserved

group(groupType: string, groupKey: string, properties?: Properties): void

B2B group analytics is part of the frozen surface but not yet available: calling group() is a safe no-op that logs a warning in debug mode. It exists so the install snippet never needs to change when it ships.