Как настроить динамическую вставку объявлений в режиме полного обслуживания

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

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

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

Чтобы использовать IMA DAI, у вас должен быть аккаунт Менеджера рекламы 360 Advanced. Если у вас есть аккаунт Менеджера рекламы, обратитесь за дополнительной информацией к менеджеру по работе с клиентами. Информацию о том, как зарегистрироваться в Менеджере рекламы, можно найти в Справочном центре.

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

Обзор IMA DAI

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

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

Требования

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

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

В примере видеопроигрывателя сразу же воспроизводится видеоконтент. Разверните пример проигрывателя на своем проигрывателе Roku, чтобы убедиться, что среда разработки настроена правильно.

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

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

Создание файла Sdk.xml

Добавьте в проект новый файл Sdk.xml рядом с MainScene.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 Advertising Framework

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. Отключите перемотку при загрузке потока, чтобы пользователи не могли пропустить видеорекламу в начале ролика до того, как будет зарегистрировано событие начала рекламной паузы.

   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
   

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

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

1. Создайте подпрограмму loadStream(), чтобы создать поток и отправить запрос. Чтобы поддерживать элементы интерфейса объявлений, например значки "Выбор рекламы", в запрос также необходимо добавить ссылку на узел, содержащий видеоконтент.

   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. Выберите видео по запросу или трансляцию. В примере ниже приведены параметры для прямой трансляции и видео по запросу.

   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
   

   По умолчанию в этом руководстве используется видео по запросу. Чтобы использовать прямую трансляцию, измените переменную 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 в объект player 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