createSession(options) → Session
Creates an ad session tied to a specific user and conversation.
string
required
Your unique publisher token.
string
required
Unique identifier that remains the same for the user’s lifetime (used for personalization, frequency capping, and rewarded ads).
string
required
Unique ID of the conversation or chat thread.
string[]
Placement codes enabled for the conversation. Defaults to
['inlineAd'].object
Character metadata used for contextual ad selection and personalization.
object
Privacy / consent signals.
string
Email of the user, used for frequency-cap deduplication.
string
Publisher-provided identifier for the user cohort (for A/B testing).
function
Callback invoked for every ad lifecycle event. See Supported events below.
function
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.
Message
required
See
Message shape.object
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.
string
required
ID of the assistant message the ad belongs to.
object
session.render(options) → Ad
Convenience wrapper for createAd + mount in one call.
string
required
ID of the assistant message the ad belongs to.
HTMLElement
required
Host element into which the ad iframe will be rendered.
string
Placement code (default:
'inlineAd').string
Visual theme.
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.
HTMLElement
required
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
string
required
Unique, stable ID of the message.
'user' | 'assistant'
required
Role of the message author.
string
required
Message text.
Date
required
Timestamp when the message was created.