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

# Ad lifecycle events

> Every event the SDK can emit — filled, no-fill, viewed, clicked, render-*, video.*, reward.granted — what triggers them and what to do with them.

The session emits events at every meaningful step of an ad's life, from the moment the server responds to `/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](/overview).

## Three stages, one stream

All events arrive on a single stream, but it helps to know which stage each one belongs to:

* **After `/preload` returns** — the SDK has decided whether an ad will be available for the current assistant message. Fires `ad.filled`, `ad.no-fill`, or `ad.error`.
* **While the ad renders** — the iframe starts streaming content and finishes. Fires `ad.render-started`, `ad.render-completed`, and `ad.height` (when the iframe reports its size).
* **As the user interacts** — fires `ad.viewed` once the MRC viewability standard is met, `ad.clicked` on 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](/guides/debugging#skipcode-reference) 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                                                                               |

The exact field names per platform live on the SDK pages — they all carry the same semantics, just under their language-native casing.

## Where to next

<CardGroup cols={2}>
  <Card title="Displaying ads" icon="window" href="/concepts/displaying-ads">
    Where these events come from in the rendering flow.
  </Card>

  <Card title="Pacing" icon="eye-slash" href="/concepts/pacing">
    What happens to events when you suppress ads for a turn.
  </Card>

  <Card title="Compliance" icon="eye" href="/resources/compliance">
    The OMID standard behind `ad.viewed` and per-SDK certification status.
  </Card>

  <Card title="Debugging" icon="bug" href="/guides/debugging">
    `onDebugEvent` and server-side debug forwarding for deeper insight.
  </Card>
</CardGroup>