Configura el SDK de IMA para la DAI

Selecciona la plataforma: HTML5 Android iOS tvOS Cast Roku

Los SDK de IMA facilitan la integración de anuncios multimedia en tus sitios web y aplicaciones. Los SDKs de IMA pueden solicitar anuncios de cualquier servidor de anuncios compatible con VAST y administrar la reproducción de anuncios en tus aplicaciones. Con los SDKs de IMA DAI, las apps realizan una solicitud de transmisión para el video del anuncio y el contenido, ya sea VOD o contenido en vivo. Luego, el SDK devuelve una transmisión de video combinada, de modo que no tengas que administrar el cambio entre el anuncio y el video de contenido en tu app.

Selecciona la solución de DAI que te interesa

Servicio completo Publicación de segmentos

DAI de servicio completo

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

Nota: El SDK de IMA DAI para Roku admite transmisiones HLS y DASH, sin diferencias de implementación.

Para usar la DAI de IMA, debes tener una cuenta de Ad Manager 360 Advanced. Si tienes una cuenta de Ad Manager, comunícate con tu administrador de cuentas para obtener más detalles. Para obtener información sobre cómo registrarte en Ad Manager, visita el Centro de ayuda de Ad Manager.

Nota: Para obtener información sobre la integración con otras plataformas o sobre el uso de los SDKs de IMA del cliente, consulta SDKs de anuncios multimedia interactivos.

Descripción general de la DAI de IMA

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

• StreamRequest: 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: 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

• Consulta nuestra página de compatibilidad para asegurarte de que se admita el caso de uso previsto.
• Descarga nuestro código de muestra del reproductor de Roku
• Implementa el código de muestra del reproductor en un dispositivo Roku para verificar que la configuración de desarrollo funcione.

Reproduce el video

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

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

Sigue estos pasos para implementar un reproductor de transmisión.

Crea 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 marco de trabajo de publicidad de Roku

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

bs_libs_required=roku_ads_lib,googleima3
manifest

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

Carga el SDK de IMA DAI

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

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

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

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

   <field id="sdkLoaded" type="Boolean" />
   Sdk.xml
   

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

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

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

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

6. Crea las subrutinas 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
   MainScene.xml
   

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 el avance rápido cuando se cargue la transmisión para evitar que los usuarios omitan un anuncio previo al video en el instante en que comience 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
   Sdk.xml
   

   Agrega un método de devolución de llamada seek para admitir anuncios que se pueden omitir. Para obtener más detalles, consulta Cómo agregar 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" />
   Sdk.xml
   

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

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

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

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

4. Selecciona entre un VOD o una transmisión en vivo. En el siguiente ejemplo, se muestran los 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"
   }
   MainScene.xml
   

   De forma predeterminada, esta guía usa la transmisión de VOD. Puedes usar la transmisión en vivo en su lugar si cambias 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
MainScene.xml

Crea el objeto 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
MainScene.xml

Cómo escuchar 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():

Punto clave: Debes reenviar todos los mensajes al SDK para garantizar la reproducción correcta de los anuncios.

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

Cómo detectar eventos de anuncios

Ahora que pasas metadatos del flujo a IMA, IMA puede emitir eventos de anuncios durante las pausas publicitarias. Crea los objetos de escucha de eventos de anuncios según sea necesario para responder a los eventos de anuncios:

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

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 DAI de IMA 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 configurar 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
Sdk.xml