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

# Guides

> Recipes beyond the first ad: loading several ads at once, your own auction, no-fill, the playhead, the next episode, the viewer.

## Loading several ads at once

To have several formats ready at once, ask for them and load them concurrently. Each format is requested and rendered in parallel, and one format without an ad leaves the others untouched:

```swift theme={null}
func prepare(_ format: AdFormat) async -> VideoAd? {
    do {
        let ad = try await ads.format(format)
        try await ad.load()
        ad.delegate = self
        return ad
    } catch {
        return nil                     // no fill for this format this time
    }
}

async let overlay = prepare(.overlay)
async let pause = prepare(.pause)
async let linear = prepare(.linear)
(overlayAd, pauseAd, linearAd) = await (overlay, pause, linear)
```

## Running your own auction

`VideoAd` carries the price before anything is rendered, so you can compare it with other networks and decide:

```swift theme={null}
let ad = try await ads.format(.pause)
if ad.price.value >= otherNetworkCPM {
    try await ad.load()
    pauseAd = ad
} else {
    try ad.reject(.outbid(winningPrice: otherNetworkCPM, winner: "Other network"))
}
```

`price.value` is a CPM in `price.currency`. `price.precision` says whether it is a DSP's clearing price (`.exact`) or a forecast for house demand (`.estimated`).

`reject` tells the server at once, and the server tells the advertiser its win produced no impression. Use `.outbid` when another network won on price, with the winning price and the network, so we can optimize our bids for your traffic; `.notUsed` (the default) for any other reason: the moment passed, the viewer left. Rejecting is optional; an ad you never use is settled when it expires or when you call `destroy()`.

## Handling no-fill

`format(_:)` throws `VideoAdError.noFill(reason:)` when the server has nothing for the format. It is not a failure and the SDK never retries by itself; ask again at a later moment.

```swift theme={null}
do {
    pauseAd = try await ads.format(.pause)
} catch VideoAdError.noFill(let reason) {
    switch reason {
    case .noAdMatch: break             // no campaign fits this episode or viewer right now
    case .geoRestricted: break         // no ads served in the viewer's country
    default: break                     // frequencyCap, contentUnsafe, temporaryError, …
    }
}
```

All of them mean the same for your code: no ad this time, ask again at the next moment. Log the reason if you want to see why fill is low.

## Giving the SDK the playhead

Every request and event carries where the viewer is in the episode. Give the SDK your player once the episode starts playing, in one of two ways.

With an `AVPlayer`, hand it over and the SDK reads its time whenever it needs it:

```swift theme={null}
ads.trackPlayhead(of: player)
```

With any other player, give a closure that returns the current position in seconds:

```swift theme={null}
ads.playheadProvider = { [weak self] in self?.player.currentTime ?? 0 }
```

Call either one when this episode starts playing, not when you create the `VideoAds`: until then the player's time belongs to the previous episode. Before that the SDK sends 0, which is right for a prefetch.

## The next episode

Create the next episode's `VideoAds` while the current one plays, prefetch its ads, and destroy the current one when the viewer leaves. Any number can be alive at once; the SDK keeps at most one ad on screen in the whole app.

```swift theme={null}
let next = VideoAds(content: nextEpisode)
Task { nextLinear = try? await next.format(.linear); try? await nextLinear?.load() }

// When the viewer moves on:
ads.destroy()
ads = next
ads.trackPlayhead(of: player)     // the player now plays the next episode
```

Call `trackPlayhead(of:)` when the episode actually starts in the player, not at creation: before that the player's time belongs to the previous episode.

## Who the viewer is

Set what you know on the shared instance; the next request carries it:

```swift theme={null}
KontextVideo.shared.user = .init(id: "user-1234", keywords: ["romance", "drama"])
KontextVideo.shared.regulatory = .init(coppa: false)
KontextVideo.shared.variantId = "B"     // for A/B tests agreed with Kontext
```


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