---
metadata:
  - name: generator
    content: Diplodoc Platform v5.52.0
alternate:
  - https://ads.yandex.com/helpcenter/en/dev/ios/instream-advanced.md
  - https://ads.yandex.com/helpcenter/ru/dev/ios/instream-advanced.md
  - https://ads.yandex.com/helpcenter/zh/dev/ios/instream-advanced.md
  - href: zh/dev/ios/instream-advanced.md
    type: text/markdown
    title: Markdown version
  - href: llms.txt
    type: text/markdown
    title: llms.txt
---
> **Documentation Index:** Fetch the complete configuration index at https://ads.yandex.com/helpcenter/zh/llms.txt

# 集成视频插播广告 API

 

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

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

{% note info %}

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

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

{% endnote %}

## 应用要求

* 使用 Xcode 16.4 或更高版本。

## 运作方式

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

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

{% list tabs %}

- 播放前/中/后贴片视频广告

   InstreamAdBinder 会跟踪主视频的播放进度，并根据 Yandex Advertising Network 界面中的视频资源设置显示广告插播时间点。

   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 容器中移除。

{% endlist %}

## 加载广告

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

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

3. 使用 `InstreamAdRequestConfiguration` 类为 `instreamAdRequestConfiguration` 请求创建配置。将来自 Yandex Advertising Network 界面的`Page ID` 作为请求参数传递。

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

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

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

## 呈现广告

{% list tabs %}

- 播放前/中/后贴片视频广告

   1. 实施 `InstreamAdPlayer` 和 `VideoPlayer` 接口。

      该参考资料提供了有关这些方法及其实施的详细信息。此外，请参阅 [测试实施示例](https://github.com/yandexmobile/yandex-ads-sdk-ios/tree/master/Examples/YandexMobileAdsExample/YandexMobileAdsExample)。

      {% note tip %}

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

      {% endnote %}

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

      {% note warning %}

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

      {% endnote %}

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

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

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

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

      ```swift
      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 开始自动跟踪主视频的播放进度并管理视频广告的播放方式。

      ```swift
      adBinder.bind(with: instreamAdView)
      ```

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

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

- 播放内贴片/暂停时视频广告

   {% note info %}

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

   {% endnote %}

   1. 实施 InstreamAdPlayer 接口。

      该参考资料提供了有关这些方法及其实施的详细信息。此外，请参阅 [测试实施示例](https://github.com/yandexmobile/yandex-ads-sdk-ios/tree/master/Examples/YandexMobileAdsExample/YandexMobileAdsExample)。

      {% note tip %}

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

      {% endnote %}

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

      {% note warning %}

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

      {% endnote %}

   3. 使用 InstreamAdLoader 通过来自 Yandex Advertising Network 界面的 `Page ID` 加载 InstreamAd 对象。
   4. InstreamAd 对象包含一组不同类型的广告插播。要获取内贴片广告插播，请使用 `InrollQueueProvider`。`InrollQueueProvider` 队列允许您按显示顺序接收内贴片广告对象。

      ```swift
      func instreamAdLoader(_ instreamAdLoader: InstreamAdLoader, didLoad ad:
      InstreamAd) {
          inrollQueue = InrollQueueProvider(ad: ad).queue()
      }
      ```
      
   5. 要启动接收的内贴片广告对象，您需要进行相应准备。未准备好的内贴片视频广告将不会启动。要跟踪内贴片视频广告准备情况，请设置 `InstreamAdBreakDelegate`，调用 `Inroll.prepare(with: adPlayer)`，并将 InstreamAdPlayer 实施的实例传递给它。

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

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

      {% note tip %}

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

      {% endnote %}

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

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

   8. 广告插播开始播放后，会调用 `InstreamAdBreakDelegate.instreamAdBreakDidStart()` 方法。调用此方法后，暂停主视频并隐藏其控件。
      ```swift
      func instreamAdBreakDidStart(_ adBreak: InstreamAdBreak) {
          contentVideoPlayer?.pauseVideo()
      }
      ```
   9. 播放广告插播后，继续播放主视频。视频广告可能会成功播放，也可能会失败。这两种情况都需要处理。
      ```swift
      func instreamAdBreakDidComplete(_ adBreak: InstreamAdBreak) {
          handleAdBreakCompleted()
      }
      func instreamAdBreakDidError(_ adBreak: InstreamAdBreak) {
          handleAdBreakCompleted()
      }
      private fun handleAdBreakCompleted() {
          currentInroll = null
          contentVideoPlayer?.resumeVideo()
      }
      ```
   10. 当前内贴片视频广告播放完毕后，在 InrollQueue 中针对下一个内贴片视频广告检查播放队列。

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

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

       ```swift
       deinit {
           currentInroll?.invalidate()
       }
       ```

{% endlist %}