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

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.

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

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

   Совет

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

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

   Пример кода:

   Ограничение

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

   <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 в необходимом для показа порядке.

   Kotlin

   Java

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

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

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

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

   Kotlin

   Java

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

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

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

   Совет

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

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

   Kotlin

   Java

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

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

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

   Kotlin

   Java

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

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

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

   Kotlin

   Java

   override fun onInstreamAdBreakCompleted() {
       handleAdBreakCompleted()
   }
   
   override fun onInstreamAdBreakError(reason: String) {
       handleAdBreakCompleted()
   }
   
   private fun handleAdBreakCompleted() {
       currentInroll = null
       contentVideoPlayer?.resumeVideo()
   }
   

   @Override
   public void onInstreamAdBreakCompleted() {
       handleAdBreakCompleted();
   }
   
   @Override
   public void onInstreamAdBreakError(@NonNull final String reason) {
       handleAdBreakCompleted();
   }
   
   private void handleAdBreakCompleted() {
       currentInroll = null;
       if (contentVideoPlayer != null) {
           contentVideoPlayer.resumeVideo();
       }
   }
   

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

    Kotlin

    Java

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

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

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

    Kotlin

    Java

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

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