--- metadata: - name: generator content: Diplodoc Platform v5.52.0 alternate: - https://ads.yandex.com/helpcenter/en/dev/ios/instream-advanced.md - https://ads.yandex.com/helpcenter/ru/dev/ios/instream-advanced.md - https://ads.yandex.com/helpcenter/zh/dev/ios/instream-advanced.md - href: ru/dev/ios/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-рекламы. Позволяет поддержать проигрывание всех типов рекламных вставок, а также использовать свою реализацию плеера. InStream-реклама состоит из рекламных вставок, которые проигрываются автоматически и вручную. Для автоматического проигрывания вставок с типом Pre-roll, Mid-roll, Post-roll используется InstreamAdBinder API. Для ручного запуска рекламных вставок используется InstreamAdBreak API. {% note info %} Доступно одновременное использование InstreamAdBinder API и InstreamAdBreak API при соблюдении определенных условий: 1. Используйте разные инстансы рекламного плеера. 2. Не запускайте InstreamAdBreak API для воспроизведения, если через InStreamAdBinder API было приостановлено основное видео. 3. Из `InstreamAd` для InstreamAdBreak API используйте вставки типа `InstreamAdBreakType.inroll` или `InstreamAdBreakType.pauseroll` — остальные типы InstreamAdBinder отрисует самостоятельно. {% endnote %} ## Требования к приложению * Используйте Xcode 16.4 или выше. ## Принципы работы Загруженный объект InStream-рекламы содержит в себе расписание показа рекламных вставок. Каждая рекламная вставка описывается объектом InstreamAdBreak. Рекламная вставка может иметь один из следующих типов: Pre / Mid / Post / In / Pause-roll. Показать Pre / Mid / Post-Roll вставки можно через InstreamAdBinder API. Показать вставки вручную, в том числе Pause-roll и In-roll, можно через InstreamAdBreak 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. - Показ InstreamAdBreak InstreamAdBreak API не управляет непосредственно отрисовкой рекламного видео в PlayerView. Воспроизводить рекламное видео необходимо со стороны приложения основываясь на сигналах от интерфейсов плееров, переданных в InstreamAdBreak. InstreamAdBreak сообщает о начале проигрывания рекламной вставки через вызов `InstreamAdBreakDelegate.instreamAdBreakDidStart()` и об окончании проигрывания рекламной вставки через вызов `InstreamAdBreakDelegate.instreamAdBreakDidComplete()` или `InstreamAdBreakDelegate.instreamAdBreakDidError()`. В момент вызова `InstreamAdBreakDelegate.instreamAdBreakDidStart()` со стороны приложения необходимо скрыть контролы управления основным видео, приостановить основное видео. Со стороны рекламного SDK после вызова метода будут показаны рекламные контролы внутри контейнера InstreamAdView и будет вызван метод `InstreamAdPlayer.playAd()` для старта воспроизведения рекламного видео. В момент вызова `InstreamAdBreakDelegate.instreamAdBreakDidComplete()` или `InstreamAdBreakDelegate.instreamAdBreakDidError()` со стороны приложения необходимо вернуть контролы управления основным видео и продолжить воспроизведение основного видео. Со стороны рекламного SDK до вызова методов будут убраны рекламные контролы из контейнера InstreamAdView. {% endlist %} ## Загрузка рекламных объявлений 1. Создайте экземпляр класса `InstreamAdLoader` для получения InStream-рекламы. 2. Создайте конфигурацию запроса с помощью класса `InstreamAdRequestConfiguration`. В качестве параметров запроса передайте идентификатор страницы (`Page ID`) из интерфейса Рекламной сети Яндекса. 3. Загрузите рекламу с помощью метода `loadInstreamAd(configuration:completion:)`. Для тестирования корректности интеграции используйте демонстрационный Page ID: `demo-instream-vmap-yandex`. {% list tabs %} - Swift Concurrency ```swift let adLoader = InstreamAdLoader() let configuration = InstreamAdRequestConfiguration(pageID: PAGE_ID) do { let ad = try await adLoader.loadInstreamAd(configuration: configuration) // Используйте загруженный объект InstreamAd } catch { // Ошибка загрузки } ``` - Completion handler ```swift let adLoader = InstreamAdLoader() let configuration = InstreamAdRequestConfiguration(pageID: PAGE_ID) adLoader.loadInstreamAd(configuration: configuration) { result in switch result { case .success(let ad): // Используйте загруженный объект InstreamAd break case .failure(let info): // Ошибка загрузки: info.reason break } } ``` {% endlist %} ## Показ рекламных объявлений {% 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() } ``` - Показ InstreamAdBreak {% note info %} Показ любой рекламной вставки настраивается по аналогии с In-roll. Для этого при фильтрации вставок замените `InstreamAdBreakType.inroll` на нужный тип, например `InstreamAdBreakType.pauseroll`. {% 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 содержит в себе набор рекламных вставок разных типов в свойстве `adBreaks`. Чтобы получить рекламные вставки In-roll, отфильтруйте массив по типу `InstreamAdBreakType.inroll`. Вставки возвращаются в порядке, предназначенном для показа. ```swift adLoader.loadInstreamAd(configuration: configuration) { result in if case .success(let ad) = result { inrollQueue = ad.adBreaks.filter { $0.adBreakData.type == InstreamAdBreakType.inroll } } } ``` 5. Чтобы запустить полученный объект In-roll, необходимо его подготовить. Без подготовки In-roll не запустится. Для отслеживания окончания подготовки установите делегат `InstreamAdBreakDelegate`, вызовите `InstreamAdBreak.prepare(with: adPlayer)`, и передайте в него инстанс созданной реализации InstreamAdPlayer. ```swift private func prepareNextAd() { guard !inrollQueue.isEmpty else { return } currentAdBreak = inrollQueue.removeFirst() currentAdBreak?.delegate = self currentAdBreak?.prepare(with: adPlayer) } ``` 6. По окончанию подготовки In-roll будет вызван `InstreamAdBreakDelegate.instreamAdBreakDidPrepare()`. Подготовленный In-roll готов к показу. {% note tip %} Показывайте объявления в порядке их получения из `adBreaks`. Показ вставок в другом порядке может снизить монетизацию вашего приложения. {% endnote %} 7. Чтобы показать подготовленную вставку, вызовите `InstreamAdBreak.play(with: adView)` и передайте в качестве параметра InstreamAdView, ранее добавленный в иерархию view. ```swift func instreamAdBreakDidPrepare(_ adBreak: InstreamAdBreak) { currentAdBreak?.play(with: instreamAdView) } ``` 8. После начала проигрывания рекламной вставки, будет вызван метод `InstreamAdBreakDelegate.instreamAdBreakDidStart()`. По вызову этого метода необходимо поставить на паузу проигрывание основного видео и скрыть контролы управления основного видео. ```swift func instreamAdBreakDidStart(_ adBreak: InstreamAdBreak) { contentVideoPlayer?.pauseVideo() } ``` 9. После проигрывания рекламной вставки необходимо продолжить воспроизведение основного видео. Проигрывание рекламной вставки может завершиться успешно или с ошибкой, эти две ситуации необходимо обрабатывать. ```swift func instreamAdBreakDidComplete(_ adBreak: InstreamAdBreak) { handleAdBreakCompleted() } func instreamAdBreakDidError(_ adBreak: InstreamAdBreak) { handleAdBreakCompleted() } private func handleAdBreakCompleted() { currentAdBreak = nil contentVideoPlayer?.resumeVideo() } ``` 10. После завершения проигрывания текущей вставки подготовьте следующую из очереди. ```swift private func prepareNextAd() { guard !inrollQueue.isEmpty else { return } currentAdBreak = inrollQueue.removeFirst() currentAdBreak?.delegate = self currentAdBreak?.prepare(with: adPlayer) } ``` 11. При остановке использования In-roll необходимо очищать его состояние. ```swift deinit { currentAdBreak?.invalidate() } ``` {% endlist %}