会话会在广告生命周期的每一个关键节点上发出事件：从服务端响应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.
/preload 的那一刻，一直到用户点击为止。你通过 onEvent（或各平台等价的接口——Swift 上是 Combine publisher，Kotlin 上是 Flow，等等）订阅这些事件，然后按自己应用的需求作出响应。
本页把所有事件集中列出。各平台具体 API 见 SDK 页面。
三个阶段，同一条事件流
所有事件都从同一条流中发出，但按照它所属的阶段来理解会更清晰：/preload返回之后 —— SDK 已决定当前助手消息是否会有可用的广告。会触发ad.filled、ad.no-fill或ad.error。- 广告渲染过程中 —— iframe 开始流式输出内容并完成。会触发
ad.render-started、ad.render-completed，以及ad.height（iframe 上报尺寸时）。 - 用户与广告交互时 —— 当满足 MRC 可见性标准时触发
ad.viewed，被点击时触发ad.clicked，对视频 / 奖励素材还会触发video.started、video.completed、reward.granted。
事件参考
| 事件 | 阶段 | 何时触发 | 关键 payload |
|---|---|---|---|
ad.filled | Preload | 服务端返回了广告，并已绑定到当前助手消息 id。 | code（placement）、revenue |
ad.no-fill | Preload | 预加载完成，但服务端没有返回符合条件的广告。 | skipCode——完整列表见 调试 |
ad.error | 任意阶段 | 预加载或渲染过程中出现错误。 | message、errCode |
ad.render-started | Render | 接收到流式广告内容的第一个 token。 | bid id |
ad.render-completed | Render | 接收到流式广告内容的最后一个 token。 | bid id |
ad.height | Render | iframe 上报了新的高度（用于调整外层容器尺寸）。 | messageId、height |
ad.viewed | Interaction | 满足 MRC 可见性标准。计为一次曝光。 | messageId、content、format、revenue |
ad.clicked | Interaction | 用户点击或轻触了广告。 | messageId、url、format、area |
video.started | Interaction | 视频开始播放。 | bid id |
video.completed | Interaction | 视频播放完成。 | bid id |
reward.granted | Interaction | 用户在激励广告流程中获得奖励。 | bid id |
下一步
展示广告
这些事件在渲染流程中的位置。
节奏控制
抑制某一轮广告时，事件会发生什么变化。
合规
ad.viewed 背后的 OMID 标准与各 SDK 的认证状态。调试
onDebugEvent 与服务端 debug 转发，可获得更深入的诊断信息。