---
metadata:
  - name: generator
    content: Diplodoc Platform v5.57.3
alternate:
  - https://boost.yandex.com/doc/en/ad-monetization/dev/ios/instream-advanced.md
  - https://boost.yandex.com/doc/ru/ad-monetization/dev/ios/instream-advanced.md
  - href: en/ad-monetization/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://boost.yandex.com/doc/en/llms.txt

# InStream API integration

The **InStream API** is an advanced API for setting up and managing ad loading and playing InStream ads. It lets you support playing any type of ad break and use your own implementation of a player. InStream ads consist of video ads that are played automatically and manually.

Use the InstreamAdBinder API to automatically play Pre-roll, Mid-roll, and Post-roll ad breaks. Use the InstreamAdBreak API to trigger ad breaks manually.

{% note info %}

You can use the InstreamAdBinder API and the InstreamAdBreak API concurrently under specific conditions:

1. Use different instances of the ad player.
2. Don't trigger playback using the InstreamAdBreak API while the main video is paused via the InstreamAdBinder API.
3. When using `InstreamAd` with the InstreamAdBreak API, use only `InstreamAdBreakType.inroll` or `InstreamAdBreakType.pauseroll` ad breaks. InstreamAdBinder automatically handles rendering for all other types.

{% endnote %}

## App requirements

* Use Xcode 16.4 or higher.

## How it works

A loaded InStream ad object contains a schedule for playing ad breaks. Each ad break is described by an InstreamAdBreak object. An ad break may have one of the following types: Pre / Mid / Post / In / Pause-roll. You can play Pre-/Mid-/Post-Roll ad breaks using the InstreamAdBinder API. You can display ad breaks manually, including Pause-roll and In-roll video ads, using the InstreamAdBreak API.

The `VideoPlayer` protocol is used to interact with the main video content. To play an ad break inside an ad placement, use the `InstreamAdPlayer` protocol.

{% list tabs %}

- Playing Pre/Mid/Post-Roll video ads

  InstreamAdBinder tracks the progress of playing the main video and automatically shows ad breaks based on their schedule from a video resource in the Boost interface.

  InstreamAdBinder does not directly control the rendering of a video ad in PlayerView. Video ads must be played on the app side based on signals from player interfaces transmitted to InstreamAdBinder. InstreamAdBinder signals the start of playing an ad break by calling `VideoPlayer.pauseVideo()` and the end by calling `VideoPlayer.resumeVideo()`.

  When calling `VideoPlayer.pauseVideo()` on the app side, it's necessary to hide the main video controls, pause the main video, and start playing the video ad. On the ad SDK side, after calling the method, advertising controls are displayed inside the InstreamAdView container and the InstreamAdPlayer.playAd() method is called to start playing the video ad.

  When calling `VideoPlayer.resumeVideo()` on the app side, it's necessary to return the main video controls and resume playing the main video. On the ad SDK side, ad controls inside the InstreamAdView container are removed before calling the method.

- Playing InstreamAdBreak

  InstreamAdBreak API doesn't directly control the rendering of a video ad in PlayerView. Video ads must be played on the app side based on signals from player interfaces transmitted to InstreamAdBreak. In/Pause-Roll signals the start of playing an ad break by calling `InstreamAdBreakDelegate.instreamAdBreakDidStart()` and the end by calling `InstreamAdBreakDelegate.instreamAdBreakDidComplete()` or `InstreamAdBreakDelegate.instreamAdBreakDidError()`.

  When calling `InstreamAdBreakDelegate.instreamAdBreakDidStart()` on the app side, it's necessary to hide the main video controls and pause the main video. On the ad SDK side, after calling the method, advertising controls are displayed inside the InstreamAdView container and the `InstreamAdPlayer.playAd()` method is called to start playing the video ad.

  When calling `InstreamAdBreakDelegate.instreamAdBreakDidComplete()` or `InstreamAdBreakDelegate.instreamAdBreakDidError()` on the app side, it's necessary to return the main video controls and resume playing the main video. On the ad SDK side, ad controls are removed from the InstreamAdView container before calling the methods.

{% endlist %}

## Loading ads

1. Create an instance of the `InstreamAdLoader` class to get InStream ads.

2. Configure your request using the `InstreamAdRequestConfiguration` class. Pass the `Page ID` from the Boost interface as a request parameter.

3. Load ads using the `loadInstreamAd(configuration:completion:)` method.

To test the integration, use the demo Page ID: `R-M-DEMO-instream-vmap`.

{% list tabs %}

- Swift Concurrency

  ```swift
  let adLoader = InstreamAdLoader()
  let configuration = InstreamAdRequestConfiguration(pageID: PAGE_ID)
  do {
      let ad = try await adLoader.loadInstreamAd(configuration: configuration)
      // Use the loaded InstreamAd object
  } catch {
      // Loading error
  }
  ```

- Completion handler

  ```swift
  let adLoader = InstreamAdLoader()
  let configuration = InstreamAdRequestConfiguration(pageID: PAGE_ID)
  adLoader.loadInstreamAd(configuration: configuration) { result in
      switch result {
      case .success(let ad):
          // Use the loaded InstreamAd object
          break
      case .failure(let info):
          // Load error: info.reason
          break
      }
  }
  ```

{% endlist %}

## Rendering ads

{% list tabs %}

- Playing Pre/Mid/Post-Roll video ads

  1. Implement the `InstreamAdPlayer` and `VideoPlayer` interfaces.

     The reference provides detailed information about the methods and their implementation. Additionally, see a [test implementation example](https://github.com/yandexmobile/yandex-ads-sdk-ios/tree/master/Examples/YandexMobileAdsExample/YandexMobileAdsExample).

     {% note tip %}

     To make implementation easier, we recommend using different instances of players to play video ads and content.

     {% endnote %}

  2. Add InstreamAdView to the View hierarchy of the app. InstreamAdView must contain PlayerView to play video ads in.

     {% note warning %}

     A container must be at least 300dp x 160dp in size.

     {% endnote %}

  3. Create an InstreamAdBinder object: pass the loaded `InstreamAd` object and the `InstreamAdPlayer` and `VideoPlayer` implementations to the builder.

     Set up notifications about the ad's progress (ready to play the video ad, the video ad played or failed to play): set a delegate that conforms to the `InstreamAdBinderDelegate` protocol.

     ```swift
     adBinder = InstreamAdBinder(ad: ad, adPlayer: adPlayer, videoPlayer:
     contentPlayer)
     adBinder.delegate = self
     ```
  4. To start playing a Pre-roll ad break faster, preload it in advance by calling the `InstreamAdBinder.prepareAd()` method.
     ```swift
     func preparePrerollAd(adBinder: InstreamAdBinder) {
         adBinder.delegate = self
         adBinder.prepareAd()
     }

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

     }
     ```
  5. Call the `InstreamAdBinder.bind(with adView: InstreamAdView)` method for the created InstreamAdBinder object. Pass `InstreamAdView`, which was previously added to the hierarchy, as a parameter. After that, the InStream SDK starts to automatically track the progress of playing the main video and manage the way video ads are played.
     ```swift
     adBinder.bind(with: instreamAdView)
     ```
  6. When playing InStream ads in the list, use the `InStreamBinder.unbind()` method when the cell with the ad is invalidated in the list. To implement a reused pool of players for scrolling, call `InstreamAdbinder.invalidateAdPlayer()` when reusing the ad player linked to InstreamAdBinder and `InstreamAdBinder.invalidateVideoPlayer()` when reusing the main content player.
  7. When you stop using InStreamAdBinder, reset the state.
     ```swift
     deinit {
         adBinder.unbind()
         adBinder.invalidateVideoPlayer()
         adBinder.invalidateAdPlayer()
     }
     ```

- Playing InstreamAdBreak

  {% note info %}

  You can configure playback of any ad break similar to In-roll video ads. When filtering ad breaks, simply replace `InstreamAdBreakType.inroll` with the type you need — for example, `InstreamAdBreakType.pauseroll`.

  {% endnote %}

  1. Implement the InstreamAdPlayer interface.

     The reference provides detailed information about the methods and their implementation. Additionally, see a [test implementation example](https://github.com/yandexmobile/yandex-ads-sdk-ios/tree/master/Examples/YandexMobileAdsExample/YandexMobileAdsExample).

     {% note tip %}

     To make implementation easier, we recommend using different instances of players to play video ads and content.

     {% endnote %}

  2. Add InstreamAdView to the View hierarchy of the app. InstreamAdView must contain PlayerView to play video ads in.

     {% note warning %}

     A container must be at least 300dp x 160dp in size.

     {% endnote %}

  3. Use the InstreamAdLoader to load the InstreamAd object using the `Page ID` from the Boost interface.
  4. InstreamAd contains a collection of various ad break types in its `adBreaks` property. To retrieve In-roll ad breaks, filter the array by `InstreamAdBreakType.inroll`. The breaks are returned in their intended playback order.

     ```swift
     adLoader.loadInstreamAd(configuration: configuration) { result in
         if case .success(let ad) = result {
             inrollQueue = ad.adBreaks.filter{ $0.adBreakData.type == InstreamAdBreakType.inroll }
         }
     }
     ```
  5. To launch the received In-roll object, you need to prepare it. Unprepared In-roll video ads won't start. To track if the In-Roll video ad is ready, set the `InstreamAdBreakDelegate`, call `Inroll.prepare(with: adPlayer)`, and pass an instance of the created InstreamAdPlayer implementation to it.

     ```swift
     private func prepareNextAd() {
         guard !inrollQueue.isEmpty else { return }
         currentAdBreak = inrollQueue.removeFirst()
         currentAdBreak?.delegate = self
         currentAdBreak?.prepare(with: adPlayer)
     }
     ```
  6. Once the In-roll video ad is prepared, `InstreamAdBreakDelegate.instreamAdBreakDidPrepare()` is called. The prepared In-roll video ad is ready to play.

     {% note tip %}

     Play video ads in the order they're received from the `adBreaks`. Playing ad breaks in a different order may reduce your app's revenue.

     {% endnote %}

  7. To display a ready ad break, call `InstreamAdBreak.play(with: adView)`, passing the InstreamAdView you've already added to your view hierarchy.
     ```swift
     func instreamAdBreakDidPrepare(_ adBreak: InstreamAdBreak) {
         currentAdBreak?.play(with: instreamAdView)
     }
     ```
  8. After the ad break starts playing, the `InstreamAdBreakDelegate.instreamAdBreakDidStart()` method is called. After calling this method, pause the main video and hide its controls.
     ```swift
     func instreamAdBreakDidStart(_ adBreak: InstreamAdBreak) {
         contentVideoPlayer?.pauseVideo()
     }
     ```
  9. Once the ad break is played, resume playing the main video. A video ad may play successfully or fail. Both situations need to be handled.
     ```swift
     func instreamAdBreakDidComplete(_ adBreak: InstreamAdBreak) {
         handleAdBreakCompleted()
     }
     func instreamAdBreakDidError(_ adBreak: InstreamAdBreak) {
         handleAdBreakCompleted()
     }
     private func handleAdBreakCompleted() {
         currentAdBreak = nil
         contentVideoPlayer?.resumeVideo()
     }
     ```
  10. When the current ad break ends, prepare the next one from the queue.
      ```swift
      private func prepareNextAd() {
          guard !inrollQueue.isEmpty else { return }
          currentAdBreak = inrollQueue.removeFirst()
          currentAdBreak?.delegate = self
          currentAdBreak?.prepare(with: adPlayer)
      }
      ```
  11. When you stop using an In-roll video ad, reset its state.
      ```swift
      deinit {
          currentAdBreak?.invalidate()
      }
      ```

{% endlist %}