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

# 调试

> 用 onEvent 处理广告生命周期事件，用 onDebugEvent 获取详细的内部日志。

SDK 暴露了两个回调，按需选用。

## `onEvent` —— 公开的广告生命周期

`onEvent` 会触发**少量**公开的广告生命周期事件：`ad.filled`、`ad.no-fill`、`ad.viewed`、`ad.clicked`、`ad.error`，以及视频和奖励相关事件。这些通常用来驱动你的 UI 与分析。

完整列表与 payload 见 [广告生命周期事件](/concepts/events)。

## `onDebugEvent` —— 详细的内部日志

`onDebugEvent` 会触发 SDK 内部的**每一个**步骤——预加载请求的开始与完成、message id 配对、重试尝试、iframe 加载里程碑等等。它内容非常多，且在 SDK 版本之间不保证稳定；请把它当作**诊断日志**使用，不要当作 API。

只在排查问题时打开它，之后在生产环境记得关掉：

```ts theme={null}
onDebugEvent: (name, data) => {
  console.log('[kontext]', name, data)
}
```

## 出现异常时

如果广告没有出现、触发了错误的事件、或 SDK 表现不符合预期：

1. 在你的构建中重新打开 `onDebugEvent`。
2. 复现问题。
3. 把完整的 `onDebugEvent` 输出发送给我们：[support@kontext.so](mailto:support@kontext.so)。

调试日志是我们在不远程接入的情况下，最快定位问题的方式。

## `skipCode` 参考

当 `ad.no-fill` 事件触发时，其 payload 会携带一个 `skipCode`，说明为何没有返回广告。可能出现的值：

| `skipCode`        | 含义                                                              | 该怎么做                              |
| ----------------- | --------------------------------------------------------------- | --------------------------------- |
| `ads_disabled`    | SDK 告知服务端本次请求的广告已禁用，因为你在调用 `addMessage` 时传入了 `trackOnly: true`。 | track-only 模式下属于预期行为。             |
| `ad_skipped`      | 服务端按规则主动跳过本轮——通常与 [节奏控制](/concepts/pacing) 有关。                  | 属于预期行为；下一个可投放的回合会展示广告。            |
| `ivt_blocked`     | 无效流量（IVT）检测拦截了该请求。                                              | 真实用户通常不会触发。若生产环境频繁出现，请联系 support。 |
| `unfilled_bid`    | 拍卖完成但没有竞价方返回可投广告。                                               | 偶发属于预期——填充率不可能恒为 100%。            |
| `illegal_content` | 对话内容被判定为不适合投放广告。                                                | 检查消息文本——某些类别不参与广告投放。              |
| `unknown`         | 暂未单独枚举的兜底代码。                                                    | 抓取 `onDebugEvent` 输出并发送给 support。 |