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

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

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

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

Если вы хотите загрузить конкретный AdBreak для ручного воспроизведения, вы можете загрузить рекламу используя PAGE_ID и IMP_ID. эти данные хранятся в блоке формата R-V-PAGE_ID-IMP_ID

1. Создайте экземпляр класса InstreamAdBreakLoader.

2. Создайте запрос с помощью класса InstreamAdBreakRequest.Builder, передав URL рекламного фида.

3. Загрузите рекламу с помощью метода InstreamAdBreakLoader.loadAd.

Пример кода:

val instreamAdBreakLoader = InstreamAdBreakLoader(this)
val instreamAdBreakRequest = InstreamAdBreakRequest.Builder(PAGE_ID, IMP_ID).build()
instreamAdBreakLoader.loadAd(instreamAdBreakRequest, object : InstreamAdBreakLoadListener {
    override fun onAdLoaded(instreamAdBreak: InstreamAdBreak) {
        // ...
    }

    override fun onAdFailedToLoad(error: InstreamAdBreakRequestError) {
        // ...
    }
})

final InstreamAdBreakLoader instreamAdBreakLoader = new InstreamAdBreakLoader(context);
final InstreamAdBreakRequest instreamAdBreakRequest =
    new InstreamAdBreakRequest.Builder(PAGE_ID, IMP_ID).build();
instreamAdBreakLoader.loadAd(instreamAdBreakRequest, new InstreamAdBreakLoadListener() {
    @Override
    public void onAdLoaded(@NonNull final InstreamAdBreak instreamAdBreak) {
        // ...
    }

    @Override
    public void onAdFailedToLoad(@NonNull final InstreamAdBreakRequestError error) {
        // ...
    }
});

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) из интерфейса Рекламной сети Яндекса или объект InstreamAdBreak через InstreamAdLoader с помощью идентификаторов рекламной вставки (PAGE_ID и IMP_ID).

4. InstreamAd содержит в себе набор рекламных вставок разных типов. Чтобы получить рекламные вставки In-roll, отфильтруйте коллекцию instreamAd.instreamAdBreaks по типу InstreamAdBreakType.INROLL.

   Kotlin

   Java

   fun onInstreamAdLoaded(instreamAd: InstreamAd) {
       instreamAdBreaks = instreamAd.instreamAdBreaks.filter {
           it.adBreakData.type == InstreamAdBreakType.INROLL
       }
   }
   

   public void onInstreamAdLoaded(@NonNull final InstreamAd instreamAd) {
       mInstreamAdBreaks = new ArrayList<>();
       for (InstreamAdBreak adBreak : instreamAd.getInstreamAdBreaks()) {
           if (adBreak.getAdBreakData().getType() == InstreamAdBreakType.INROLL) {
               mInstreamAdBreaks.add(adBreak);
           }
       }
   }
   

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

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

   Kotlin

   Java

   fun prepare() {
       currentInroll = instreamAdBreaks.getOrNull(currentIndex++)?.apply {
           setListener(InrollListener())
           prepare()
       }
   }
   

   public void prepare() {
       if (mCurrentIndex < mInstreamAdBreaks.size()) {
           currentInroll = mInstreamAdBreaks.get(mCurrentIndex++);
           currentInroll.setListener(new InrollListener());
           currentInroll.prepare();
       }
   }
   

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

   Совет

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

7. Чтобы показать подготовленный In-roll, вызовите InstreamAdBreak.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 = instreamAdBreaks.getOrNull(currentIndex++)
        currentInroll?.let { prepareInroll(it) }
    }
    

    public void prepareNextAd() {
        if (mCurrentIndex < mInstreamAdBreaks.size()) {
            currentInroll = mInstreamAdBreaks.get(mCurrentIndex++);
            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();
    }