The session emits events at every meaningful step of an ad’s life, from the moment the server responds toDocumentation Index
Fetch the complete documentation index at: https://docs.kontext.so/llms.txt
Use this file to discover all available pages before exploring further.
/preload through to the user clicking through. You subscribe via onEvent (or the platform-specific equivalent — a Combine publisher on Swift, a Flow on Kotlin, etc.) and react however your app needs.
This page lists every event in one place. For the exact API on a given platform, see the SDK pages.
Three stages, one stream
All events arrive on a single stream, but it helps to know which stage each one belongs to:- After
/preloadreturns — the SDK has decided whether an ad will be available for the current assistant message. Firesad.filled,ad.no-fill, orad.error. - While the ad renders — the iframe starts streaming content and finishes. Fires
ad.render-started,ad.render-completed, andad.height(when the iframe reports its size). - As the user interacts — fires
ad.viewedonce the MRC viewability standard is met,ad.clickedon tap-through, and (for video / rewarded creatives)video.started,video.completed,reward.granted.
Reference
| Event | Stage | When it fires | Key payload |
|---|---|---|---|
ad.filled | Preload | An ad was returned and linked to the current assistant message id. | code (placement), revenue |
ad.no-fill | Preload | Preload completed but the server returned no eligible ad. | skipCode — see Debugging for the full list |
ad.error | Any stage | Something went wrong during preload or render. | message, errCode |
ad.render-started | Render | First token of the streamed ad content arrived. | bid id |
ad.render-completed | Render | Last token of the streamed ad content arrived. | bid id |
ad.height | Render | The iframe reported a new height (use to size the surrounding container). | messageId, height |
ad.viewed | Interaction | MRC viewability standard met. Counts as an impression. | messageId, content, format, revenue |
ad.clicked | Interaction | User tapped or clicked the ad. | messageId, url, format, area |
video.started | Interaction | Video playback began. | bid id |
video.completed | Interaction | Video playback finished. | bid id |
reward.granted | Interaction | A rewarded-ad reward was earned by the user. | bid id |
Where to next
Displaying ads
Where these events come from in the rendering flow.
Pacing
What happens to events when you suppress ads for a turn.
Compliance
The OMID standard behind
ad.viewed and per-SDK certification status.Debugging
onDebugEvent and server-side debug forwarding for deeper insight.