Чтобы обсудить наши продукты и оставить отзыв о них, присоединяйтесь к официальному каналу Ad Manager Discord на сервере Google Advertising and Measurement Community .

Эта страница переведена с помощью Cloud Translation API.

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

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

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

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

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

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

Обзор IMA DAI

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

StreamRequest : Объект, определяющий запрос на потоковую передачу. Запросы на потоковую передачу могут быть как для видео по запросу, так и для прямых трансляций. Запросы на прямую трансляцию указывают ключ ресурса, а запросы на видео по запросу — идентификатор CMS и идентификатор видео. Оба типа запросов могут дополнительно включать ключ API, необходимый для доступа к указанным потокам, и сетевой код Google Ad Manager для обработки идентификаторов рекламы в SDK IMA, как указано в настройках Google Ad Manager.
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.

SDK IMA DAI зависит от рекламной платформы Roku. Для загрузки платформы добавьте следующее в manifest и Sdk.xml :

bs_libs_required=roku_ads_lib,googleima3manifest

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

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

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

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

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

Чтобы проверить, загружен ли IMA-файл, создайте логическое поле ` sdkLoaded :
```
<field id="sdkLoaded" type="Boolean" />Sdk.xml
```
Вызовите подпрограмму loadSdk() из основной подпрограммы runThread() :
```
if not m.top.sdkLoaded
  loadSdk()
End IfSdk.xml
```

Создайте функцию 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 functionMainScene.xml

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

Создайте подпрограммы-слушатели 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 SubMainScene.xml

Создайте проигрыватель IMA-стриминга

Для создания проигрывателя IMA-стримов выполните следующие действия:

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

Для создания проигрывателя потокового видео используйте метод createPlayer() .
Пусть этот проигрыватель потокового видео реализует три метода обратного вызова: loadUrl , adBreakStarted и adBreakEnded .
Отключение функции «просмотра рекламного ролика» при загрузке потока предотвращает пропуск пользователями преролла в момент начала трансляции, до того, как сработает событие начала рекламной паузы.

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 SubSdk.xml

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

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

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

Создайте и выполните запрос на потоковую передачу.

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

Создайте подпрограмму 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 SubSdk.xml

Добавьте поля streamData и streamManagerReady , используемые в подпрограмме loadStream() :
```
<field id="streamManagerReady" type="Boolean" />
<field id="streamData" type="assocarray" />Sdk.xml
```
Если менеджер потоков недоступен, вызовите подпрограмму loadStream() из подпрограммы runThread() :
```
if not m.top.streamManagerReady
  loadStream()
End IfSdk.xml
```
Выберите между видео по запросу (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 SubMainScene.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 SubMainScene.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 SubSdk.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 FunctionSdk.xml

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

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

Для поддержки пропуска рекламы необходимо также указать 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 FunctionSdk.xml