Skip to main content

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.

​
KontextAds.createSession(...)

public fun createSession(context: Context, options: SessionOptions): Session
Returns a new Session configured from the given SessionOptions. Fires /init in the background. Pass context.applicationContext so the session is not tied to any single Activity.

​
SessionOptions

​
publisherToken
String
required
Your unique publisher token.
​
userId
String
required
Stable identifier for the end user. Used for personalization, frequency capping, and rewarded ads.
​
conversationId
String
required
Unique ID of the current conversation / chat thread.
​
enabledPlacementCodes
List<String>?
Placement codes to request ads for. Defaults to ["inlineAd"] when null or empty.
​
adServerUrl
String?
Override for the ad-server base URL. Leave null to use Kontext’s production endpoint.
​
character
Character?
AI character metadata for contextual targeting.
​
variantId
String?
Publisher-defined cohort identifier (e.g. for A/B testing).
​
regulatory
Regulatory?
Privacy / consent signals. TCF (gdpr / gdprConsent) is collected automatically if a TCF-compliant CMP is integrated — set manually only for COPPA, GPP, or US Privacy.
​
userEmail
String?
End-user email for frequency-cap deduplication.
​
advertisingId
String?
GAID you collected yourself. Takes priority over the SDK’s automatic collection.
​
onEvent
(AdEvent) -> Unit
Callback invoked on every ad lifecycle event. Called on the main thread.
​
onDebugEvent
(String, Any?) -> Unit
Optional diagnostic stream — fires for every internal SDK event (preload start/end, iframe lifecycle, geometry updates, etc.). Useful during integration. Leave null in production.

​
Session

​
addMessage(message, options)
method
Append a Message to the conversation. Synchronous (not suspend). User messages trigger a debounced preload; assistant messages let the SDK link the matched ad to the placement.
session.addMessage(Message(id = "m1", role = Role.USER, content = "Hi"))
session.addMessage(
    Message(id = "m2", role = Role.USER, content = "Hi again"),
    AddMessageOptions(trackOnly = true),
)
When trackOnly = true, the preload is sent for analytics but no ad is generated.
​
createAd(messageId, options)
method
Returns an Ad for the given messageId. Idempotent — repeated calls with the same messageId + code + theme return the same Ad. Cache the result.
val ad = session.createAd("m2")
val sidebar = session.createAd("m2", AdOptions(code = "sidebar", theme = "dark"))
​
updateOptions(partial)
method
Live-update preload-scoped fields. See Guides → Live-updating session options.
​
destroy()
method
Tear down the session: cancel preloads, destroy ads, release WebView resources. Idempotent. close() is an alias (implements AutoCloseable).
​
events
SharedFlow<AdEvent>
Hot Flow that delivers the same events as onEvent. Useful for ViewModels and coroutine pipelines.
​
messages
List<Message>
Read-only snapshot of messages tracked by the session.
​
sessionId
UUID?
Server-assigned session ID. null until the first successful preload.
​
disabled
Boolean
true if the server has permanently disabled the session via the /init response (e.g. geo-restriction). Subsequent preloads are skipped.
​
destroyed
Boolean
true after destroy() is called.

​
MutablePublisherOptions

Subset of SessionOptions accepted by session.updateOptions(...). Every field is optional — non-null overwrites, null leaves unchanged.
​
variantId
String?
​
regulatory
Regulatory?
​
userEmail
String?
​
advertisingId
String?

​
Message

​
id
String
required
Unique message ID.
​
role
Role
required
Role.USER or Role.ASSISTANT.
​
content
String
required
Message text.
​
createdAt
Date
Defaults to Date().

​
AdOptions

​
code
String
Placement code. Defaults to "inlineAd".
​
theme
String?
UI theme hint forwarded to the ad iframe (e.g. "dark").

​
AddMessageOptions

​
trackOnly
Boolean
When true, the preload is still sent (for analytics) but no ad is generated for this message. Defaults to false.

​
UI

@Composable
public fun InlineAd(
    messageId: String,
    session: Session,
    code: String? = null,
    theme: String? = null,
    modifier: Modifier = Modifier,
)
Mounts the ad for the given messageId. Internally calls session.createAd(...), attaches a pooled WebView, and reports container geometry back to the iframe. Safe to compose in a LazyColumn — the underlying Ad and WebView survive recomposition and scroll-off-screen recycling. A second overload accepts a pre-resolved Ad directly: 
@Composable
public fun InlineAd(ad: Ad, modifier: Modifier = Modifier)

​
InlineAdView (View interop)

public class InlineAdView(context: Context) : FrameLayout {
    public var onHeightChange: ((Float) -> Unit)?
    public fun bind(messageId: String, session: Session, code: String? = null, theme: String? = null)
}
For apps not on Compose. Call bind(messageId, session) once after inflating; observe onHeightChange to resize the surrounding container (e.g. in a RecyclerView row).

​
AdEvent

AdEvent is a sealed class with one typed payload per case. Every case has a stable string identifier accessible via event.name.

​
AdEvent.Filled — wire name ad.filled

An ad was returned and linked to the placement.

​
AdEvent.NoFill — wire name ad.no-fill

No ad was returned for the placement (server skipped).

​
AdEvent.AdHeight — wire name ad.height

The ad iframe reported a new height. Use to size the surrounding container in RecyclerView rows. The InlineAd Compose composable handles this for you automatically.

​
AdEvent.Viewed — wire name ad.viewed

The ad was viewed by the user (IAB MRC viewability standard).

​
AdEvent.Clicked — wire name ad.clicked

The user clicked the ad.

​
AdEvent.RenderStarted — wire name ad.render-started

The first token of the ad content was received.

​
AdEvent.RenderCompleted — wire name ad.render-completed

Ad content streaming finished.

​
AdEvent.Error — wire name ad.error

The SDK encountered an error while serving an ad.

​
AdEvent.VideoStarted — wire name video.started

​
AdEvent.VideoCompleted — wire name video.completed

​
AdEvent.RewardGranted — wire name reward.granted

Fired for rewarded-ad flows after the user qualifies for a reward.