Skip to main content
The Wendung SDK is written in TypeScript and exports its public types from @wendung/sdk.

InitConfig

The configuration object accepted by Wendung.init(). Only apiKey is required; the rest fall back to defaults.

ConsentState

The analytics consent states accepted by init() and setConsent() and returned by getConsent(). See the consent guide for what each state does.

Config

The full resolved configuration after defaults are applied. Applications normally pass InitConfig instead.
string
required
Your publishable API key. Sent with every request as the X-API-Key header; it does not appear in the request body.
string
required
The resolved ingest endpoint. Defaults to https://ingest.wendung.app/v1/events. http:// is only permitted for localhost addresses.
number
required
Milliseconds between automatic flushes. Defaults to 5000.
number
required
Maximum events per outbound batch. Defaults to 50; the effective value is clamped to 1–100.
boolean | 'auto'
required
Defaults to false. true enables full pageviews with granted consent. 'auto' also enables aggregate pageviews while pending. Denied consent stops both. See options.
boolean
When true, verbose [Wendung] messages are written to the console. Defaults to false.

Identity

The user context attached to events. Set by Wendung.identify(), cleared by Wendung.reset().
string | null
required
The identifier of the current user, or null for an anonymous session.
string
The SDK’s random visitor identifier for full analytics. Aggregate pageviews omit identity entirely.
Record<string, unknown>
Key-value metadata about the user. Replaced wholesale by each identify() call.

EventContext

Environment metadata captured when an event is tracked.
'@wendung/sdk'
required
The literal package name.
string
required
The SDK version, also sent as the X-Wendung-SDK-Version request header.
string
The full URL for consented events, or origin and pathname for aggregate pageviews. Absent outside the browser.
string
For the first pageview, document.referrer; for later pageviews, the previous pageview’s URL. Aggregate pageviews restrict it to the origin. Absent when empty or outside the browser.

StepEvent

A single tracked event, as queued and as sent in the events array of a payload. All snapshot fields are captured at the moment Wendung.step() is called.
string
required
Unique event ID, generated with crypto.randomUUID().
string
required
The event name passed to step(), 1–100 characters.
Record<string, unknown>
Deep-cloned copy of the properties passed to step(). Present only when supplied.
string
required
ISO 8601 UTC timestamp (new Date().toISOString()) recorded at call time.
string
The session ID active when the event was tracked.
Identity
Snapshot of the identity at track time. Later identify() calls do not backfill earlier events.
EventContext
Snapshot of the event context at track time.

EventRequestPayload

The JSON body for full analytics requests. Payload is an alias for this type. Pending aggregate pageviews use AggregatePageviewPayload instead. Requests carry the headers Content-Type: application/json, X-API-Key, and X-Wendung-SDK-Version.
'identity' | 'event'
required
Payload discriminant. The SDK currently always sends 'event'.
string
required
Random UUID identifying the batch. Stable across retries of the same batch.
string
required
The session ID of the first event in the batch, or the current session if the batch is empty.
Identity
required
The identity snapshot of the first event in the batch, or the current identity.
StepEvent[]
required
The events being delivered, at most the effective batch size (1–100).
string
required
ISO 8601 UTC timestamp taken when the payload is serialized, distinct from the per-event timestamp fields.
EventContext
required
The context snapshot of the first event in the batch, or the current context.

AggregatePageviewPayload

The request body for pageviews collected with trackPageviews: 'auto' while consent is pending.
Every event has the name $pageview. The body and its events contain no visitor identity or session ID. Event and batch IDs support delivery deduplication. The pageview field reference describes the restricted context.