configuration

The options Contextune.init() accepts, the blocks getSnapshot() returns, and their defaults. All fields are optional; the minimal call is Contextune.init().

every option set explicitlyts

import { Contextune } from '@contextune/sdk';

Contextune.init({
  source: 'segment',          // tap segment network traffic
  eventLogSize: 100,          // keep last 100 events (default 50)
  persistence: 'ct-session',  // survive page reloads (default 'navigation')
  context: {
    extras: {
      marketing: true,  // capture UTM / referrer (default true)
      device: true,     // capture viewport / UA (default true)
    },
  },
  tracking: {
    scroll: true,      // emit 'scroll' at 25/50/75/100% depth (default off)
    rageClicks: true,  // emit 'rage_click' on 3+ fast clicks (default off)
  },
});

1 / init() options

The top-level options object passed to Contextune.init(options?).

ContextuneOptions

name	type	default	example
`source` Tap an existing analytics stream. When set, the SDK installs fetch / sendBeacon / XHR patches and intercepts traffic to the named provider. Omit to use direct-call mode — only track() and page() calls populate the log, and no network patches are installed.	`'ga4' \| 'segment' \| 'mixpanel' \| undefined`	`undefined`	`'ga4'`
`eventLogSize` Maximum events retained in event_log. Oldest dropped FIFO when capacity is reached.	`number`	`50`	`100`
`persistence` 'navigation' (default): event log lives in memory only, cleared on page reload. 'ct-session': event log is saved to localStorage and restored on reload; scoped to 30 minutes of inactivity via a cookie.	`'navigation' \| 'ct-session'`	`'navigation'`	`'ct-session'`
`context.extras.marketing` Include marketing_params (UTM, referrer, landing page). Disable if your app does not need attribution context.	`boolean`	`true`	`false`
`context.extras.device` Include device_info (viewport, user agent, language, platform, device type).	`boolean`	`true`	`false`
`tracking.scroll` Emit a 'scroll' event each time the user crosses a 25 / 50 / 75 / 100% page-depth milestone.	`boolean`	`false`	`true`
`tracking.rageClicks` Emit a 'rage_click' event when the same target is clicked 3+ times within a 1-second window, a friction cue.	`boolean`	`false`	`true`

2 / device_info block

Static device information, read at snapshot time from navigator and window. Enabled by default; disable with context.extras.device: false.

snapshot.device_info

name	type	default	example
`user_agent` navigator.userAgent verbatim.	`string`	—	`'Mozilla/5.0 ...'`
`viewport_w` window.innerWidth in CSS pixels at snapshot time.	`number`	—	`1440`
`viewport_h` window.innerHeight in CSS pixels at snapshot time.	`number`	—	`900`
`language` navigator.language.	`string`	—	`'en-GB'`
`platform` navigator.platform (legacy field; still useful as a coarse OS hint).	`string`	—	`'MacIntel'`
`device_type` Derived from user agent + viewport width.	`'desktop' \| 'tablet' \| 'mobile'`	—	`'desktop'`

3 / marketing_params block

Frozen-at-init marketing context. Every URL field is passed through redactUrl which strips sensitive query params and replaces UUID path segments. Enabled by default; disable with context.extras.marketing: false.

snapshot.marketing_params

name	type	default	example
`utm_source` utm_source query param at landing time, decoded and sanitised.	`string \| null`	—	`'google'`
`utm_medium` utm_medium query param at landing time.	`string \| null`	—	`'cpc'`
`utm_campaign` utm_campaign query param at landing time.	`string \| null`	—	`'summer'`
`utm_term` utm_term query param at landing time.	`string \| null`	—	`'field-jacket'`
`utm_content` utm_content query param at landing time.	`string \| null`	—	`'hero-cta'`
`referrer` document.referrer at init, routed through redactUrl. null when there is no referrer.	`string \| null`	—	`'https://www.google.com/'`
`landing_page` Full window.location.href at init, routed through redactUrl (sensitive query params replaced with [REDACTED]).	`string \| null`	—	`'https://app.example.com/?utm_source=google'`

4 / event_log block

A rolling FIFO window of events. Always present in the snapshot. Default size is 50; raise with eventLogSize.

snapshot.event_log[i]

name	type	default	example
`name` Normalised event name: page_view (from Contextune.page()), scroll / rage_click (from tracking extras), your custom track() name, or an event normalised from the intercepted analytics provider.	`string`	—	`'page_view'`
`elapsed_s` Whole seconds elapsed since session start.	`number`	—	`67`
`properties` Optional event payload. Recursively sanitised: sensitive keys redacted, URL-shaped values scrubbed, depth bounded at 4.	`Record<string, unknown> \| undefined`	—	`{ form: 'checkout' }`

lifecycle & persistence

With persistence: 'navigation' (the default), the snapshot lives only in JavaScript memory for the life of the tab. It is cleared on page reload and never shared across tabs.

With persistence: 'ct-session', the event log is written to localStorage and restored on reload. A cookie (contextune_session) tracks inactivity; the log is cleared after 30 minutes without activity. The cookie and localStorage key are scoped to the current origin.

Call Contextune.clear() to empty the event log — in memory and, under ct-session, its persisted copy — while keeping the SDK running (patches, subscribers, and the session clock stay intact). Contextune.destroy() goes further: it tears the SDK down and, under ct-session, removes the stored log and expires the cookie, so the profile cannot be recovered by a later init().

event_log is a fixed-size FIFO: once it reaches eventLogSize (50 by default) the oldest event is dropped as each new one arrives. There is no time-based expiry for individual events — they persist until evicted by the FIFO cap or the session ends.

full snapshot shape

For reference — the complete TypeScript shape of getSnapshot()'s return value. See API reference for per-method signatures.

snapshot.d.tsts

interface ContextuneSnapshot {
  event_log: EventLogEntry[];
  marketing_params?: MarketingParamsBlock; // present when context.extras.marketing !== false
  device_info?: DeviceInfoBlock;           // present when context.extras.device !== false
}

By default getSnapshot() returns this object. Pass { format: 'json' } for a JSON string, or { format: 'toon' } for a compact, token-optimised encoding suited to inline prompt injection — see the API reference.