Configura con DAI de servicio completo

Selecciona la plataforma: HTML5 Android iOS tvOS Cast Roku

En esta guía, se muestra cómo integrar el SDK de IMA para DAI en una app de reproductor de video. Si quieres ver o seguir una integración de ejemplo completa, descarga el ejemplo básico de GitHub.

Descripción general de IMA para DAI

La implementación de IMA para DAI implica dos componentes principales del SDK, como se muestra en esta guía:

  • StreamRequest: Es un objeto que define una solicitud de transmisión. Las solicitudes de transmisión pueden ser para videos on demand o transmisiones en vivo. Las solicitudes de transmisión en vivo especifican una clave de recurso, mientras que las solicitudes de VOD especifican un ID de CMS y un ID de video. Ambos tipos de solicitudes pueden incluir, de forma opcional, una clave de API necesaria para acceder a las transmisiones especificadas y un código de red de Google Ad Manager para que el SDK de IMA controle los identificadores de anuncios según se especifica en la configuración de Google Ad Manager.
  • StreamManager: Es un objeto que controla las transmisiones de inserción de anuncios dinámicos y las interacciones con el backend de DAI. El administrador de transmisiones también controla los pings de seguimiento y reenvía los eventos de transmisión y de anuncios al publicador.

Requisitos previos

Reproduce el video

El reproductor de video de muestra que se proporciona reproduce un video de contenido de forma predeterminada. Implementa el reproductor de ejemplo en tu reproductor de Roku para asegurarte de que tu entorno de desarrollo esté configurado correctamente.

Convierte tu reproductor de video en un reproductor de transmisiones de IMA para DAI

Sigue estos pasos para implementar un reproductor de transmisiones.

Crea el archivo Sdk.xml

Agrega un archivo nuevo a tu proyecto junto a MainScene.xml llamado Sdk.xml y agrega el siguiente código estándar:

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>

Deberás editar ambos archivos a lo largo de esta guía.

Carga el framework de publicidad de Roku

El SDK de IMA para DAI depende del framework de publicidad de Roku. Para cargar el framework, agrega lo siguiente a manifest y Sdk.xml:

bs_libs_required=roku_ads_lib,googleima3

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

Carga el SDK de IMA para DAI

Para cargar el SDK de IMA para DAI, haz lo siguiente:

  1. Inicializa el SDK de IMA con la llamada New_IMASDK():

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

  2. Para hacer un seguimiento de si el SDK de IMA se cargó, crea un campo booleano sdkLoaded:

    <field id="sdkLoaded" type="Boolean" />

  3. Llama a la subrutina loadSdk() desde la subrutina runThread() principal:

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

  4. Crea la función loadImaSdk() en MainScene.xml para crear y ejecutar el objeto 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

  5. Llama a la función loadImaSdk() desde la función init().

  6. Crea las subrutinas de objetos de escucha onSdkLoaded() y onSdkLoadedError() para responder a los eventos de carga del 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

Crea un reproductor de transmisiones de IMA

Para crear un reproductor de transmisiones de IMA, haz lo siguiente:

  1. Crea una subrutina setupVideoPlayer() que haga lo siguiente:

    1. Usa el método createPlayer() para crear el reproductor de transmisión.

    2. Haz que ese reproductor de transmisión implemente tres métodos de devolución de llamada: loadUrl, adBreakStarted y adBreakEnded.

    3. Inhabilita la reproducción rápida cuando se cargue la transmisión para evitar que los usuarios omitan un anuncio previo al video en el instante en que se inicia la transmisión, antes de que se active el evento de inicio de la pausa publicitaria.

    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

    Agrega un método de devolución de llamada seek para admitir anuncios que se pueden omitir. Para obtener más detalles, consulta Agrega compatibilidad con anuncios que se pueden omitir.

  2. Agrega los campos urlData, adPlaying y video que se usan en la subrutina setupVideoPlayer():

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

Crea y ejecuta una solicitud de transmisión

Para solicitar tu transmisión de DAI, haz lo siguiente:

  1. Crea una subrutina loadStream() para crear y solicitar una transmisión. Para admitir la IU de anuncios, como los íconos de AdChoices, también debes pasar una referencia al nodo que contiene tu video de contenido como parte de tu solicitud:

    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

  2. Agrega los campos streamData y streamManagerReady que se usan en la subrutina loadStream():

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

  3. Si el administrador de transmisiones no está disponible, llama a la subrutina loadStream() desde la subrutina runThread():

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

  4. Selecciona entre un VOD o una transmisión en vivo. En el siguiente ejemplo, se incluyen parámetros de transmisión para una transmisión en vivo y una transmisión de 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"
}

    De forma predeterminada, en esta guía se usa la transmisión de VOD. En su lugar, puedes usar la transmisión en vivo cambiando la variable selectedStream del objeto m.testVodStream al objeto m.testLiveStream.

Inicia la transmisión

Crea la subrutina urlLoadRequested() para escuchar los datos de la transmisión y llamar a la subrutina playStream():

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

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

Crea el playStream() para iniciar la reproducción de la transmisión:

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

Escucha los metadatos de la transmisión

Crea la subrutina runLoop() con un bucle while para que se ejecute durante la reproducción de la transmisión y envíe los metadatos de la transmisión a IMA con 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

Escucha los eventos de anuncios

Ahora que pasas metadatos de transmisión al IMA, este puede emitir eventos de anuncios durante las pausas publicitarias. Crea objetos de escucha de eventos de anuncios según sea necesario para responder a estos eventos:

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

Agrega compatibilidad con anuncios que se pueden omitir (opcional)

Para admitir anuncios que se pueden omitir, debes agregar un método seek al objeto player del SDK de IMA para DAI que busque de forma programática el video en la ubicación especificada, en segundos de punto flotante.

Para admitir anuncios que se pueden omitir, también debes asegurarte de establecer el parámetro adUiNode en tu solicitud.

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