集成视频插播广告 API

视频插播广告 API 是用于设置和管理视频插播广告加载和播放方式的 API。它允许您支持播放任何类型的广告插播：前贴片广告、中贴片广告、后贴片广告、内贴片广告和暂停时广告。

前贴片广告、中贴片广告和后贴片广告插播使用 InstreamAdBinder API 播放。要播放内贴片广告和暂停时广告插播，请分别使用内贴片广告 API 和暂停时广告 API。

备注

如果满足以下条件，您还可以同时使用 InstreamAdBinder API、内贴片广告 API 和暂停时广告 API：

  1. 使用广告播放器的不同实例。
  2. 如果主视频通过 InStreamAdBinder API 暂停，请勿启动 Pause-Roll 和 In-Roll API 来播放广告。

应用要求

  • 使用 Xcode 15 或更高版本。

运作方式

加载的视频插播广告对象包含播放广告插播的时间表。每个广告插播时间均由 InstreamAdBreak 对象描述。广告插播可能具有以下类型之一： 前贴片/中贴片/后贴片/内贴片/暂停时广告。您可以使用 InstreamAdBinder API 播放前/中/后贴片广告插播。要播放内贴片/暂停时广告插播，请分别使用 In-Roll API 和 Pause-Roll API。

VideoPlayer 协议用于与主视频内容进行交互。要在广告版位内播放广告插播，请使用 InstreamAdPlayer 协议。

InstreamAdBinder 跟踪主视频的播放进度，并根据合作伙伴界面中视频资源的时间表自动显示广告插播。

InstreamAdBinder 不直接控制 PlayerView 中视频广告的呈现。视频广告必须根据播放器接口传输到 InstreamAdBinder 的信号在应用端播放。InstreamAdBinder 通过调用 VideoPlayer.pauseVideo() 来发出播放广告插播的开始信号，并通过调用 VideoPlayer.resumeVideo() 来发出结束信号。

在应用端调用 VideoPlayer.pauseVideo() 时，需要隐藏主视频控件，暂停主视频，然后开始播放视频广告。在广告 SDK 端，调用该方法后，广告控件会显示在 InstreamAdView 容器内，并调用 InstreamAdPlayer.playAd() 方法开始播放视频广告。

在应用端调用 VideoPlayer.resumeVideo() 时，需要返回主视频控件并继续播放主视频。在广告 SDK 端，在调用该方法之前会移除 InstreamAdView 容器内的广告控件。

内贴片/暂停时广告 API 不直接控制 PlayerView 中视频广告的呈现。视频广告必须根据播放器接口传输到内贴片/暂停时广告的信号在应用端播放。内贴片/暂停时广告通过调用 InstreamAdBreakDelegate.instreamAdBreakDidStart() 来发出播放广告插播的开始信号，并通过调用 InstreamAdBreakDelegate.instreamAdBreakDidComplete() 或 InstreamAdBreakDelegate.instreamAdBreakDidError() 来发出结束信号。

在应用端调用 InstreamAdBreakDelegate.instreamAdBreakDidStart() 时，需要隐藏主视频控件并暂停主视频。在广告 SDK 端，调用该方法后，广告控件会显示在 InstreamAdView 容器内，并调用 InstreamAdPlayer.playAd() 方法开始播放视频广告。

在应用端调用 InstreamAdBreakDelegate.instreamAdBreakDidComplete() 或 InstreamAdBreakDelegate.instreamAdBreakDidError() 时，需要返回主视频控件并继续播放主视频。在广告 SDK 端，在调用该方法之前，广告控件会从 InstreamAdView 容器中移除。

加载广告

  1. 创建 InstreamAdLoader 类的实例以获取视频插播广告。

  2. 要获取通知（广告加载成功或失败并出现错误），请订阅广告加载事件。为此，请设置符合 InstreamAdLoaderDelegate 协议的委托。

  3. 使用 InstreamAdRequestConfiguration 类为 instreamAdRequestConfiguration 请求创建配置。将合作伙伴接口中的 Page ID 作为请求参数传递。

  4. 使用 InstreamAdLoader.loadInstreamAd 方法加载广告并将 instreamAdRequestConfiguration 传递给它。

要测试集成，请使用演示页面 ID：demo-instream-vmap-yandex。

adLoader = InstreamAdLoader()
adLoader.delegate = self
let configuration = InstreamAdRequestConfiguration(pageID: PAGE_ID)
adloader.loadInstreamAd(configuration: configuration)

呈现广告

  1. 实施 InstreamAdPlayer 和 VideoPlayer 接口。

    该参考资料提供了有关这些方法及其实施的详细信息。此外，请参阅 测试实施示例。

    提示

    为了使实施更容易，我们建议使用不同的播放器实例来播放视频广告和内容。

  2. 将 InstreamAdView 添加到应用的视图层次结构中。InstreamAdView 必须包含 PlayerView 才能在其中播放视频广告。

    重要

    容器的尺寸必须至少为 300dp x 160dp。

  3. 创建一个 InstreamAdBinder 对象：将加载的 InstreamAd 对象以及 InstreamAdPlayer 和 VideoPlayer 实施传递给构建器。

    设置有关广告进度的通知（准备播放视频广告、视频广告已播放或播放失败）：设置符合 InstreamAdBinderDelegate 协议的委托。

    adBinder = InstreamAdBinder(ad: ad, adPlayer: adPlayer, videoPlayer:
contentPlayer)
adBinder.delegate = self

  4. 要更快地开始播放前贴片广告插播，请通过调用 InstreamAdBinder.prepareAd() 方法提前预加载广告。

    func preparePrerollAd(adBinder: InstreamAdBinder) {
    adBinder.delegate = self
    adBinder.prepareAd()
}

extension InstreamViewController: InstreamAdBinderDelegate {
    func instreamAdBinder(_ binder: InstreamAdBinder, didPrepare instreamAd: InstreamAd) {
        addInstreamAdBinderToPreloadedAdQueue(binder)
    }
    //...

}

  5. 调用 InstreamAdBinder.bind(with adView: InstreamAdView) 方法，用于创建 InstreamAdBinder 对象。将之前添加到层次结构中的 InstreamAdView 作为参数传递。之后，视频插播广告 SDK 开始自动跟踪主视频的播放进度并管理视频广告的播放方式。

    adBinder.bind(with: instreamAdView)

  6. 在播放列表中的视频插播广告时，当列表中包含广告的单元格失效时，请使用 InStreamBinder.unbind() 方法。要实施滚动的播放器重用池，请在重用链接到 InstreamAdBinder 的广告播放器时调用 InstreamAdbinder.invalidateAdPlayer()，在重用主内容播放器时调用 InstreamAdBinder.invalidateVideoPlayer()。

  7. 停止使用 InStreamAdBinder 时，请重置状态。

    deinit {
    adBinder.unbind()
    adBinder.invalidateVideoPlayer()
    adBinder.invalidateAdPlayer()
}

备注

设置播放暂停时广告插播与内贴片广告插播类似。为此，请将内贴片广告类/方法替换为暂停时广告类/方法。

  1. 实施 InstreamAdPlayer 接口。

    该参考资料提供了有关这些方法及其实施的详细信息。此外，请参阅 测试实施示例。

    提示

    为了使实施更容易，我们建议使用不同的播放器实例来播放视频广告和内容。

  2. 将 InstreamAdView 添加到应用的视图层次结构中。InstreamAdView 必须包含 PlayerView 才能在其中播放视频广告。

    重要

    容器的尺寸必须至少为 300dp x 160dp。

  3. 使用 InstreamAdLoader 通过合作伙伴界面中的 Page ID 加载 InstreamAd 对象。

  4. InstreamAd 对象包含一组不同类型的广告插播。要获取内贴片广告插播，请使用 InrollQueueProvider。InrollQueueProvider 队列允许您按显示顺序接收内贴片广告对象。

    func instreamAdLoader(_ instreamAdLoader: InstreamAdLoader, didLoad ad:
InstreamAd) {
    inrollQueue = InrollQueueProvider(ad: ad).queue()
}

  5. 要启动接收的内贴片广告对象，您需要进行相应准备。未准备好的内贴片视频广告将不会启动。要跟踪内贴片视频广告准备情况，请设置 InstreamAdBreakDelegate，调用 Inroll.prepare(with: adPlayer)，并将 InstreamAdPlayer 实施的实例传递给它。

    private func prepareNextAd() {
    currentInroll = inrollQueue?.poll()
    currentInroll?.delegate = self
    currentInroll?.prepare(with: adPlayer)
}

  6. 准备好内贴片视频广告后，将调用 InstreamAdBreakDelegate.instreamAdBreakDidPrepare()。准备好播放的内贴片视频广告已经就绪。

    提示

    按照从 InrollQueue 收到视频广告的顺序播放视频广告。如果接收的内贴片视频广告以不同的顺序播放，则可能会降低应用的变现能力。

  7. 要播放准备好的内贴片视频广告，请调用 Inroll.play(with adView: InstreamAdView) 并将之前添加到视图层次结构中的 InstreamAdView 作为参数传递。

    func instreamAdBreakDidPrepare(_ adBreak: InstreamAdBreak) {
    currentInroll?.play(instreamAdView)
}

  8. 广告插播开始播放后，会调用 InstreamAdBreakDelegate.instreamAdBreakDidStart() 方法。调用此方法后，暂停主视频并隐藏其控件。

    func instreamAdBreakDidStart(_ adBreak: InstreamAdBreak) {
    contentVideoPlayer?.pauseVideo()
}

  9. 播放广告插播后，继续播放主视频。视频广告可能会成功播放，也可能会失败。这两种情况都需要处理。

    func instreamAdBreakDidComplete(_ adBreak: InstreamAdBreak) {
    handleAdBreakCompleted()
}
func instreamAdBreakDidError(_ adBreak: InstreamAdBreak) {
    handleAdBreakCompleted()
}
private fun handleAdBreakCompleted() {
    currentInroll = null
    contentVideoPlayer?.resumeVideo()
}

  10. 当前内贴片视频广告播放完毕后，在 InrollQueue 中针对下一个内贴片视频广告检查播放队列。

    private func prepareNextAd() {
    currentInroll = inrollQueue?.poll()
    currentInroll?.delegate = self
    currentInroll?.prepare(with: adPlayer)
}

  11. 当您停止使用内贴片视频广告时，请重置其状态。

    deinit {
    currentInroll?.invalidate()
}
上一篇
视频插播广告
下一篇
开屏广告