高级集成（视频插播广告 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 对象包含一组不同类型的广告插播。要获取内贴片广告插播，请使用 InrollQueueProvider。InrollQueueProvider 队列允许您按显示顺序接收内贴片广告对象。

   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. 要启动接收的内贴片视频广告，您需要进行相应准备。未准备好的内贴片视频广告将不会启动。

   要准备内贴片视频广告，请调用接口 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. 准备好内贴片视频广告后，将调用 InstreamAdBreakEventListener.onInstreamAdBreakPrepared()。准备好播放的内贴片视频广告已经就绪。

   提示

   按照从 InstreamAdBreakQueue 收到视频广告的顺序播放广告。如果接收的内贴片视频广告以不同的顺序播放，则可能会降低应用的变现能力。

7. 要播放准备好的内贴片视频广告，请调用 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. 当前内贴片视频广告播放完毕后，在 InstreamAdBreakQueue 中针对下一个内贴片视频广告检查播放队列。

    Kotlin

    Java

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

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

11. 当您停止使用内贴片视频广告时，请重置其状态。

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