--- metadata: - name: generator content: Diplodoc Platform v5.55.2 alternate: - https://ads.yandex.com/helpcenter/en/dev/ios7/instream-advanced.md - https://ads.yandex.com/helpcenter/ru/dev/ios7/instream-advanced.md - href: ru/dev/ios7/instream-advanced.md type: text/markdown title: Markdown version - href: llms.txt type: text/markdown title: llms.txt --- > **Documentation Index:** Fetch the complete configuration index at https://ads.yandex.com/helpcenter/ru/llms.txt # Интеграция 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 соответственно. {% note info %} Доступно одновременное использование InstreamAdBinder API, In-roll API и Pause-roll API при соблюдении определенных условий: 1. Используйте разные инстансы рекламного плеера. 2. Не запускайте Pause-roll и In-roll API для воспроизведения, если через InStreamAdBinder API было приостановлено основное видео. {% endnote %} ## Требования к приложению * Используйте Xcode 16.4 или выше. ## Принципы работы Загруженный объект InStream-рекламы содержит в себе расписание показа рекламных вставок. Каждая рекламная вставка описывается объектом InstreamAdBreak. Рекламная вставка может иметь один из следующих типов: Pre / Mid / Post / In / Pause-roll. Показать Pre/MidPost-Roll вставки можно через InstreamAdBinder API. Показать In / Pause-Roll вставки можно через In-roll API и Pause-roll API соответственно. Для взаимодействия с основным видеоконтентом используется протокол `VideoPlayer`, а для воспроизведения рекламного видео внутри рекламной вставки — протокол `InstreamAdPlayer`. {% list tabs %} - Показ Pre / Mid / Post-Roll InstreamAdBinder отслеживает ход воспроизведения основного видео и автоматически показывает рекламные вставки на основе расписания рекламных вставок из видеоресурса в интерфейсе Рекламной сети Яндекса. InstreamAdBinder не управляет непосредственно отрисовкой рекламного видео в PlayerView. Воспроизводить рекламное видео необходимо со стороны приложения основываясь на сигналах от интерфейсов плееров, переданных в InstreamAdBinder. InstreamAdBinder сообщает о начале проигрывания рекламной вставки через вызов `VideoPlayer.pauseVideo()` и об окончании проигрывания рекламной вставки через вызов `VideoPlayer.resumeVideo()`. В момент вызова `VideoPlayer.pauseVideo()` со стороны приложения необходимо скрыть контролы управления основным видео, приостановить основное видео и начать воспроизведение рекламного видео. Со стороны рекламного SDK после вызова метода будут показаны рекламные контролы внутри контейнера InstreamAdView и будет вызван метод InstreamAdPlayer.playAd() для старта воспроизведения рекламного видео. В момент вызова `VideoPlayer.resumeVideo()` со стороны приложения необходимо вернуть контролы управления основным видео и продолжить воспроизведение основного видео. Со стороны рекламного SDK до вызова метода будут убраны рекламные контролы внутри контейнера InstreamAdView. - Показ In / Pause-Roll 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. {% endlist %} ## Загрузка рекламных объявлений 1. Создайте экземпляр класса `InstreamAdLoader` для получения InStream-рекламы. 2. Чтобы получать уведомления (успешная загрузка рекламы или ошибка при загрузке рекламы) подпишитесь на события загрузки рекламы. Для этого установите делегат, который удовлетворяет протоколу `InstreamAdLoaderDelegate`. 3. Создайте конфигурацию запроса `instreamAdRequestConfiguration` с помощью класса `InstreamAdRequestConfiguration`. В качестве параметров запроса передайте идентификатор страницы (`Page ID`) из интерфейса Рекламной сети Яндекса. 4. Загрузите рекламу с помощью метода `InstreamAdLoader.loadInstreamAd`, передайте в него `instreamAdRequestConfiguration`. Для тестирования корректности интеграции используйте демонстрационный Page ID: `demo-instream-vmap-yandex`. ```swift adLoader = InstreamAdLoader() adLoader.delegate = self let configuration = InstreamAdRequestConfiguration(pageID: PAGE_ID) adloader.loadInstreamAd(configuration: configuration) ``` ## Показ рекламных объявлений {% list tabs %} - Показ Pre / Mid / Post-Roll 1. Реализуйте интерфейсы `InstreamAdPlayer` и `VideoPlayer`. В справочнике приведена подробная информация по работе методов и их реализации. Дополнительно рекомендуется ориентироваться на [тестовый пример реализации](https://github.com/yandexmobile/yandex-ads-sdk-ios/tree/master/Examples/YandexMobileAdsExample/YandexMobileAdsExample). {% note tip %} Для упрощения реализации, рекомендуется использовать разные инстансы плееров для воспроизведения рекламы и контентного видео. {% endnote %} 2. Добавьте в иерархию View приложения InstreamAdView. InstreamAdView должна содержать в себе PlayerView, в которой будут проигрываться рекламные ролики. {% note warning %} Размер контейнера должен быть не меньше 300dp x 160dp. {% endnote %} 3. Создайте объект InstreamAdBinder: передайте в конструктор объект загруженной рекламы `InstreamAd` и реализации плееров `InstreamAdPlayer`, `VideoPlayer`. Настройте получение уведомлений о ходе воспроизведения рекламы (готовность к проигрыванию видеорекламы, завершение воспроизведения или ошибка в процессе воспроизведения): установите делегат, который удовлетворяет протоколу `InstreamAdBinderDelegate`. ```swift adBinder = InstreamAdBinder(ad: ad, adPlayer: adPlayer, videoPlayer: contentPlayer) adBinder.delegate = self ``` 4. Для ускорения старта рекламной вставки с типом Pre-roll, заранее предзагрузите ее через вызов метода `InstreamAdBinder.prepareAd()`. ```swift func preparePrerollAd(adBinder: InstreamAdBinder) { adBinder.delegate = self adBinder.prepareAd() } extension InstreamViewController: InstreamAdBinderDelegate { func instreamAdBinder(_ binder: InstreamAdBinder, didPrepare instreamAd: InstreamAd) { addInstreamAdBinderToPreloadedAdQueue(binder) } //... } ``` 5. Вызовите метод `InstreamAdBinder.bind(with adView: InstreamAdView)` у созданного объекта InstreamAdBinder. В качестве параметра передайте `InstreamAdView`, ранее добавленную в иерархию. После этого InStream SDK начнет автоматически отслеживать прогресс воспроизведения основного видео и возьмет на себя управление проигрыванием рекламных роликов. ```swift adBinder.bind(with: instreamAdView) ``` 6. При реализации проигрывания InStream-рекламы в списке, необходимо использовать метод `InStreamBinder.unbind()` при инвалидации ячейки с рекламой в списке. При реализации переиспользуемого пула плееров для скролла, необходимо вызывать `InstreamAdbinder.invalidateAdPlayer()` при переиспользовании плеера рекламы привязанного к InstreamAdBinder, а при переиспользовании плеера основного контента `InstreamAdBinder.invalidateVideoPlayer()`. 7. При остановке использования InStreamAdBinder необходимо очищать состояние. ```swift deinit { adBinder.unbind() adBinder.invalidateVideoPlayer() adBinder.invalidateAdPlayer() } ``` - Показ In / Pause-Roll {% note info %} Показ рекламной вставки Pause-roll настраивается по аналогии с In-roll. Для этого замените In-roll классы / методы на Pause-roll. {% endnote %} 1. Реализуйте интерфейс InstreamAdPlayer. В справочнике приведена подробная информация по работе методов и их реализации. Дополнительно рекомендуется ориентироваться на [тестовый пример реализации](https://github.com/yandexmobile/yandex-ads-sdk-ios/tree/master/Examples/YandexMobileAdsExample/YandexMobileAdsExample). {% note tip %} Для упрощения реализации, рекомендуется использовать разные инстансы плееров для воспроизведения рекламы и контентного видео. {% endnote %} 2. Добавьте в иерархию View приложения InstreamAdView. InstreamAdView должна содержать в себе PlayerView, в которой будут проигрываться рекламные ролики. {% note warning %} Размер контейнера должен быть не меньше 300dp x 160dp. {% endnote %} 3. Загрузите через InstreamAdLoader объект InstreamAd с помощью идентификатора страницы (`Page ID`) из интерфейса Рекламной сети Яндекса. 4. InstreamAd содержит в себе набор рекламных вставок разных типов. Чтобы получить рекламные вставки In-roll, используйте `InrollQueueProvider`. Очередь `InrollQueueProvider` позволяет получать объекты In-roll в необходимом для показа порядке. ```swift func instreamAdLoader(_ instreamAdLoader: InstreamAdLoader, didLoad ad: InstreamAd) { inrollQueue = InrollQueueProvider(ad: ad).queue() } ``` 5. Чтобы запустить полученный объект In-roll, необходимо его подготовить. Без подготовки In-roll не запустится. Для отслеживания окончания подготовки In-roll установите делегат `InstreamAdBreakDelegate`, вызовите `Inroll.prepare(with: adPlayer)`, и передайте в него инстанс созданной реализации InstreamAdPlayer. ```swift private func prepareNextAd() { currentInroll = inrollQueue?.poll() currentInroll?.delegate = self currentInroll?.prepare(with: adPlayer) } ``` 6. По окончанию подготовки In-roll будет вызван InstreamAdBreakDelegate.instreamAdBreakDidPrepare(). Подготовленный In-roll готов к показу. {% note tip %} Показывайте объявления в порядке их получения из InrollQueue. Показ полученных In-roll в другом порядке может снизить монетизацию вашего приложения. {% endnote %} 7. Чтобы показать подготовленный In-roll, вызовите `Inroll.play(with adView: InstreamAdView)` и передайте в качестве параметра InstreamAdView, ранее добавленный в иерархию view. ```swift func instreamAdBreakDidPrepare(_ adBreak: InstreamAdBreak) { currentInroll?.play(instreamAdView) } ``` 8. После начала проигрывания рекламной вставки, будет вызван метод `InstreamAdBreakDelegate.instreamAdBreakDidStart()`. По вызову этого метода необходимо поставить на паузу проигрывание основного видео и скрыть контролы управления основного видео. ```swift func instreamAdBreakDidStart(_ adBreak: InstreamAdBreak) { contentVideoPlayer?.pauseVideo() } ``` 9. После проигрывания рекламной вставки необходимо продолжить воспроизведение основного видео. Проигрывание рекламной вставки может завершиться успешно или с ошибкой, эти две ситуации необходимо обрабатывать. ```swift func instreamAdBreakDidComplete(_ adBreak: InstreamAdBreak) { handleAdBreakCompleted() } func instreamAdBreakDidError(_ adBreak: InstreamAdBreak) { handleAdBreakCompleted() } private fun handleAdBreakCompleted() { currentInroll = null contentVideoPlayer?.resumeVideo() } ``` 10. После завершения проигрывания текущего InRoll проверьте очередь воспроизведения на наличие следующего In-roll в InrollQueue. ```swift private func prepareNextAd() { currentInroll = inrollQueue?.poll() currentInroll?.delegate = self currentInroll?.prepare(with: adPlayer) } ``` 11. При остановке использования In-roll необходимо очищать его состояние. ```swift deinit { currentInroll?.invalidate() } ``` {% endlist %}