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

# How it works

> From the request to the last event: what your app does, what the SDK does, and what our server does.

A video ad has three parties: your app, the SDK and the Kontext ad server. Your app asks and decides the moment; the SDK renders and tracks; the server runs the auction, hosts the creative and settles every bid with the advertiser.

## The flow

The diagram follows a pause ad. Overlay and linear ads go the same way; only the moment and the `show()` call differ.

```mermaid theme={null}
sequenceDiagram
    participant App as Your app
    participant SDK as Kontext Video SDK
    participant Server as Kontext ad server

    App->>SDK: initialize(publisherToken)
    SDK->>Server: configuration request
    Server-->>SDK: enabled

    Note over App,SDK: The episode opens
    App->>SDK: VideoAds(content), ads.format(.pause)
    SDK->>Server: ad request (content, player)
    Note over Server: auction across demand partners
    Server-->>SDK: the ad, with its price
    SDK-->>App: VideoAd (price)

    App->>SDK: ad.load()
    Note over SDK: renders the creative off screen
    SDK-->>App: ready

    Note over App,SDK: The viewer pauses
    App->>SDK: ad.show(in: playerView)
    SDK->>Server: impression, viewability, clicks, completion
    Note over SDK: the viewer closes or resumes
    SDK-->>App: didEnd(reason)
```

1. **Initialize once at launch.** `initialize(with:)` stores your token and sends a configuration request in the background. Nothing waits on it; ads requests made meanwhile queue behind it.
2. **Create the video's ads.** One `VideoAds` per episode, with what you know about it. Creating it sends nothing.
3. **Ask for an ad.** `format(.pause)` sends a request with the content and the player size and returns the pause ad. The server runs an auction across its demand partners and answers with an ad, or a no-fill reason.
4. **Look at the price, then load or reject.** The `VideoAd` carries its CPM before anything renders. `load()` renders the creative off screen and returns once it is ready to draw; `reject()` tells the server you won't use it.
5. **Show it at your moment.** `show(in: playerView)` puts the creative on screen inside your player view (overlay, pause); `show()` presents it full screen (linear). From here the SDK owns the ad: it counts the impression, measures viewability, tracks every interaction, and hands you one `didEnd`.
6. **The server settles with the advertiser.** Every event goes to our server, which reports to the advertiser and bills. An ad you never show is settled too, as not used, when you reject it, destroy the `VideoAds`, or it expires.

## What you provide and what the SDK handles

| You provide | The SDK handles |
| - | - |
| `publisherToken`, once at launch | Initialization, every ads request, retries after a failed launch |
| One `VideoAds` per episode, with the content's metadata | Device, app, consent and identity signals on every request |
| The moment: `format()` early, `show()` when it fits | One request at a time, one unshown ad per format, expiry |
| The view your content plays in (overlay, pause) | Placement, sizing, scaling, the pass-through for taps around the ad |
| Your own auction, if you run one: compare the price, `reject` if you lose | Telling the advertiser, with the winning price and winner |
| `didEnd`: resume your content | Impression, viewability, clicks, quartiles, the not-used notice |
| `destroy()` when the viewer leaves | Releasing what the ads held, ending the ad on screen, settling held ads |

## Where the creative lives

Our server hosts every ad's creative, and the SDK renders it isolated from your app: the advertiser's code never runs in your app, a tap opens a URL only after a real touch, and the SDK does all the tracking.

## Where to next

> **[Ad formats](https://docs.kontext.so/video/concepts/ad-formats.md)**
>
> Overlay, pause and linear: where they appear, how big, how they end.

> **[Ad lifecycle](https://docs.kontext.so/video/concepts/lifecycle.md)**
>
> What the SDK holds, when it lets go, and the one callback you implement.

> **[Targeting](https://docs.kontext.so/video/concepts/targeting.md)**
>
> What to send so ads match the episode and the viewer.

> **[Swift Video SDK](https://docs.kontext.so/video/sdk/swift.md)**
>
> The 10-minute integration.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.