高级集成（视频插播广告 API）

内贴片/暂停时广告 API 不直接控制 PlayerView 中视频广告的呈现。视频广告必须根据播放器接口传输到内贴片/暂停时广告的信号在应用端播放。内贴片/暂停时广告通过调用 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. 将 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 通过合作伙伴界面中的 Page_ID 加载 InstreamAd 对象。

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. 当前 In-roll 视频广告播放完毕后，在 InstreamAdBreakQueue 中针对下一个 In-roll 视频广告检查播放队列。

    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();
    }