展示第一个广告

这是 10 分钟集成。开始前请完成安装，确保 KontextVideo.shared.initialize(with:) 在启动时运行。每种格式都遵循同样的四个步骤：

VideoAds(content:)，对应观众正在看的视频。
ads.format() 向服务器请求并返回一个 VideoAd。
ad.load() 在屏幕外渲染素材，之后展示即时完成。或者 ad.reject()，如果你不会使用它。
在你选的时刻 ad.show()。结束时一个 didEnd 回调。

1. 创建视频的广告对象

每个视频（剧集）一个 VideoAds。创建它不发送任何请求。

import KontextVideoSDK

let content = KontextVideo.Content(
    id: "episode-1234",
    language: "en",
    title: "Episode 1",
    duration: 93,
    genre: "romance",
    series: .init(id: "series-42", title: "My Marionette Lover", episodeCount: 6)
)
let ads = VideoAds(content: content)

只有 id 和 language 是必填的；其余字段都能改善定向，有什么就发什么。告诉 SDK 内容在哪里播放，这样事件会带上内容播放位置：

ads.trackPlayhead(of: player)   // 你的 AVPlayer，这一集在其中播放后调用

如果播放器不是 AVPlayer，改为设置 ads.playheadProvider = { seconds }。

2. 获取广告

overlayAd = try await ads.format(.overlay)   // .pause 存入 pauseAd，.linear 存入 linearAd

format() 向服务器请求你传入的格式的广告。在剧集打开时就请求，而不是等到你想展示广告的那一刻：请求和加载需要一点时间，而广告应该立即出现。服务器没有广告时它抛出 VideoAdError.noFill(reason:)。这是正常的，不是故障；稍后再请求。

3. 加载它，或拒绝它

try await overlayAd?.load()
overlayAd?.delegate = self

load() 在屏幕外渲染素材，就绪后返回，所以 show() 是即时的。如果你决定不用这个广告，调用 try overlayAd?.reject()，广告主会收到通知。

4. 展示它

每种格式有自己的时刻和自己的 show()。

叠加
暂停
线性

剧集播放时，在你选的时刻出现在播放器上的一条条幅。几秒后它会自行消失。

func showOverlay() {
    try? overlayAd?.show(in: playerView)   // 你的视频播放所在的视图
}

想提前移除，对它调用 dismiss()。

观众暂停时出现的卡片或全屏广告。观众继续播放时移除它。

func viewerPaused() {
    player.pause()
    try? pauseAd?.show(in: playerView)   // 你的视频播放所在的视图
}

func viewerResumed() {
    try? pauseAd?.dismiss()
    player.play()
}

观众也可以点击全屏暂停广告上的恢复按钮；你在 didEnd 中恢复播放。

剧集之间、之前或之后的全屏视频。先暂停你的内容；广告由 SDK 自行呈现。

func showLinear() {
    guard let linearAd else { return }
    player.pause()
    do {
        try linearAd.show()              // 从最上层的视图控制器呈现；或 show(from: viewController)
    } catch {
        player.play()                    // 它从未出现，之后不会有任何回调
    }
}

你在 didEnd 中恢复内容。

show() 要么抛错且什么都没发生，要么广告已在屏幕上。从那以后由 SDK 运行它直到结束。

5. 响应结束

实现 VideoAdDelegate。每个方法都有空的默认实现；你需要的是 didEnd。每个已展示的广告它恰好到达一次，无论是谁结束了它，所以把恢复逻辑放在这里，别处不放，并从这里请求下一个广告，让它提前就绪。

叠加
暂停
线性

你的内容一直在播放，所以无需恢复。

extension PlayerController: VideoAdDelegate {
    func videoAd(_ ad: VideoAd, didEnd reason: VideoAd.EndReason) {
        overlayAd = nil
        // 提前准备下一个广告：format()，然后 load()
    }
}

观众点击全屏暂停广告上的恢复按钮时，在这里恢复播放。观众通过你自己的控件恢复时，viewerResumed() 已经处理了。

extension PlayerController: VideoAdDelegate {
    func videoAd(_ ad: VideoAd, didEnd reason: VideoAd.EndReason) {
        pauseAd = nil
        if reason == .resumed { player.play() }        // 观众点击了广告上的恢复按钮
        // 提前准备下一个广告：format()，然后 load()
    }
}

你的内容为广告暂停了；无论原因是什么，都恢复它。

extension PlayerController: VideoAdDelegate {
    func videoAd(_ ad: VideoAd, didEnd reason: VideoAd.EndReason) {
        linearAd = nil
        player.play()
        // 提前准备下一个广告：format()，然后 load()
    }
}

6. 清理

观众离开视频时调用 destroy()。它丢弃所有持有的广告，告诉服务器哪些没有被使用，并结束屏幕上的那个。

ads.destroy()

完整代码

每集一个控制器。选择与你的格式对应的标签页：

叠加
暂停
线性

@MainActor
final class PlayerController: VideoAdDelegate {
    let player: AVPlayer
    let playerView: UIView
    let ads: VideoAds
    var overlayAd: VideoAd?

    init(content: KontextVideo.Content, player: AVPlayer, playerView: UIView) {
        self.player = player
        self.playerView = playerView
        ads = VideoAds(content: content)
        ads.trackPlayhead(of: player)
        Task { await prepare() }
    }

    func prepare() async {
        do {
            let ad = try await ads.format(.overlay)
            try await ad.load()
            ad.delegate = self
            overlayAd = ad
        } catch {
            // 这次无填充；在下一个时刻再请求
        }
    }

    func showOverlay() {                         // 你选的时刻
        try? overlayAd?.show(in: playerView)
    }

    func videoAd(_ ad: VideoAd, didEnd reason: VideoAd.EndReason) {
        overlayAd = nil
        Task { await prepare() }
    }

    func leave() {
        ads.destroy()
    }
}

@MainActor
final class PlayerController: VideoAdDelegate {
    let player: AVPlayer
    let playerView: UIView
    let ads: VideoAds
    var pauseAd: VideoAd?

    init(content: KontextVideo.Content, player: AVPlayer, playerView: UIView) {
        self.player = player
        self.playerView = playerView
        ads = VideoAds(content: content)
        ads.trackPlayhead(of: player)
        Task { await prepare() }
    }

    func prepare() async {
        do {
            let ad = try await ads.format(.pause)
            try await ad.load()
            ad.delegate = self
            pauseAd = ad
        } catch {
            // 这次无填充；在下一个时刻再请求
        }
    }

    func viewerPaused() {
        player.pause()
        try? pauseAd?.show(in: playerView)
    }

    func viewerResumed() {
        try? pauseAd?.dismiss()
        player.play()
    }

    func videoAd(_ ad: VideoAd, didEnd reason: VideoAd.EndReason) {
        pauseAd = nil
        if reason == .resumed { player.play() }   // 观众点击了广告上的恢复按钮
        Task { await prepare() }
    }

    func leave() {
        ads.destroy()
    }
}

@MainActor
final class PlayerController: VideoAdDelegate {
    let player: AVPlayer
    let playerView: UIView
    let ads: VideoAds
    var linearAd: VideoAd?

    init(content: KontextVideo.Content, player: AVPlayer, playerView: UIView) {
        self.player = player
        self.playerView = playerView
        ads = VideoAds(content: content)
        ads.trackPlayhead(of: player)
        Task { await prepare() }
    }

    func prepare() async {
        do {
            let ad = try await ads.format(.linear)
            try await ad.load()
            ad.delegate = self
            linearAd = ad
        } catch {
            // 这次无填充；在下一个时刻再请求
        }
    }

    func showLinear() {                          // 你选的时刻
        guard let linearAd else { return }
        player.pause()
        do { try linearAd.show() } catch { player.play() }
    }

    func videoAd(_ ad: VideoAd, didEnd reason: VideoAd.EndReason) {
        linearAd = nil
        player.play()
        Task { await prepare() }
    }

    func leave() {
        ads.destroy()
    }
}

入门

核心概念

实践指南

SDK

资源

1. 创建视频的广告对象

2. 获取广告

3. 加载它，或拒绝它

4. 展示它

5. 响应结束

6. 清理

完整代码

​1. 创建视频的广告对象

​2. 获取广告

​3. 加载它，或拒绝它

​4. 展示它

​5. 响应结束

​6. 清理

​完整代码

1. 创建视频的广告对象

2. 获取广告

3. 加载它，或拒绝它

4. 展示它

5. 响应结束

6. 清理

完整代码