Documentation Index
Fetch the complete documentation index at: https://docs.kontext.so/llms.txt
Use this file to discover all available pages before exploring further.
createSession(options) → Session
Creates an ad session tied to a specific user and conversation.
Your unique publisher token.
Unique identifier that remains the same for the user’s lifetime (used for personalization, frequency capping, and rewarded ads).
Unique ID of the conversation or chat thread.
Placement codes enabled for the conversation. Defaults to
['inlineAd'].Character metadata used for contextual ad selection and personalization.
Privacy / consent signals.
Email of the user, used for frequency-cap deduplication.
Publisher-provided identifier for the user cohort (for A/B testing).
Callback invoked for every ad lifecycle event. See Supported events below.
Callback for SDK-internal diagnostic events. Receives
(name, data?) — useful when investigating preload/session behaviour during integration. Off by default.Session methods
session.addMessage(message, options?)
Register a chat message with the SDK. Triggers a debounced preload when appropriate.
See
Message shape.session.createAd(messageId, options?) → Ad
Create an Ad bound to a specific assistant message. Doesn’t wait for an ad — the ad will render as soon as one is available. Calling createAd twice for the same messageId + code returns the existing instance.
ID of the assistant message the ad belongs to.
session.render(options) → Ad
Convenience wrapper for createAd + mount in one call.
ID of the assistant message the ad belongs to.
Host element into which the ad iframe will be rendered.
Placement code (default:
'inlineAd').Visual theme.
session.updateOptions(partial)
Live-update preload-scoped configuration on an active session. Accepted fields: variantId, regulatory, userEmail. Read at the next /preload, so the change takes effect on the next user message — no session recreation needed.
session.destroy()
Cleans up internal state, cancels in-flight preloads, and stops further preload requests. Call this when the conversation ends or the page unmounts. After destroy(), mutator methods (addMessage, createAd, render) throw.
session.getSessionId() → string | null
Server-assigned session ID. null until the first successful /preload.
session.isDisabled() → boolean
true if the server has permanently disabled this session via the /init response (e.g. geo-restriction). Subsequent preloads are skipped.
session.isDestroyed() → boolean
true after destroy() has been called.
session.getMessages() → readonly Message[]
Snapshot of messages tracked by the session, in insertion order. Do not mutate; do not cache long-term — the internal array is replaced with a trimmed copy when message count exceeds the cap.
session.getPreloadTimeout() → number
Current /preload request timeout in milliseconds. May be overridden by the server via the /init response.
Ad methods
ad.mount(element)
Mounts the ad iframe inside the given DOM element. Each Ad instance can only be mounted once — re-mounting throws.
Host element for the ad iframe.
ad.destroy()
Removes the iframe from the DOM and releases all listeners. Idempotent — safe to call multiple times.
Message shape
Unique, stable ID of the message.
Role of the message author.
Message text.
Timestamp when the message was created.