Esta página foi traduzida pela API Cloud Translation.

Começar a usar o SDK de DAI do IMA

Os SDKs do IMA facilitam a integração de anúncios multimídia aos seus sites e apps. Os SDKs do IMA podem solicitar anúncios de qualquer servidor compatível com VAST e gerenciar a reprodução de anúncios nos seus apps. Com os SDKs do IMA DAI, os apps fazem uma solicitação de transmissão para anúncios e vídeos de conteúdo, seja VOD ou conteúdo ao vivo. Em seguida, o SDK retorna um stream de vídeo combinado para que você não precise alternar entre vídeos de anúncios e de conteúdo no seu app.

Selecione a solução de DAI de seu interesse

DAI de serviço completo

Este guia demonstra como integrar o SDK do IMA DAI a um app simples de player de vídeo. Se você quiser conferir ou acompanhar uma integração de exemplo completa, faça o download do exemplo básico no GitHub.

Visão geral da DAI do IMA

A implementação do IMA DAI envolve dois componentes principais do SDK, conforme demonstrado neste guia:

StreamRequest: um objeto que define uma solicitação de transmissão. As solicitações de stream podem ser para vídeo on demand ou transmissões ao vivo. As solicitações especificam um ID de conteúdo, uma chave de API ou token de autenticação e outros parâmetros.
StreamManager: um objeto que processa fluxos de inserção de anúncios dinâmicos e interações com o back-end da DAI. O gerenciador de stream também processa pings de rastreamento e encaminha eventos de stream e de anúncio para o editor.

Pré-requisitos

Leia nossa página de compatibilidade para confirmar se o caso de uso pretendido é aceito.
Faça o download do nosso código de player de exemplo do Roku.
Implante o código de amostra do player em um dispositivo Roku para verificar se a configuração de desenvolvimento está funcionando.

Assistir o vídeo

O player de vídeo de exemplo fornecido reproduz um vídeo de conteúdo imediatamente. Implante o player de exemplo no seu player Roku para garantir que o ambiente de desenvolvimento esteja configurado corretamente.

Transformar seu player de vídeo em um player de stream da IMA DAI

Siga estas etapas para implementar um player de streaming.

Criar o Sdk.xml

Adicione um novo arquivo ao projeto com MainScene.xml chamado Sdk.xml e adicione o seguinte código boilerplate:

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>

Você vai precisar editar esses dois arquivos ao longo deste guia.

Carregar o Roku Advertising Framework

O SDK de DAI do IMA depende do Roku Advertising Framework. Para carregar o framework, adicione o seguinte a manifest e Sdk.xml:

manifesto

bs_libs_required=roku_ads_lib,googleima3

Sdk.xml

Library "Roku_Ads.brs"
Library "IMA3.brs"

Carregar o SDK do IMA DAI

A primeira etapa para carregar o stream de Inserção de anúncios dinâmicos do IMA é carregar e inicializar o SDK DAI do IMA. O código a seguir carrega o script do SDK de DAI do IMA.

Sdk.xml

<interface>
  <field id="sdkLoaded" type="Boolean" />
  <field id="errors" type="stringarray" />
</interface>
...
Sub init()
  m.top.functionName = "runThread"
End Sub

Sub runThread()
  if not m.top.sdkLoaded
    loadSdk()
  End If
End Sub

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

Agora, inicie essa tarefa em MainScene.xml e remova a chamada para carregar o stream de conteúdo.

MainScene.xml

function init()
  m.video = m.top.findNode("myVideo")
  m.video.notificationinterval = 1
  loadImaSdk()
end function

function loadImaSdk() as void
  m.sdkTask = createObject("roSGNode", "imasdk")
  m.sdkTask.observeField("sdkLoaded", "onSdkLoaded")
  m.sdkTask.observeField("errors", "onSdkLoadedError")

  m.sdkTask.control = "RUN"
end function

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

Criar um player de stream do IMA

Em seguida, use o roVideoScreen para criar um player de stream do IMA. Esse player de streaming implementa três métodos de callback: loadUrl, adBreakStarted e adBreakEnded. Além disso, desative a reprodução de truque quando o stream for carregado. Isso impede que os usuários pulem um anúncio precedente no momento em que ele começa, antes que o evento de início do intervalo de anúncio seja acionado.

Sdk.xml

<interface>
  <field id="sdkLoaded" type="Boolean" />
  <field id="errors" type="stringarray" />
  <field id="urlData" type="assocarray" />
  <field id="adPlaying" type="Boolean" />
  <field id="video" type="Node" />
</interface>
...
Sub setupVideoPlayer()
  sdk = m.sdk
  m.player = sdk.createPlayer()
  m.player.top = m.top
  m.player.loadUrl = Function(urlData)
    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
End Sub

Criar e executar uma solicitação de stream

Agora que você tem um player de stream, pode criar e executar uma solicitação de stream. Este exemplo tem dados de uma transmissão ao vivo e uma transmissão VOD. Ele usa a transmissão de VOD, mas você pode usar a transmissão ao vivo mudando selectedStream de m.testVodStream para m.testLiveStream.

Para oferecer suporte à AdUI, como os ícones de Opções de anúncios, você também precisa transmitir uma referência ao nó que contém o conteúdo de vídeo como parte da solicitação.

MainScene.xml

function init()
  m.video = m.top.findNode("myVideo")
  m.video.notificationinterval = 1
  m.testLiveStream = {
    title: "Livestream",
    assetKey: "sN_IYUG8STe1ZzhIIE_ksA",
    apiKey: "",
    type: "live"
  }
  m.testVodStream = {
    title: "VOD stream"
    contentSourceId: "2548831",
    videoId: "tears-of-steel",
    apiKey: "",
    type: "vod"
  }
  loadImaSdk()
end function

function loadImaSdk() as void
  m.sdkTask = createObject("roSGNode", "imasdk")
  m.sdkTask.observeField("sdkLoaded", "onSdkLoaded")
  m.sdkTask.observeField("errors", "onSdkLoadedError")

  selectedStream = m.testVodStream
  m.videoTitle = selectedStream.title
  m.sdkTask.streamData = selectedStream

  m.sdkTask.video = m.video
  m.sdkTask.control = "RUN"
end function

Sdk.xml

<interface>
  <field id="sdkLoaded" type="Boolean" />
  <field id="errors" type="stringarray" />
  <field id="urlData" type="assocarray" />
  <field id="adPlaying" type="Boolean" />
  <field id="video" type="Node" />
  <field id="streamData" type="assocarray" />
  <field id="streamManagerReady" type="Boolean" />
</interface>
...
Sub runThread()
  if not m.top.sdkLoaded
    loadSdk()
  End If
  if not m.top.streamManagerReady
    loadStream()
  End If
End Sub

Sub loadStream()
  sdk = m.sdk
  sdk.initSdk()
  setupVideoPlayer()

  request = {}
  streamData = m.top.streamData
  if streamData.type = "live"
    request = sdk.CreateLiveStreamRequest(streamData.assetKey, streamData.apiKey)
  else if streamData.type = "vod"
    request = sdk.CreateVodStreamRequest(streamData.contentSourceId, streamData.videoId, streamData.apiKey)
  else
    request = sdk.CreateStreamRequest()
  end if

  request.player = m.player
  request.videoObject = m.top.video
  ' Required to support UI elements for 'Why This Ad?' and skippability
  request.adUiNode = m.top.video

  requestResult = sdk.requestStream(request)
  If requestResult &lt;&gt; 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"] &lt;&gt; 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

Adicione listeners de eventos e inicie o stream

Depois de solicitar seu stream, restam apenas algumas ações: adicionar listeners de eventos para acompanhar o progresso do anúncio, iniciar seu stream e encaminhar mensagens do Roku para o SDK.

MainScene.xml

function loadImaSdk() as void
  m.sdkTask = createObject("roSGNode", "imasdk")
  m.sdkTask.observeField("sdkLoaded", "onSdkLoaded")
  m.sdkTask.observeField("errors", "onSdkLoadedError")

  selectedStream = m.testVodStream
  m.videoTitle = selectedStream.title
  m.sdkTask.streamData = selectedStream

  m.sdkTask.observeField("urlData", "urlLoadRequested")
  m.sdkTask.video = m.video
  m.sdkTask.control = "RUN"
end function

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

  playStream(data.manifest)
End Sub

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

Sdk.xml

Sub runThread()
  if not m.top.sdkLoaded
    loadSdk()
  End If
  if not m.top.streamManagerReady
    loadStream()
  End If
  If m.top.streamManagerReady
    runLoop()
  End If
End Sub

Sub runLoop()
  m.top.video.timedMetaDataSelectionKeys = ["*"]

  m.port = CreateObject("roMessagePort")

  ' Listen to all fields.

  ' IMPORTANT: Failure to listen to the position and timedmetadata fields
  ' could result in ad impressions not being reported.
  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
    If currentTime > 3 And not m.top.adPlaying
       m.top.video.enableTrickPlay = true
    End If
  end while
End Sub

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
  m.errorState = True
End Function

Adicionar suporte a anúncios puláveis (opcional)

Para oferecer suporte a anúncios puláveis, adicione um método seek ao objeto player do SDK da DAI do IMA que procura o vídeo no local especificado de forma programática, em segundos de ponto flutuante.

Para oferecer suporte a anúncios puláveis, você também precisa definir o adUiNode na sua solicitação.

Sdk.xml

  m.player.loadUrl = Function(urlData)
    m.top.video.enableTrickPlay = false
    m.top.urlData = urlData
  End Function

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

  m.player.adBreakStarted = Function(adBreakInfo as Object)
    print "---- Ad Break Started ---- "
    m.top.adPlaying = True
    m.top.video.enableTrickPlay = false
  End Function