Как настроить IMA SDK для динамической вставки объявлений

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

Выберите решение для динамической вставки объявлений

Полный набор функций динамической вставки объявлений

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

Общие сведения о динамической вставке объявлений с помощью IMA SDK

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

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

Требования

• Проверьте, поддерживается ли ваш вариант использования, на странице совместимости.
• Скачайте образец кода проигрывателя 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

IMA DAI SDK зависит от рекламного фреймворка Roku. Чтобы загрузить фреймворк, добавьте в 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
   

   По умолчанию в этом руководстве используется трансляция видео по запросу. Вместо этого можно использовать livestream, изменив переменную 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():

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