> ## 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.

# 广告生命周期事件

> SDK 可能发出的全部事件——filled、no-fill、viewed、clicked、render-*、video.*、reward.granted——它们何时触发以及该如何响应。

会话会在广告生命周期的每一个关键节点上发出事件：从服务端响应 `/preload` 的那一刻，一直到用户点击为止。你通过 `onEvent`（或各平台等价的接口——Swift 上是 Combine publisher，Kotlin 上是 `Flow`，等等）订阅这些事件，然后按自己应用的需求作出响应。

本页把所有事件集中列出。各平台具体 API 见 [SDK 页面](/overview)。

## 三个阶段，同一条事件流

所有事件都从同一条流中发出，但按照它所属的阶段来理解会更清晰：

* **`/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`——完整列表见 [调试](/guides/debugging#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                                                |

各平台的具体字段名见对应的 SDK 页面——语义完全一致，只是按各语言的命名风格略有差异。

## 下一步

<CardGroup cols={2}>
  <Card title="展示广告" icon="window" href="/concepts/displaying-ads">
    这些事件在渲染流程中的位置。
  </Card>

  <Card title="节奏控制" icon="eye-slash" href="/concepts/pacing">
    抑制某一轮广告时，事件会发生什么变化。
  </Card>

  <Card title="合规" icon="eye" href="/resources/compliance">
    `ad.viewed` 背后的 OMID 标准与各 SDK 的认证状态。
  </Card>

  <Card title="调试" icon="bug" href="/guides/debugging">
    `onDebugEvent` 与服务端 debug 转发，可获得更深入的诊断信息。
  </Card>
</CardGroup>