Guides

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:

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:

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.

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:

ads.trackPlayhead(of: player)

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

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.

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:

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

Get Started

Concepts

SDKs

Resources

Guides

Loading several ads at once

Running your own auction

Handling no-fill

Giving the SDK the playhead

The next episode

Who the viewer is

​Loading several ads at once

​Running your own auction

​Handling no-fill

​Giving the SDK the playhead

​The next episode

​Who the viewer is

Loading several ads at once

Running your own auction

Handling no-fill

Giving the SDK the playhead

The next episode

Who the viewer is