createSession(options) → Session
Creates an ad session tied to a specific user and conversation.
Unique identifier that remains the same for the user’s lifetime (used for personalization, frequency capping, and rewarded ads).
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.
session.render(options) → Ad
Convenience wrapper for createAd + mount in one call.
session.updateOptions(partial)
Live-update preload-scoped configuration on an active session. Accepted fields: variantId, regulatory, userEmail, advertisingId, vendorId. 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.