---
metadata:
  - name: generator
    content: Diplodoc Platform v5.50.6
alternate:
  - https://ads.yandex.com/helpcenter/en/dev/android7/instream-advanced.md
  - https://ads.yandex.com/helpcenter/ru/dev/android7/instream-advanced.md
---
> **Documentation Index:** Fetch the complete configuration index at https://ads.yandex.com/helpcenter/ru/llms.txt

<!--
Используется в Boost: boost/ru/ad-monetization/dev/android
-->

# Расширенная интеграция (InStream API)



**InStream API** — расширенный API для настройки, управления загрузкой и воспроизведением InStream-рекламы. Позволяет поддержать проигрывание всех типов рекламных вставок, а также использовать свою реализацию плеера. InStream-реклама состоит из рекламных вставок, которые проигрываются автоматически и вручную.

Для автоматического проигрывания вставок с типом Pre-roll, Mid-roll, Post-roll используется InstreamAdBinder API. Для ручного запуска рекламных вставок с типом In-roll и Pause-roll используются In-roll API и Pause-roll API соответственно.

{% note info %}

Доступно одновременное использование InstreamAdBinder API, In-roll API и Pause-roll API при соблюдении определенных условий:
1. Используйте разные инстансы рекламного плеера.
2. Не запускайте Pause-roll и In-roll API для воспроизведения, если через InStreamAdBinder API было приостановлено основное видео.

{% endnote %}

## Принципы работы

Загруженный объект InStream-рекламы содержит в себе расписание показа рекламных вставок. Каждая рекламная вставка описывается объектом InstreamAdBreak. Рекламная вставка может иметь один из следующих типов: Pre / Mid / Post / In / Pause-roll. Показать Pre / Mid / Post-Roll вставки можно через InstreamAdBinder API. Показать In / Pause-Roll вставки можно через In-roll API и Pause-roll API соответственно.

Для взаимодействия с основным видеоконтентом используется интерфейс VideoPlayer, а для воспроизведения рекламного видео внутри рекламной вставки — интерфейс InstreamAdPlayer.

{% list tabs %}

- Показ Pre / Mid / Post-Roll

  InstreamAdBinder отслеживает ход воспроизведения основного видео и показывает рекламные вставки на основе настроек видеоресурса в интерфейсе Рекламной сети Яндекса.

  InstreamAdBinder не управляет непосредственно отрисовкой рекламного видео в PlayerView. Воспроизводить рекламное видео необходимо со стороны приложения основываясь на сигналах от интерфейсов плееров, переданных в InstreamAdBinder. InstreamAdBinder сообщает о начале проигрывания рекламной вставки через вызов `VideoPlayer.pauseVideo()` и об окончании проигрывания рекламной вставки через вызов `VideoPlayer.resumeVideo()`.

  В момент вызова `VideoPlayer.pauseVideo()` со стороны приложения необходимо скрыть контролы управления основным видео, приостановить основное видео и начать воспроизведение рекламного видео. Со стороны рекламного SDK после вызова метода будут показаны рекламные контролы внутри контейнера `InstreamAdView` и будет вызван метод `InstreamAdPlayer.playAd()` для старта воспроизведения рекламного видео.

  В момент вызова `VideoPlayer.resumeVideo()` со стороны приложения необходимо вернуть контролы управления основным видео и продолжить воспроизведение основного видео. Со стороны рекламного SDK до вызова метода будут убраны рекламные контролы внутри контейнера `InstreamAdView`.

- Показ In / Pause-Roll

  In / Pause-Roll API не управляет непосредственно отрисовкой рекламного видео в PlayerView. Воспроизводить рекламное видео необходимо со стороны приложения основываясь на сигналах от интерфейсов плееров, переданных в In / Pause-Roll. In / Pause-Roll сообщает о начале проигрывания рекламной вставки через вызов `InstreamAdBreakEventListener.onInstreamAdBreakStarted()` и об окончании проигрывания рекламной вставки через вызов `InstreamAdBreakEventListener.onInstreamAdBreakCompleted()` или `InstreamAdBreakEventListener.onInstreamAdBreakError()`.

  В момент вызова `InstreamAdBreakEventListener.onInstreamAdBreakStarted()` со стороны приложения необходимо скрыть контролы управления основным видео, приостановить основное видео. Со стороны рекламного SDK после вызова метода будут показаны рекламные контролы внутри контейнера `InstreamAdView` и будет вызван метод `InstreamAdPlayer.playAd()` для старта воспроизведения рекламного видео.

  В момент вызова `InstreamAdBreakEventListener.onInstreamAdBreakCompleted()` или `InstreamAdBreakEventListener.onInstreamAdBreakError()` со стороны приложения необходимо вернуть контролы управления основным видео и продолжить воспроизведение основного видео. Со стороны рекламного SDK до вызова методов будут убраны рекламные контролы из контейнера `InstreamAdView`.

{% endlist %}

## Загрузка рекламных объявлений

1. Создайте экземпляр класса `InstreamAdLoader` для получения InStream-рекламы.

2. Настройте получение уведомлений (успешная загрузка рекламы или ошибка при загрузке рекламы): создайте экземпляр `InstreamAdLoadListener` и установите его в качестве слушателя событий загрузчика рекламных объявлений.

3. Создайте конфигурацию запроса `instreamAdRequestConfiguration` с помощью класса `InstreamAdRequestConfiguration.Builder`. В качестве параметров запроса передайте идентификатор страницы (`PAGE_ID`) из интерфейса Рекламной сети Яндекса.

4. Загрузите рекламу с помощью метода `InstreamAdLoader.loadInstreamAd`, передайте в него `Context` и `instreamAdRequestConfiguration`.

**Пример кода:**

Для тестирования корректности интеграции используйте демонстрационный PAGE_ID: `demo-instream-vmap-yandex`.

{% list tabs %}

   - Kotlin

     ```kotlin
     val instreamAdLoader = InstreamAdLoader(this)
     instreamAdLoader.setInstreamAdLoadListener(object : InstreamAdLoadListener {
         override fun onInstreamAdLoaded(instreamAd: InstreamAd) {
             // ...
         }

         override fun onInstreamAdFailedToLoad(reason: String) {
             // ...
         }
     })

     val instreamAdRequestConfiguration = InstreamAdRequestConfiguration.Builder(PAGE_ID).build()
     instreamAdLoader.loadInstreamAd(this, instreamAdRequestConfiguration)
     ```

   - Java

     ```java
     final InstreamAdLoader instreamAdLoader = new InstreamAdLoader(context);
     instreamAdLoader.setInstreamAdLoadListener(new InstreamAdLoadListener() {
             @override
             public void onInstreamAdLoaded(@NonNull final InstreamAd instreamAd) {
             // ...
             }

             @override
             public void onInstreamAdFailedToLoad(@NonNull final String reason) {
             // ...
             }
         });

     final InstreamAdRequestConfiguration instreamAdRequestConfiguration =
         new InstreamAdRequestConfiguration.Builder(PAGE_ID).build();
     instreamAdLoader.loadInstreamAd(this, instreamAdRequestConfiguration);
     ```
{% endlist %}

## Показ рекламных объявлений

{% list tabs %}

- Показ Pre / Mid / Post-Roll

  1. Реализуйте интерфейсы `InstreamAdPlayer` и `VideoPlayer`.

     В разделах справочника `Package com.yandex.mobile.ads.instream.player.ad` и `Package com.yandex.mobile.ads.instream.player.content` приведена подробная информация по работе методов и их реализации. Дополнительно рекомендуется ориентироваться на тестовый пример реализации.

     <!-- source: ru/dev/_includes7/instream-src.md -->
     {% note tip %}

     Для упрощения реализации, рекомендуется использовать разные инстансы плееров для воспроизведения рекламы и контентного видео.

     {% endnote %}
     <!-- endsource: ru/dev/_includes7/instream-src.md -->


  2. Добавьте в layout приложения InstreamAdView. InstreamAdView должна содержать в себе PlayerView, в которой будут проигрываться рекламные ролики.

     Пример кода:

     {% note info "Ограничение" %}

     Размер контейнера должен быть не меньше 300dp x 160dp.

     {% endnote %}

     ```xml
     <com.yandex.mobile.ads.instream.player.ad.InstreamAdView
         android:id="@+id/instream_ad_view"
         android:layout_width="match_parent"
         android:layout_height="wrap_content">

             <PlayerView
                 android:id="@+id/player_view"
                 android:layout_width="match_parent"
                 android:layout_height="wrap_content"/>

     </com.yandex.mobile.ads.instream.player.ad.InstreamAdView>
     ```
  3. Создайте объект `InstreamAdBinder`: передайте в конструктор Context, объект загруженной рекламы `InstreamAd` и реализации плееров `InstreamAdPlayer`, `VideoPlayer`.

     Настройте получение уведомлений о ходе воспроизведения рекламы (готовность к проигрыванию видеорекламы, завершение воспроизведения или ошибка в процессе воспроизведения): создайте экземпляр `InstreamAdListener` и установите его в качестве слушателя событий объекта `InstreamAdBinder`.

     {% list tabs %}

     - Kotlin

       ```kotlin
       instreamAdBinder = InstreamAdBinder(
           this,
           instreamAd,
           checkNotNull(instreamAdPlayer),
           checkNotNull(contentVideoPlayer)
       )
       instreamAdBinder.setInstreamAdListener(...)
       ```

     - Java

       ```java
       mInstreamAdBinder = new InstreamAdBinder(context, mInstreamAd, mYandexAdPlayer, mContentVideoPlayer);
       mInstreamAdBinder.setInstreamAdListener(...);
       ```

     {% endlist %}

  4. Для ускорения старта рекламной вставки с типом Pre-roll, заранее предзагрузите ее через вызов метода `InstreamAdBinder.prepareAd()`.

     {% list tabs %}

     - Kotlin

       ```kotlin
       private fun preparePrerollAd(instreamAdBinder: InstreamAdBinder) {
           instreamAdBinder.setInstreamAdListener(object : InstreamAdListener {
               // ...
               override fun onInstreamAdPrepared() {
                   addInstreamAdBinderToPreloadedAdQueue(instreamAdBinder)
               } // ...
           })
           instreamAdBinder.prepareAd()
       }
       ```

     - Java

       ```java
       private void preparePrerollAd(@NonNull final InstreamAdBinder instreamAdBinder) {
           instreamAdBinder.setInstreamAdListener(new InstreamAdListener() {
               // ...
               public void onInstreamAdPrepared() {
                   addInstreamAdBinderToPreloadedAdQueue(instreamAdBinder);
               }
               // ...
           });
           instreamAdBinder.prepareAd();
       }
       ```

     {% endlist %}

  5. Вызовите метод `InstreamAdBinder.bind(instreamAdView)` у созданного объекта `InstreamAdBinder`. В качестве параметра передайте `InstreamAdView`. После этого InStream SDK начнет автоматически отслеживать прогресс воспроизведения основного видео и возьмет на себя управление проигрыванием рекламных роликов.

     {% list tabs %}

     - Kotlin

       ```kotlin
       instreamAdBinder.bind(instreamAdView)
       ```

     - Java

       ```java
       mInstreamAdBinder.bind(mInstreamAdView);
       ```

     {% endlist %}

  6. При реализации проигрывания InStream-рекламы в списке, необходимо использовать метод `InStreamBinder.unbind()` при инвалидации ячейки с рекламой в списке. При реализации переиспользуемого пула плееров для скролла, необходимо вызывать `InstreamAdbinder.invalidateAdPlayer()` при переиспользовании плеера рекламы привязанного к `InstreamAdBinder`, а при переиспользовании плеера основного контента `InstreamAdBinder.invalidateVideoPlayer()`.

  7. При остановке использования `InStreamAdBinder` необходимо очищать состояние.

     {% list tabs %}

     - Kotlin

       ```kotlin
       override fun onDestroy() {
           instreamAdBinder.apply {
               unbind()
               instreamAdBinder.invalidateVideoPlayer()
               instreamAdBinder.invalidateAdPlayer()
               instreamAdBinder.setInstreamAdListener(null)
               instreamAdBinder.setVideoAdPlaybackListener(null)
           }

           super.onDestroy()
       }
       ```

     - Java

       ```java
       public void onDestroy() {
           instreamAdBinder.unbind();
           instreamAdBinder.invalidateVideoPlayer();
           instreamAdBinder.invalidateAdPlayer();
           instreamAdBinder.setInstreamAdListener(null);
           instreamAdBinder.setVideoAdPlaybackListener(null);

           super.onDestroy();
       }
       ```

     {% endlist %}

- Показ In / Pause-Roll

  {% note info %}

  Показ рекламной вставки Pause-roll настраивается по аналогии с In-roll. Для этого замените In-roll классы / методы на Pause-roll.

  {% endnote %}

  1. Реализуйте интерфейс InstreamAdPlayer.

     В разделе справочника `Package com.yandex.mobile.ads.instream.player.ad` приведена подробная информация по работе методов и их реализации. Дополнительно рекомендуется ориентироваться на тестовый пример реализации.

     <!-- source: ru/dev/_includes7/instream-src.md -->
     {% note tip %}

     Для упрощения реализации, рекомендуется использовать разные инстансы плееров для воспроизведения рекламы и контентного видео.

     {% endnote %}
     <!-- endsource: ru/dev/_includes7/instream-src.md -->
     

  2. Добавьте в layout приложения InstreamAdView. InstreamAdView должна содержать в себе PlayerView, в которой будут проигрываться рекламные ролики.

     Пример кода:

     {% note info "Ограничение" %}

     Размер контейнера должен быть не меньше 300dp x 160dp.

     {% endnote %}

     ```xml
     <com.yandex.mobile.ads.instream.player.ad.InstreamAdView
         android:id="@+id/instream_ad_view"
         android:layout_width="match_parent"
         android:layout_height="wrap_content">

             <PlayerView
                 android:id="@+id/player_view"
                 android:layout_width="match_parent"
                 android:layout_height="wrap_content"/>

     </com.yandex.mobile.ads.instream.player.ad.InstreamAdView>
     ```

  3. Загрузите через `InstreamAdLoader` объект `InstreamAd` с помощью идентификатора страницы (`PAGE_ID`) из интерфейса Рекламной сети Яндекса.

  4. InstreamAd содержит в себе набор рекламных вставок разных типов. Чтобы получить рекламные вставки In-roll, используйте `InrollQueueProvider`. Очередь `InrollQueueProvider` позволяет получать объекты In-roll в необходимом для показа порядке.

     {% list tabs %}

     - Kotlin

       ```kotlin
       fun onInstreamAdLoaded(instreamAd: InstreamAd) {
           val inrollQueueProvider = InrollQueueProvider(context, instreamAd)
           instreamAdBreakQueue = inrollQueueProvider.queue
       }
       ```

     - Java

       ```java
       public void onInstreamAdLoaded(@NonNull final InstreamAd instreamAd) {
           final InrollQueueProvider inrollQueueProvider = new InrollQueueProvider(context, instreamAd);
           mInstreamAdBreakQueue = inrollQueueProvider.getQueue();
       }
       ```

     {% endlist %}

  5. Для запуска полученного In-roll, необходимо его подготовить. Без подготовки In-roll не запустится.

     Чтобы подготовить In-roll, вызовите `Inroll.prepare(instreamAdPlayer)` интерфейса и передайте в него инстанс созданной реализации `InstreamAdPlayer`. Для отслеживания состояния рекламной вставки установите слушатель `InstreamAdBreakEventListener`.

     {% list tabs %}

     - Kotlin

       ```kotlin
       fun prepare(instreamAdPlayer: SampleInstreamAdPlayer) {
           currentInroll = instreamAdBreakQueue.poll()?.apply {
               setListener(InrollListener())
               instreamAdPlayer.let(::prepare)
           }
       }
       ```

     - Java

       ```java
       public void prepare(instreamAdPlayer) {
           currentInroll = mInstreamAdBreakQueue.poll();
           currentInroll.setListener(new InrollListener());
           currentInroll.prepare(instreamAdPlayer);
       }
       ```

     {% endlist %}

  6. По окончанию подготовки In-roll будет вызван `InstreamAdBreakEventListener.onInstreamAdBreakPrepared()`. Подготовленный In-roll готов к показу.

     {% note tip %}

     Показывайте объявления в порядке их получения из InstreamAdBreakQueue. Показ полученных In-roll в другом порядке может снизить монетизацию вашего приложения.

     {% endnote %}

  7. Чтобы показать подготовленный In-roll, вызовите `Inroll.play()` и передайте в качестве параметра `InstreamAdView`.

     {% list tabs %}

     - Kotlin

       ```kotlin
       fun onInstreamAdBreakPrepared() {
           currentInroll?.play(instreamAdView)
       }
       ```

     - Java

       ```java
       public void onInstreamAdBreakPrepared() {
           if (currentInroll != null) {
               currentInroll.play(instreamAdView);
           }
       }
       ```

     {% endlist %}

  8. После начала проигрывания рекламной вставки, будет вызван метод `InstreamAdBreakEventListener.onInstreamAdBreakStarted()`. По вызову этого метода необходимо поставить на паузу проигрывание основного видео и скрыть контролы управления основного видео.

     {% list tabs %}

     - Kotlin

       ```kotlin
       fun onInstreamAdBreakStarted() {
           contentVideoPlayer?.pauseVideo()
       }
       ```

     - Java

       ```java
       public void onInstreamAdBreakStarted() {
           if (contentVideoPlayer != null) {
               contentVideoPlayer.pauseVideo();
           }
       }
       ```

     {% endlist %}

  9. После проигрывания рекламной вставки необходимо продолжить воспроизведение основного видео. Проигрывание рекламной вставки может завершиться успешно или с ошибкой, эти две ситуации необходимо обрабатывать.

     {% list tabs %}

     - Kotlin

       ```kotlin
       override fun onInstreamAdBreakCompleted() {
           handleAdBreakCompleted()
       }

       override fun onInstreamAdBreakError(reason: String) {
           handleAdBreakCompleted()
       }

       private fun handleAdBreakCompleted() {
           currentInroll = null
           contentVideoPlayer?.resumeVideo()
       }
       ```

     - Java

       ```java
       @Override
       public void onInstreamAdBreakCompleted() {
           handleAdBreakCompleted();
       }

       @Override
       public void onInstreamAdBreakError(@NonNull final String reason) {
           handleAdBreakCompleted();
       }

       private void handleAdBreakCompleted() {
           currentInroll = null;
           if (contentVideoPlayer != null) {
               contentVideoPlayer.resumeVideo();
           }
       }
       ```

     {% endlist %}

  10. После завершения проигрывания текущего InRoll проверьте очередь воспроизведения на наличие следующего In-roll в `InstreamAdBreakQueue`.

      {% list tabs %}

      - Kotlin

        ```kotlin
        fun prepareNextAd() {
            currentInroll = mInstreamAdBreakQueue.poll()
            currentInroll?.prepareInroll(currentInroll)
        }
        ```

      - Java

        ```java
        public void prepareNextAd() {
            currentInroll = mInstreamAdBreakQueue.poll();
            if (currentInroll != null) {
                prepareInroll(currentInroll);
            }
        }
        ```

      {% endlist %}

  11. При остановке использования In-roll необходимо очищать его состояние.

      {% list tabs %}

      - Kotlin

        ```kotlin
        override fun onDestroy() {
            currentInroll?.apply {
                invalidate()
                setListener(null)
            }
            super.onDestroy()
        }
        ```

      - Java

        ```java
        public void onDestroy() {
            if (currentInroll != null) {
                currentInroll.invalidate();
                currentInroll.setListener(null);
            }
            super.onDestroy();
        }
        ```

      {% endlist %}

{% endlist %}