Advanced integration (InStream API)

Warning.

This is an archived version of the documentation. Actual documentation for all platforms can be found here.

  1. How it works
  2. Loading ads
  3. Rendering ads

The InStream API is an advanced API for setting up and managing ad loading and playing InStream ads. It lets you support playing any type of ad break and use your own implementation of a player. InStream ads consist of ad breaks that play automatically and manually.

Pre-Roll, Mid-Roll, and Post-Roll ad breaks are played automatically using the InstreamAdBinder API. To play In-Roll and Pause-Roll ad breaks manually, use the In-Roll API and Pause-Roll API, respectively.

Note.
You can also use the InstreamAdBinder API, In-Roll API, and Pause-Roll API concurrently if you:
  1. Use different instances of the ad player.
  2. Don't start the Pause-Roll and In-Roll APIs for playing ads if the main video was paused using the InStreamAdBinder API.

How it works

A loaded InStream ad object contains a schedule for playing ad breaks. Each ad break is described by an InstreamAdBreak object. An ad break may have one of the following types: Pre/Mid/Post/In/Pause-Roll. You can play Pre/MidPost-Roll ad breaks using the InstreamAdBinder API. To play In/Pause-Roll ad breaks, use the In-Roll API and Pause-Roll API, respectively.

The VideoPlayer interface is used to interact with the main video content. To play an ad break inside an ad placement, use the InstreamAdPlayer interface.

InstreamAdBinder tracks the progress of playing the main video and shows ad breaks based on the video resource settings in the Partner interface.

InstreamAdBinder does not 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 InstreamAdBinder. InstreamAdBinder signals the start of playing an ad break by calling VideoPlayer.pauseVideo() and the end by calling VideoPlayer.resumeVideo().

When calling VideoPlayer.pauseVideo() on the app side, it's necessary to hide the main video controls, pause the main video, and start playing the video ad. 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 VideoPlayer.resumeVideo() on the app side, it's necessary to return the main video controls and resume playing the main video. On the ad SDK side, ad controls inside the InstreamAdView container are removed before calling the method.

Loading ads

  1. Create an instance of the InstreamAdLoader class to get InStream ads.

  2. Set up notifications (ad loaded successfully or failed with an error): create an InstreamAdLoadListener instance and set it as an event listener for the ad loader.

  3. Create a configuration for the instreamAdRequestConfiguration request using the InstreamAdRequestConfiguration.Builder class. Pass the page identifier (Page ID) from the Partner interface as a request parameter.

  4. Load ads using the InstreamAdLoader.loadInstreamAd method and pass Context and instreamAdRequestConfiguration to it.

Code example:

To test the integration, use the demo Page ID: demo-instream-vmap-yandex.

final InstreamAdLoader instreamAdLoader = new InstreamAdLoader(context);
instreamAdLoader.setInstreamAdLoadListener(new InstreamAdLoadListener() {
        @override
        public void onInstreamAdLoaded(@NonNull final InstreamAd instreamAd) {
        ...
        }

        @override
        public void onInstreamAdFailedToLoad(@NonNull final String reason) {
        ...
        }
    });

final InstreamAdRequestConfiguration instreamAdRequestConfiguration = 
    new InstreamAdRequestConfiguration.Builder(PAGE_ID).build();
instreamAdLoader.loadInstreamAd(this, instreamAdRequestConfiguration);

Rendering ads

  1. Implement the InstreamAdPlayer and VideoPlayer interfaces.

    For more information about using and implementing the appropriate methods, see the reference guide sections Package com.yandex.mobile.ads.instream.player.ad and Package com.yandex.mobile.ads.instream.player.content. Additionally, see a test implementation example.

    Warning.

    To make implementation easier, we recommend using different instances of players to play video ads and content.

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

    Code example:
    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>

  3. Create an InstreamAdBinder object: pass Context, the loaded InstreamAd object, and the InstreamAdPlayer and VideoPlayer implementations to the builder.

    Set up notifications about the ad playing progress (ready to play the video ad, the video ad played or failed to play), create an instance of InstreamAdListener and set it as an event listener for InstreamAdBinder.

    mInstreamAdBinder = new InstreamAdBinder(context, mInstreamAd, mYandexAdPlayer, mContentVideoPlayer);
mInstreamAdBinder.setInstreamAdListener(...);

  4. To start playing a Pre-Roll ad break faster, preload it in advance by calling the InstreamAdBinder.prepareAd() method.

    private void preparePrerollAd(@NonNull final InstreamAdBinder instreamAdBinder) {
    instreamAdBinder.setInstreamAdListener(new InstreamAdListener() {
        ...
        public void onInstreamAdPrepared() {
            addInstreamAdBinderToPreloadedAdQueue(instreamAdBinder);
        }
        ...
    });
    instreamAdBinder.prepareAd();
}

  5. Call the InstreamAdBinder.bind(instreamAdView) method for the created InstreamAdBinder object. Pass InstreamAdView as a parameter. After that, the InStream SDK starts to automatically track the progress of playing the main video and manage the way video ads are played.

    mInstreamAdBinder.bind(mInstreamAdView);

  6. When playing InStream ads in the list, use the InStreamBinder.unbind() method when the cell with the ad is invalidated in the list. To implement a reused pool of players for scrolling, call InstreamAdbinder.invalidateAdPlayer() when reusing the ad player linked to InstreamAdBinder and InstreamAdBinder.invalidateVideoPlayer() when reusing the main content player.

  7. When you stop using InStreamAdBinder, reset the state.

    public void onDestroy() {
    instreamAdBinder.unbind();
    instreamAdBinder.invalidateVideoPlayer();
    instreamAdBinder.invalidateAdPlayer();
    instreamAdBinder.setInstreamAdListener(null);
    instreamAdBinder.setVideoAdPlaybackListener(null);
 
    super.onDestroy();
}