Advanced integration (InStream API)

InstreamAdBreak API doesn't directly control the rendering of a video ad in PlayerView. Video ads must be played on the app side based on signals from player interfaces transmitted to InstreamAdBreak. In/Pause-Roll signals the start of playing an ad break by calling InstreamAdBreakEventListener.onInstreamAdBreakStarted() and the end by calling InstreamAdBreakEventListener.onInstreamAdBreakCompleted() or InstreamAdBreakEventListener.onInstreamAdBreakError().

When calling InstreamAdBreakEventListener.onInstreamAdBreakStarted() on the app side, it's necessary to hide the main video controls and pause the main video. On the ad SDK side, after calling the method, advertising controls are displayed inside the InstreamAdView container and the InstreamAdPlayer.playAd() method is called to start playing the video ad.

When calling InstreamAdBreakEventListener.onInstreamAdBreakCompleted() or InstreamAdBreakEventListener.onInstreamAdBreakError() on the app side, return the main video controls and resume playing the main video. On the ad SDK side, ad controls are removed from the InstreamAdView container before calling the methods.

To load a specific AdBreak for manual playback, you can load the ad using PAGE_ID and IMP_ID. This data is stored in the ad unit ID, which is formatted as R-V-PAGE_ID-IMP_ID.

1. Create an instance of the InstreamAdBreakLoader class.

2. Create a request using the InstreamAdBreakRequest.Builder class, passing the ad feed URL.

3. Load the ad using the InstreamAdBreakLoader.loadAd method.

Code example:

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){
        // ...
    }
});

1. Add InstreamAdView to the app layout. InstreamAdView must contain PlayerView to play video ads in.

   Sample code:

   Restriction

   A container must be at least 300dp x 160dp in size.

   <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>
   

2. Use InstreamAdLoader to load an InstreamAd object using the page ID (PAGE_ID) from the Boost interface. Alternatively, use InstreamAdLoader to load an InstreamAdBreak object using the ad break identifiers (PAGE_ID and IMP_ID).

3. The InstreamAd object contains a set of different types of ad breaks. To get In-roll ad breaks, filter the instreamAd.instreamAdBreaks collection by the InstreamAdBreakType.INROLL type.

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

4. To launch the received In-roll video ad, you need to prepare it. Unprepared In-roll video ads won't start.

   To prepare In-roll video ads, call InstreamAdBreak.prepare(). To track the status of the ad break, set 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();
       }
   }
   

5. Once the In-roll video ad is prepared, InstreamAdBreakEventListener.onInstreamAdBreakPrepared() is called. The prepared In-roll video ad is ready to play.

   Tip

   Play video ads in the order they're retrieved from the instreamAdBreaks collection. If the received In-roll video ads are played in a different order, this may lower your app's monetization.

6. To play the prepared In-roll video ad, call InstreamAdBreak.play() and pass InstreamAdView as a parameter.

   Kotlin

   Java

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

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

7. After the ad break starts playing, the InstreamAdBreakEventListener.onInstreamAdBreakStarted() method is called. After calling this method, pause the main video and hide its controls.

   Kotlin

   Java

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

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

8. Once the ad break is played, resume playing the main video. A video ad may play successfully or fail. Both situations need to be handled.

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

9. After the current In-roll video ad finishes playing, check the play queue for the next In-roll video ad in the 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);
       }
   }
   

10. When you stop using an In-roll video ad, reset its state.

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