---
metadata:
- name: generator
content: Diplodoc Platform v5.50.6
alternate:
- https://ads.yandex.com/helpcenter/en/dev/android/instream-advanced.md
- https://ads.yandex.com/helpcenter/ru/dev/android/instream-advanced.md
- https://ads.yandex.com/helpcenter/zh/dev/android/instream-advanced.md
---
> **Documentation Index:** Fetch the complete configuration index at https://ads.yandex.com/helpcenter/en/llms.txt
# Advanced integration (InStream API)
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 video ads that are played 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 info %}
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.
{% endnote %}
## 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-/Mid-/Post-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.
{% list tabs %}
- Playing Pre/Mid/Post-Roll video ads
InstreamAdBinder tracks the progress of playing the main video and shows ad breaks based on the video resource settings in the Yandex Advertising Network 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.
- Playing In/Pause-Roll video ads
The In/Pause-Roll 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 In/Pause-Roll. 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.
{% endlist %}
## 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 `instreamAdRequest` request using the `InstreamAdRequest.Builder` class. Pass the `PAGE_ID` from the Yandex Advertising Network interface as a request parameter.
4. Load ads using the `InstreamAdLoader.loadInstreamAd` method and pass `Context` and `instreamAdRequest` to it.
**Code example:**
To test the integration, use the demo PAGE_ID: `demo-instream-vmap-yandex`.
{% list tabs %}
- Kotlin
```kotlin
val instreamAdLoader = InstreamAdLoader(this)
instreamAdLoader.setInstreamAdLoadListener(object : InstreamAdLoadListener {
override fun onInstreamAdLoaded(instreamAd: InstreamAd) {
// ...
}
override fun onInstreamAdFailedToLoad(reason: String) {
// ...
}
})
val instreamAdRequest = InstreamAdRequest.Builder(PAGE_ID).build()
instreamAdLoader.loadInstreamAd(this, instreamAdRequest)
```
- Java
```java
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 InstreamAdRequest instreamAdRequest =
new InstreamAdRequest.Builder(PAGE_ID).build();
instreamAdLoader.loadInstreamAd(this, instreamAdRequest);
```
{% endlist %}
## Rendering ads
{% list tabs %}
- Playing Pre/Mid/Post-Roll video 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.
{% note tip %}
To make implementation easier, we recommend using different instances of players to play video ads and content.
{% endnote %}
2. Add InstreamAdView to the app layout. InstreamAdView must contain PlayerView to play video ads in.
Code example:
{% note info "Constraint" %}
A container must be at least 300dp x 160dp in size.
{% endnote %}
```xml
```
3. Create an `InstreamAdBinder` object: pass Context, the loaded `InstreamAd` object, and the `VideoPlayer` and `InstreamAdPlayer` 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`.
{% list tabs %}
- Kotlin
```kotlin
instreamAdBinder = InstreamAdBinder(
this,
instreamAd,
checkNotNull(contentVideoPlayer),
checkNotNull(instreamAdPlayer)
)
instreamAdBinder.setInstreamAdListener(...)
```
- Java
```java
mInstreamAdBinder = new InstreamAdBinder(context, mInstreamAd, mContentVideoPlayer, mYandexAdPlayer);
mInstreamAdBinder.setInstreamAdListener(...);
```
{% endlist %}
4. To start playing a Pre-roll ad break faster, preload it in advance by calling the `InstreamAdBinder.prepareAd()` method.
{% list tabs %}
- Kotlin
```kotlin
private fun preparePrerollAd(instreamAdBinder: InstreamAdBinder) {
instreamAdBinder.setInstreamAdListener(object : InstreamAdListener {
// ...
override fun onInstreamAdPrepared() {
addInstreamAdBinderToPreloadedAdQueue(instreamAdBinder)
} // ...
})
instreamAdBinder.prepareAd()
}
```
- Java
```java
private void preparePrerollAd(@NonNull final InstreamAdBinder instreamAdBinder) {
instreamAdBinder.setInstreamAdListener(new InstreamAdListener() {
// ...
public void onInstreamAdPrepared() {
addInstreamAdBinderToPreloadedAdQueue(instreamAdBinder);
}
// ...
});
instreamAdBinder.prepareAd();
}
```
{% endlist %}
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.
{% list tabs %}
- Kotlin
```kotlin
instreamAdBinder.bind(instreamAdView)
```
- Java
```java
mInstreamAdBinder.bind(mInstreamAdView);
```
{% endlist %}
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.
{% list tabs %}
- Kotlin
```kotlin
override fun onDestroy() {
instreamAdBinder.apply {
unbind()
instreamAdBinder.invalidateVideoPlayer()
instreamAdBinder.invalidateAdPlayer()
instreamAdBinder.setInstreamAdListener(null)
instreamAdBinder.setVideoAdPlaybackListener(null)
}
super.onDestroy()
}
```
- Java
```java
public void onDestroy() {
instreamAdBinder.unbind();
instreamAdBinder.invalidateVideoPlayer();
instreamAdBinder.invalidateAdPlayer();
instreamAdBinder.setInstreamAdListener(null);
instreamAdBinder.setVideoAdPlaybackListener(null);
super.onDestroy();
}
```
{% endlist %}
- Playing In/Pause-Roll video ads
{% note info %}
Setting up playing Pause-roll ad breaks is similar to In-roll. To do this, replace In-roll classes/methods with Pause-roll ones.
{% endnote %}
1. Implement the InstreamAdPlayer interface.
For more information about the methods and their implementation, see the `Package com.yandex.mobile.ads.instream.player.ad` reference section. Additionally, see a test implementation example.
{% note tip %}
To make implementation easier, we recommend using different instances of players to play video ads and content.
{% endnote %}
2. Add InstreamAdView to the app layout. InstreamAdView must contain PlayerView to play video ads in.
Code example:
{% note info "Constraint" %}
A container must be at least 300dp x 160dp in size.
{% endnote %}
```xml
```
3. Use the `InstreamAdLoader` to load the `InstreamAd` object using the `PAGE_ID` from the Yandex Advertising Network interface.
4. The InstreamAd object contains a set of different types of ad breaks. To get In-roll ad breaks, use `InrollQueueProvider`. The `InrollQueueProvider` queue lets you receive In-roll objects in the display order.
{% list tabs %}
- Kotlin
```kotlin
fun onInstreamAdLoaded(instreamAd: InstreamAd) {
val inrollQueueProvider = InrollQueueProvider(context, instreamAd)
instreamAdBreakQueue = inrollQueueProvider.queue
}
```
- Java
```java
public void onInstreamAdLoaded(@NonNull final InstreamAd instreamAd) {
final InrollQueueProvider inrollQueueProvider = new InrollQueueProvider(context, instreamAd);
mInstreamAdBreakQueue = inrollQueueProvider.getQueue();
}
```
{% endlist %}
5. To launch the received In-roll video ad, you need to prepare it. Unprepared In-roll video ads won't start.
To prepare an In-roll video ad, call the interface `Inroll.prepare(instreamAdPlayer)` and pass an instance of the created `InstreamAdPlayer` implementation to it. To track the status of the ad break, set `InstreamAdBreakEventListener`.
{% list tabs %}
- Kotlin
```kotlin
fun prepare(instreamAdPlayer: SampleInstreamAdPlayer) {
currentInroll = instreamAdBreakQueue.poll()?.apply {
setListener(InrollListener())
instreamAdPlayer.let(::prepare)
}
}
```
- Java
```java
public void prepare(instreamAdPlayer) {
currentInroll = mInstreamAdBreakQueue.poll();
currentInroll.setListener(new InrollListener());
currentInroll.prepare(instreamAdPlayer);
}
```
{% endlist %}
6. Once the In-roll video ad is prepared, `InstreamAdBreakEventListener.onInstreamAdBreakPrepared()` is called. The prepared In-roll video ad is ready to play.
{% note tip %}
Play video ads in the order they're received from the InstreamAdBreakQueue. If the received In-roll video ads are played in a different order, this may lower your app's monetization.
{% endnote %}
7. To play the prepared In-roll video ad, call `Inroll.play()` and pass `InstreamAdView` as a parameter.
{% list tabs %}
- Kotlin
```kotlin
fun onInstreamAdBreakPrepared() {
currentInroll?.play(instreamAdView)
}
```
- Java
```java
public void onInstreamAdBreakPrepared() {
if (currentInroll != null) {
currentInroll.play(instreamAdView);
}
}
```
{% endlist %}
8. After the ad break starts playing, the `InstreamAdBreakEventListener.onInstreamAdBreakStarted()` method is called. After calling this method, pause the main video and hide its controls.
{% list tabs %}
- Kotlin
```kotlin
fun onInstreamAdBreakStarted() {
contentVideoPlayer?.pauseVideo()
}
```
- Java
```java
public void onInstreamAdBreakStarted() {
if (contentVideoPlayer != null) {
contentVideoPlayer.pauseVideo();
}
}
```
{% endlist %}
9. 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.
{% list tabs %}
- Kotlin
```kotlin
override fun onInstreamAdBreakCompleted() {
handleAdBreakCompleted()
}
override fun onInstreamAdBreakError(reason: String) {
handleAdBreakCompleted()
}
private fun handleAdBreakCompleted() {
currentInroll = null
contentVideoPlayer?.resumeVideo()
}
```
- Java
```java
@Override
public void onInstreamAdBreakCompleted() {
handleAdBreakCompleted();
}
@Override
public void onInstreamAdBreakError(@NonNull final String reason) {
handleAdBreakCompleted();
}
private void handleAdBreakCompleted() {
currentInroll = null;
if (contentVideoPlayer != null) {
contentVideoPlayer.resumeVideo();
}
}
```
{% endlist %}
10. After the current In-roll video ad finishes playing, check the play queue for the next In-roll video ad in the `InstreamAdBreakQueue`.
{% list tabs %}
- Kotlin
```kotlin
fun prepareNextAd() {
currentInroll = mInstreamAdBreakQueue.poll()
currentInroll?.prepareInroll(currentInroll)
}
```
- Java
```java
public void prepareNextAd() {
currentInroll = mInstreamAdBreakQueue.poll();
if (currentInroll != null) {
prepareInroll(currentInroll);
}
}
```
{% endlist %}
11. When you stop using an In-roll video ad, reset its state.
{% list tabs %}
- Kotlin
```kotlin
override fun onDestroy() {
currentInroll?.apply {
invalidate()
setListener(null)
}
super.onDestroy()
}
```
- Java
```java
public void onDestroy() {
if (currentInroll != null) {
currentInroll.invalidate();
currentInroll.setListener(null);
}
super.onDestroy();
}
```
{% endlist %}
{% endlist %}