Настройка IMA SDK для DAI

Выберите платформу: HTML5 Android iOS tvOS Cast Roku

Пакеты IMA SDK упрощают интеграцию мультимедийной рекламы в ваши веб-сайты и приложения. Пакеты IMA SDK могут запрашивать рекламу с любого рекламного сервера , совместимого с VAST, и управлять её воспроизведением в ваших приложениях. С помощью пакетов IMA DAI SDK приложения запрашивают потоковое видео для рекламы и контента — как VOD, так и прямой трансляции. Затем SDK возвращает объединённый видеопоток, поэтому вам не придётся переключаться между рекламой и контентом в приложении.

Выберите интересующее вас решение DAI

Полный сервис обслуживания Pod

Полный комплекс услуг DAI

В этом руководстве показано, как интегрировать IMA DAI SDK в простое приложение видеоплеера. Если вы хотите просмотреть или изучить готовый пример интеграции, скачайте базовый пример с GitHub.

Примечание: IMA DAI SDK для Roku поддерживает потоки HLS и DASH без каких-либо различий в реализации.

Для использования IMA DAI вам потребуется расширенная учётная запись Ad Manager 360. Если у вас есть учётная запись Ad Manager, обратитесь к своему менеджеру для получения дополнительной информации. Информацию о регистрации в Ad Manager можно найти в Справочном центре Ad Manager .

Примечание: Информацию об интеграции с другими платформами или об использовании клиентских SDK IMA см. в разделе Interactive Media Ads SDKs .

Обзор IMA DAI

Реализация IMA DAI включает два основных компонента SDK, как показано в этом руководстве:

• StreamRequest : объект, определяющий запрос потока. Запросы потока могут быть предназначены как для видео по запросу, так и для прямых трансляций. В запросах прямых трансляций указывается ключ ресурса, а в запросах VOD — идентификатор CMS и идентификатор видео. Оба типа запросов могут дополнительно включать ключ API, необходимый для доступа к указанным потокам, и сетевой код Google Ad Manager для IMA SDK для обработки идентификаторов объявлений, указанных в настройках Google Ad Manager.
• StreamManager : объект, который обрабатывает потоки динамической вставки рекламы и взаимодействует с бэкендом DAI. Менеджер потоков также обрабатывает запросы отслеживания и пересылает события потоков и рекламы издателю.

Предпосылки

• Ознакомьтесь с нашей страницей совместимости , чтобы убедиться, что ваш предполагаемый вариант использования поддерживается.
• Загрузите наш пример кода плеера Roku
• Разверните код образца проигрывателя на устройстве Roku, чтобы проверить работоспособность вашей среды разработки.

Воспроизвести видео

Предоставленный пример видеоплеера воспроизводит видеоконтент без дополнительных настроек. Разверните пример плеера на вашем плеере Roku, чтобы убедиться, что ваша среда разработки настроена правильно.

Превратите свой видеоплеер в потоковый проигрыватель IMA DAI

Выполните следующие шаги для реализации потокового проигрывателя.

Создать Sdk.xml

Добавьте в свой проект новый файл рядом с MainScene.xml с названием Sdk.xml и добавьте следующий шаблон:

SDK.xml

<?xml version = "1.0" encoding = "utf-8" ?>

<component name = "imasdk" extends = "Task">
<interface>
</interface>
<script type = "text/brightscript">
<![CDATA[
  ' Your code goes here.
]]>
</script>
</component>

Вам необходимо редактировать оба этих файла на протяжении всего руководства.

Загрузите рекламную платформу Roku

IMA DAI SDK зависит от Roku Advertising Framework. Чтобы загрузить фреймворк, добавьте в manifest и Sdk.xml следующее:

bs_libs_required=roku_ads_lib,googleima3
manifest

Library "Roku_Ads.brs"
Library "IMA3.brs"
Sdk.xml

Загрузите IMA DAI SDK

Чтобы загрузить IMA DAI SDK, выполните следующие действия:

1. Инициализируйте IMA SDK с помощью вызова New_IMASDK() :

   sub loadSdk()
     If m.sdk = invalid
       m.sdk = New_IMASDK()
     End If
     m.top.sdkLoaded = true
   End Sub
   Sdk.xml
   

2. Отслеживайте загрузку IMA, создав логическое поле sdkLoaded :

   <field id="sdkLoaded" type="Boolean" />
   Sdk.xml
   

3. Вызовите подпрограмму loadSdk() из основной подпрограммы runThread() :

   if not m.top.sdkLoaded
     loadSdk()
   End If
   Sdk.xml
   

4. Создайте функцию loadImaSdk() в MainScene.xml для создания и запуска объекта sdkTask :

   function loadImaSdk() as void
     m.sdkTask = createObject("roSGNode", "imasdk")
     m.sdkTask.observeField("sdkLoaded", "onSdkLoaded")
     m.sdkTask.observeField("errors", "onSdkLoadedError")
   
     ' Change to m.testLiveStream to demo live instead of VOD.
     selectedStream = m.testVodStream
     m.videoTitle = selectedStream.title
     m.sdkTask.streamData = selectedStream
   
     m.sdkTask.observeField("urlData", "urlLoadRequested")
     m.sdkTask.video = m.video
     ' Setting control to run starts the task thread.
     m.sdkTask.control = "RUN"
   end function
   MainScene.xml
   

5. Вызовите функцию loadImaSdk() из функции init() .

6. Создайте подпрограммы прослушивателя onSdkLoaded() и onSdkLoadedError() для реагирования на события загрузки SDK:

   Sub onSdkLoaded(message as Object)
     print "----- onSdkLoaded --- control ";message
   End Sub
   
   Sub onSdkLoadedError(message as Object)
     print "----- errors in the sdk loading process --- ";message
   End Sub
   MainScene.xml
   

Создать проигрыватель потоков IMA

Чтобы создать проигрыватель потоков IMA, выполните следующие действия:

1. Создайте подпрограмму setupVideoPlayer() , которая выполняет следующие действия:

   1. Используйте метод createPlayer() для создания потокового проигрывателя.

   2. Пусть этот потоковый проигрыватель реализует три метода обратного вызова: loadUrl , adBreakStarted и adBreakEnded .

   3. Отключите функцию Trick Play при загрузке трансляции, чтобы пользователи не могли пропустить преролл в момент начала трансляции до срабатывания события начала рекламной паузы.

   sub setupVideoPlayer()
     sdk = m.sdk
     m.player = sdk.createPlayer()
     m.player.top = m.top
     m.player.loadUrl = Function(urlData)
       ' This line prevents users from scanning during buffering
       ' or during the first second of the ad before we have a callback from roku.
       ' If there are no prerolls disabling trickplay isn't needed.
       m.top.video.enableTrickPlay = false
       m.top.urlData = urlData
     End Function
     m.player.adBreakStarted = Function(adBreakInfo as Object)
       print "---- Ad Break Started ---- "
       m.top.adPlaying = True
       m.top.video.enableTrickPlay = false
     End Function
     m.player.adBreakEnded = Function(adBreakInfo as Object)
       print "---- Ad Break Ended ---- "
       m.top.adPlaying = False
       m.top.video.enableTrickPlay = true
     End Function
     m.player.seek = Function(timeSeconds as Double)
       print "---- SDK requested seek to ----" ; timeSeconds
       m.top.video.seekMode = "accurate"
       m.top.video.seek = timeSeconds
     End Function
   End Sub
   Sdk.xml
   

   Добавьте метод обратного вызова seek для поддержки пропускаемой рекламы. Подробнее см. в разделе Добавление поддержки пропускаемой рекламы .

2. Добавьте поля urlData , adPlaying и video , используемые в подпрограмме setupVideoPlayer() :

   <field id="urlData" type="assocarray" />
   <field id="adPlaying" type="Boolean" />
   <field id="video" type="Node" />
   Sdk.xml
   

Создать и выполнить потоковый запрос

Чтобы запросить поток DAI, выполните следующие действия:

1. Создайте подпрограмму loadStream() для создания и запроса потока. Для поддержки рекламного интерфейса, например значков adChoices , необходимо также передать ссылку на узел, содержащий ваш видеоконтент, в рамках запроса:

   Sub loadStream()
     sdk = m.sdk
     sdk.initSdk()
     setupVideoPlayer()
   
     request = {}
     streamData = m.top.streamData
     if streamData.type = "live"
       request = sdk.CreateLiveStreamRequest(streamData.assetKey, streamData.apiKey, streamData.networkCode)
     else if streamData.type = "vod"
       request = sdk.CreateVodStreamRequest(streamData.contentSourceId, streamData.videoId, streamData.apiKey, streamData.networkCode)
     else
       request = sdk.CreateStreamRequest()
     end if
   
     request.player = m.player
     request.adUiNode = m.top.video
   
     requestResult = sdk.requestStream(request)
     If requestResult <> Invalid
       print "Error requesting stream ";requestResult
     Else
       m.streamManager = Invalid
       While m.streamManager = Invalid
         sleep(50)
         m.streamManager = sdk.getStreamManager()
       End While
       If m.streamManager = Invalid or m.streamManager["type"] <> Invalid or m.streamManager["type"] = "error"
         errors = CreateObject("roArray", 1, True)
         print "error ";m.streamManager["info"]
         errors.push(m.streamManager["info"])
         m.top.errors = errors
       Else
         m.top.streamManagerReady = True
         addCallbacks()
         m.streamManager.start()
       End If
     End If
   End Sub
   Sdk.xml
   

2. Добавьте поля streamData и streamManagerReady , используемые в подпрограмме loadStream() :

   <field id="streamManagerReady" type="Boolean" />
   <field id="streamData" type="assocarray" />
   Sdk.xml
   

3. Если менеджер потоков недоступен, вызовите подпрограмму loadStream() из подпрограммы runThread() :

   if not m.top.streamManagerReady
     loadStream()
   End If
   Sdk.xml
   

4. Выберите между VOD и прямой трансляцией. В следующем примере представлены параметры прямой трансляции и VOD-трансляции:

   m.testLiveStream = {
     title: "Live Stream",
     assetKey: "c-rArva4ShKVIAkNfy6HUQ",
     networkCode: "21775744923",
     apiKey: "",
     type: "live"
   }
   m.testVodStream = {
     title: "VOD stream"
     contentSourceId: "2548831",
     videoId: "tears-of-steel",
     networkCode: "21775744923",
     apiKey: "",
     type: "vod"
   }
   MainScene.xml
   

   По умолчанию в этом руководстве используется поток VOD. Вы можете использовать прямую трансляцию, изменив переменную selectedStream с объекта m.testVodStream на объект m.testLiveStream .

Начать трансляцию

Создайте подпрограмму urlLoadRequested() для прослушивания потоковых данных и вызовите подпрограмму playStream() :

Sub urlLoadRequested(message as Object)
  print "Url Load Requested ";message
  data = message.getData()

  playStream(data.manifest, data.format)
End Sub
MainScene.xml

Создайте playStream() для начала воспроизведения потока:

Sub playStream(url as String, format as String)
  vidContent = createObject("RoSGNode", "ContentNode")
  vidContent.url = url
  vidContent.title = m.videoTitle
  vidContent.streamformat = format
  m.video.content = vidContent
  m.video.setFocus(true)
  m.video.visible = true
  m.video.control = "play"
  m.video.EnableCookies()
End Sub
MainScene.xml

Прослушивание метаданных потока

Создайте подпрограмму runLoop() с циклом while для запуска во время воспроизведения потока и отправки метаданных потока в IMA с помощью StreamManager.onMessage() :

Ключевой момент: для обеспечения корректного воспроизведения рекламы необходимо пересылать все сообщения в SDK.

Sub runLoop()
  ' Forward all timed metadata events.
  m.top.video.timedMetaDataSelectionKeys = ["*"]

  ' Cycle through all the fields and just listen to them all.
  m.port = CreateObject("roMessagePort")
  fields = m.top.video.getFields()
  for each field in fields
    m.top.video.observeField(field, m.port)
  end for

  while True
    msg = wait(1000, m.port)
    if m.top.video = invalid
      print "exiting"
      exit while
    end if

    m.streamManager.onMessage(msg)
    currentTime = m.top.video.position
    ' Only enable trickplay after a few seconds, in case we start with an ad,
    ' to prevent users from skipping through that ad.
    If currentTime > 3 And not m.top.adPlaying
       m.top.video.enableTrickPlay = true
    End If
  end while
End Sub
Sdk.xml

Слушайте рекламные события

Теперь, когда вы передаёте метаданные потока в IMA, IMA может генерировать рекламные события во время рекламных пауз. Создайте прослушиватели рекламных событий по мере необходимости, чтобы реагировать на них:

Function addCallbacks() as Void
  m.streamManager.addEventListener(m.sdk.AdEvent.ERROR, errorCallback)
  m.streamManager.addEventListener(m.sdk.AdEvent.START, startCallback)
  m.streamManager.addEventListener(m.sdk.AdEvent.FIRST_QUARTILE, firstQuartileCallback)
  m.streamManager.addEventListener(m.sdk.AdEvent.MIDPOINT, midpointCallback)
  m.streamManager.addEventListener(m.sdk.AdEvent.THIRD_QUARTILE, thirdQuartileCallback)
  m.streamManager.addEventListener(m.sdk.AdEvent.COMPLETE, completeCallback)
End Function

Function startCallback(ad as Object) as Void
  print "Callback from SDK -- Start called - "
End Function

Function firstQuartileCallback(ad as Object) as Void
  print "Callback from SDK -- First quartile called - "
End Function

Function midpointCallback(ad as Object) as Void
  print "Callback from SDK -- Midpoint called - "
End Function

Function thirdQuartileCallback(ad as Object) as Void
  print "Callback from SDK -- Third quartile called - "
End Function

Function completeCallback(ad as Object) as Void
  print "Callback from SDK -- Complete called - "
End Function

Function errorCallback(error as Object) as Void
  print "Callback from SDK -- Error called - "; error
  ' errors are critical and should terminate the stream.
  m.errorState = True
End Function
Sdk.xml

Добавить поддержку пропускаемой рекламы (необязательно)

Для поддержки пропускаемой рекламы необходимо добавить метод seek к объекту проигрывателя IMA DAI SDK, который программно ищет видео в указанном месте за секунды с плавающей запятой.

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

m.player.seek = Function(timeSeconds as Double)
  print "---- SDK requested seek to ----" ; timeSeconds
  m.top.video.seekMode = "accurate"
  m.top.video.seek = timeSeconds
End Function
Sdk.xml