Интеграция InStream API. Интеграция

Рекламная сеть Яндекса

iOS (deprecated)

Интеграция (deprecated)

Форматы рекламы

Интеграция InStream API

Внимание.

Это архивная версия документации. Актуальная документация по всем платформам находится здесь.

InStream API — API для настройки, управления загрузкой и воспроизведением InStream рекламы. Позволяет поддержать проигрывание всех типов рекламных вставок: Pre-Roll, Mid-Roll, Post-Roll, In-Roll и Pause-Roll.

Для проигрывания вставок с типом Pre-Roll, Mid-Roll, Post-Roll используется InstreamAdBinder API. Для проигрывания вставок с типом In-Roll и Pause-Roll используются In-Roll API и Pause-Roll API соответственно.

Примечание.

Доступно одновременное использование InstreamAdBinder API, In-Roll API и Pause-Roll API при соблюдении определенных условий:

Используйте разные инстансы рекламного плеера.
Не запускайте Pause-Roll и In-Roll API для воспроизведения, если через InStreamAdBinder API было приостановлено основное видео.

Принципы работы

Загруженный объект InStream рекламы содержит в себе расписание показа рекламных вставок. Каждая рекламная вставка описывается объектом InstreamAdBreak. Рекламная вставка может иметь один из следующих типов: Pre / Mid / Post / In / Pause-Roll. Показать Pre/MidPost-Roll вставки можно через InstreamAdBinder API. Показать In / Pause-Roll вставки можно через In-Roll API и Pause-Roll API соответственно.

Для взаимодействия с основным видеоконтентом используется протокол VideoPlayer, а для воспроизведения рекламного видео внутри рекламной вставки — протокол InstreamAdPlayer.

InstreamAdBinder отслеживает ход воспроизведения основного видео и автоматически показывает рекламные вставки на основе расписания рекламных вставок из видеоресурса в Партнерском Интерфейсе.

InstreamAdBinder не управляет непосредственно отрисовкой рекламного видео в PlayerView. Воспроизводить рекламное видео необходимо со стороны приложения основываясь на сигналах от интерфейсов плееров, переданных в InstreamAdBinder. InstreamAdBinder сообщает о начале проигрывания рекламной вставки через вызов VideoPlayer.pauseVideo() и об окончании проигрывания рекламной вставки через вызов VideoPlayer.resumeVideo().

В момент вызова VideoPlayer.pauseVideo() со стороны приложения необходимо скрыть контролы управления основным видео, приостановить основное видео и начать воспроизведение рекламного видео. Со стороны рекламного SDK после вызова метода будут показаны рекламные контролы внутри контейнера InstreamAdView и будет вызван метод InstreamAdPlayer.playAd() для старта воспроизведения рекламного видео.

В момент вызова VideoPlayer.resumeVideo() со стороны приложения необходимо вернуть контролы управления основным видео и продолжить воспроизведение основного видео. Со стороны рекламного SDK до вызова метода будут убраны рекламные контролы внутри контейнера InstreamAdView.

In / Pause-Roll API не управляет непосредственно отрисовкой рекламного видео в PlayerView. Воспроизводить рекламное видео необходимо со стороны приложения основываясь на сигналах от интерфейсов плееров, переданных в In / Pause-Roll. In / Pause-Roll сообщает о начале проигрывания рекламной вставки через вызов InstreamAdBreakDelegate.instreamAdBreakDidStart() и об окончании проигрывания рекламной вставки через вызов InstreamAdBreakDelegate.instreamAdBreakDidComplete() или InstreamAdBreakDelegate.instreamAdBreakDidError().

В момент вызова InstreamAdBreakDelegate.instreamAdBreakDidStart() со стороны приложения необходимо скрыть контролы управления основным видео, приостановить основное видео. Со стороны рекламного SDK после вызова метода будут показаны рекламные контролы внутри контейнера InstreamAdView и будет вызван метод InstreamAdPlayer.playAd() для старта воспроизведения рекламного видео.

В момент вызова InstreamAdBreakDelegate.instreamAdBreakDidComplete() или InstreamAdBreakDelegate.instreamAdBreakDidError() со стороны приложения необходимо вернуть контролы управления основным видео и продолжить воспроизведение основного видео. Со стороны рекламного SDK до вызова методов будут убраны рекламные контролы из контейнера InstreamAdView.

Загрузка рекламных объявлений

Создайте экземпляр класса InstreamAdLoader для получения InStream рекламы.
Чтобы получать уведомления (успешная загрузка рекламы или ошибка при загрузке рекламы) подпишитесь на события загрузки рекламы. Для этого установите делегат, который удовлетворяет протоколу InstreamAdLoaderDelegate.
Создайте конфигурацию запроса instreamAdRequestConfiguration с помощью класса InstreamAdRequestConfiguration. В качестве параметров запроса передайте идентификатор страницы (Page ID) из Партнерского интерфейса.
Загрузите рекламу с помощью метода InstreamAdLoader.loadInstreamAd, передайте в него instreamAdRequestConfiguration.

Для тестирования корректности интеграции используйте демонстрационный Page ID: demo-instream-vmap-yandex.

adLoader = InstreamAdLoader()
adLoader.delegate = self
let configuration = InstreamAdRequestConfiguration(pageID: PAGE_ID)
adloader.loadInstreamAd(configuration: configuration)

Показ рекламных объявлений

Реализуйте интерфейсы InstreamAdPlayer и VideoPlayer.

В справочнике приведена подробная информация по работе методов и их реализации. Дополнительно рекомендуется ориентироваться на тестовый пример реализации.

Внимание.
Для упрощения реализации, рекомендуется использовать разные инстансы плееров для воспроизведения рекламы и контентного видео.
Добавьте в иерархию View приложения InstreamAdView. InstreamAdView должна содержать в себе PlayerView, в которой будут проигрываться рекламные ролики.

Ограничение.
Размер контейнера должен быть не меньше 300dp x 160dp.
Создайте объект InstreamAdBinder: передайте в конструктор объект загруженной рекламы InstreamAd и реализации плееров InstreamAdPlayer, VideoPlayer.

Настройте получение уведомлений о ходе воспроизведения рекламы (готовность к проигрыванию видеорекламы, завершение воспроизведения или ошибка в процессе воспроизведения): установите делегат, который удовлетворяет протоколу InstreamAdBinderDelegate.
```
adBinder = InstreamAdBinder(ad: ad, adPlayer: adPlayer, videoPlayer:
contentPlayer)
adBinder.delegate = self
```

Для ускорения старта рекламной вставки с типом Pre-Roll, заранее предзагрузите ее через вызов метода InstreamAdBinder.prepareAd().

func preparePrerollAd(adBinder: InstreamAdBinder) {
    adBinder.delegate = self
    adBinder.prepareAd()
}

extension InstreamViewController: InstreamAdBinderDelegate {
    func instreamAdBinder(_ binder: InstreamAdBinder, didPrepare instreamAd: InstreamAd) {
        addInstreamAdBinderToPreloadedAdQueue(binder)
    }
    …
}

Вызовите метод InstreamAdBinder.bind(with adView: InstreamAdView) у созданного объекта InstreamAdBinder. В качестве параметра передайте InstreamAdView, ранее добавленную в иерархию. После этого InStream SDK начнет автоматически отслеживать прогресс воспроизведения основного видео и возьмет на себя управление проигрыванием рекламных роликов.
```
adBinder.bind(with: instreamAdView)
```
При реализации проигрывания InStream рекламы в списке, необходимо использовать метод InStreamBinder.unbind() при инвалидации ячейки с рекламой в списке. При реализации переиспользуемого пула плееров для скролла, необходимо вызывать InstreamAdbinder.invalidateAdPlayer() при переиспользовании плеера рекламы привязанного к InstreamAdBinder, а при переиспользовании плеера основного контента InstreamAdBinder.invalidateVideoPlayer().
При остановке использования InStreamAdBinder необходимо очищать состояние.
```
deinit {
    adBinder.unbind()
    adBinder.invalidateVideoPlayer()
    adBinder.invalidateAdPlayer()
}
```

Примечание.

Показ рекламной вставки Pause-Roll настраивается по аналогии с In-Roll. Для этого замените In-Roll классы / методы на Pause-Roll.

Реализуйте интерфейс InstreamAdPlayer.

В справочнике приведена подробная информация по работе методов и их реализации. Дополнительно рекомендуется ориентироваться на тестовый пример реализации.

Внимание.
Для упрощения реализации, рекомендуется использовать разные инстансы плееров для воспроизведения рекламы и контентного видео.
Добавьте в иерархию View приложения InstreamAdView. InstreamAdView должна содержать в себе PlayerView, в которой будут проигрываться рекламные ролики.

Ограничение.
Размер контейнера должен быть не меньше 300dp x 160dp.
Загрузите через InstreamAdLoader объект InstreamAd с помощью идентификатора страницы (Page ID) из Партнерского интерфейса.
InstreamAd содержит в себе набор рекламных вставок разных типов. Чтобы получить рекламные вставки In-Roll, используйте InrollQueueProvider. Очередь InrollQueueProvider позволяет получать объекты In-Roll в необходимом для показа порядке.
```
func instreamAdLoader(_ instreamAdLoader: InstreamAdLoader, didLoad ad:
InstreamAd) {
    inrollQueue = InrollQueueProvider(ad: ad).queue()
}
```
Чтобы запустить полученный объект In-Roll, необходимо его подготовить. Без подготовки In-Roll не запустится. Для отслеживания окончания подготовки In-Roll установите делегат InstreamAdBreakDelegate, вызовите Inroll.prepare(with: adPlayer), и передайте в него инстанс созданной реализации InstreamAdPlayer.
```
private func prepareNextAd() {
    currentInroll = inrollQueue?.poll()
    currentInroll?.delegate = self
    currentInroll?.prepare(with: adPlayer)
}
```
По окончанию подготовки In-Roll будет вызван InstreamAdBreakDelegate.instreamAdBreakDidPrepare(). Подготовленный In-Roll готов к показу.

Совет.
Показывайте объявления в порядке их получения из InrollQueue. Показ полученных In-Roll в другом порядке может снизить монетизацию вашего приложения.
Чтобы показать подготовленный In-Roll, вызовите Inroll.play(with adView: InstreamAdView) и передайте в качестве параметра InstreamAdView, ранее добавленный в иерархию view.
```
func instreamAdBreakDidPrepare(_ adBreak: InstreamAdBreak) {
    currentInroll?.play(instreamAdView)
}
```
После начала проигрывания рекламной вставки, будет вызван метод InstreamAdBreakDelegate.instreamAdBreakDidStart(). По вызову этого метода необходимо поставить на паузу проигрывание основного видео и скрыть контролы управления основного видео.
```
func instreamAdBreakDidStart(_ adBreak: InstreamAdBreak) {
    contentVideoPlayer?.pauseVideo()
}
```
После проигрывания рекламной вставки необходимо продолжить воспроизведение основного видео. Проигрывание рекламной вставки может завершиться успешно или с ошибкой, эти две ситуации необходимо обрабатывать.
```
func instreamAdBreakDidComplete(_ adBreak: InstreamAdBreak) {
    handleAdBreakCompleted()
}
func instreamAdBreakDidError(_ adBreak: InstreamAdBreak) {
    handleAdBreakCompleted()
}
private fun handleAdBreakCompleted() {
    currentInroll = null
    contentVideoPlayer?.resumeVideo()
}
```
После завершения проигрывания текущего InRoll проверьте очередь воспроизведения на наличие следующего In-Roll в InrollQueue.
```
private func prepareNextAd() {
    currentInroll = inrollQueue?.poll()
    currentInroll?.delegate = self
    currentInroll?.prepare(with: adPlayer)
}
```
При остановке использования In-Roll необходимо очищать его состояние.
```
deinit {
    currentInroll?.invalidate()
}
```

Была ли статья полезна?

Расскажите, что вам не понравилось в статье:

InStream реклама

Классы и протоколы для работы

В этой статье

Принципы работы Загрузка рекламных объявлений Показ рекламных объявлений

InStream реклама

Классы и протоколы для работы