Configurare l'SDK IMA per DAI

Seleziona la piattaforma: HTML5 Android iOS tvOS Cast Roku

Gli SDK IMA semplificano l'integrazione di annunci multimediali nei tuoi siti web e nelle tue app. Gli SDK IMA possono richiedere annunci da qualsiasi ad server compatibile con VAST e gestire la riproduzione degli annunci nelle tue app. Con gli SDK IMA DAI, le app effettuano una richiesta di streaming per l'annuncio e il video dei contenuti, che possono essere VOD o live. L'SDK restituisce quindi uno stream video combinato, in modo da non dover gestire il passaggio tra l'annuncio e il video di contenuti all'interno dell'app.

Seleziona la soluzione DAI che ti interessa

Servizio completo Pubblicazione di pod

DAI con servizio completo

Questa guida mostra come integrare l'SDK IMA DAI in una semplice app video player. Se vuoi visualizzare o seguire un esempio di integrazione completato, scarica l'esempio di base da GitHub.

Nota:L'SDK IMA DAI per Roku supporta sia gli stream HLS che DASH, senza differenze di implementazione.

Per utilizzare IMA DAI, devi disporre di un account Ad Manager 360 Advanced. Se hai un account Ad Manager, contatta il tuo account manager per maggiori dettagli. Per informazioni sull'iscrizione ad Ad Manager, visita il Centro assistenza Ad Manager.

Nota:per informazioni sull'integrazione con altre piattaforme o sull'utilizzo degli SDK IMA lato client, consulta SDK Interactive Media Ads.

Panoramica di IMA DAI

L'implementazione di IMA DAI prevede due componenti SDK principali, come illustrato in questa guida:

• StreamRequest: un oggetto che definisce una richiesta di stream. Le richieste di stream possono riguardare video on demand o live streaming. Le richieste di live streaming specificano una chiave asset, mentre le richieste VOD specificano un ID CMS e un ID video. Entrambi i tipi di richiesta possono includere facoltativamente una chiave API necessaria per accedere agli stream specificati e un codice di rete Google Ad Manager per l'SDK IMA per gestire gli identificatori pubblicità come specificato nelle impostazioni di Google Ad Manager.
• StreamManager: Un oggetto che gestisce i flussi di inserimento di annunci dinamici e le interazioni con il backend DAI. Lo stream manager gestisce anche i ping di monitoraggio e inoltra gli eventi di stream e annunci al publisher.

Prerequisiti

• Consulta la nostra pagina sulla compatibilità per assicurarti che il tuo caso d'uso previsto sia supportato.
• Scarica il nostro codice di esempio del lettore Roku
• Esegui il deployment del codice del lettore di esempio su un dispositivo Roku per verificare che la configurazione di sviluppo funzioni.

Riprodurre il tuo video

Il video player di esempio fornito riproduce un video di contenuti pronto all'uso. Esegui il deployment del player di esempio sul tuo player Roku per assicurarti che l'ambiente di sviluppo sia configurato correttamente.

Trasforma il tuo video player in un player di streaming IMA DAI

Per implementare un player di streaming:

Crea Sdk.xml

Aggiungi un nuovo file al progetto insieme a MainScene.xml chiamato Sdk.xml e aggiungi il seguente 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>

Devi modificare entrambi i file nel corso di questa guida.

Carica il framework pubblicitario di Roku

L'SDK IMA DAI dipende dal framework pubblicitario di Roku. Per caricare il framework, aggiungi quanto segue a manifest e Sdk.xml:

bs_libs_required=roku_ads_lib,googleima3
manifest

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

Carica l'SDK IMA DAI

Per caricare l'SDK IMA DAI, procedi nel seguente modo:

1. Inizializza l'SDK IMA con la chiamata New_IMASDK():

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

2. Verifica se IMA è stato caricato creando un campo booleano sdkLoaded:

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

3. Chiama la subroutine loadSdk() dalla subroutine principale runThread():

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

4. Crea la funzione loadImaSdk() in MainScene.xml per creare ed eseguire l'oggetto 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. Chiama la funzione loadImaSdk() dalla funzione init().

6. Crea le subroutine del listener onSdkLoaded() e onSdkLoadedError() per rispondere agli eventi di caricamento dell'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
   

Creare un lettore di stream IMA

Per creare un lettore di stream IMA:

1. Crea una subroutine setupVideoPlayer() che:

   1. Utilizza il metodo createPlayer() per creare il player dello stream.

   2. Fai in modo che il lettore di stream implementi tre metodi di callback: loadUrl, adBreakStarted e adBreakEnded.

   3. Disattiva la riproduzione con trucchi quando lo stream viene caricato per impedire agli utenti di saltare un pre-roll nell'istante in cui lo stream inizia, prima che venga attivato l'evento di inizio interruzione pubblicitaria.

   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
   

   Aggiungi un metodo di callback seek per supportare gli annunci ignorabili. Per maggiori dettagli, vedi Aggiungere il supporto per gli annunci ignorabili.

2. Aggiungi i campi urlData, adPlaying e video utilizzati nella subroutine setupVideoPlayer():

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

Crea ed esegui una richiesta di stream

Per richiedere il tuo stream DAI:

1. Crea una subroutine loadStream() per creare e richiedere uno stream. Per supportare l'interfaccia utente degli annunci, ad esempio le icone di Scelte pubblicitarie, devi anche passare un riferimento al nodo contenente il video di contenuti come parte della richiesta:

   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. Aggiungi i campi streamData e streamManagerReady utilizzati nella subroutine loadStream():

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

3. Se lo stream manager non è disponibile, chiama la subroutine loadStream() dalla subroutine runThread():

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

4. Seleziona un VOD o un live streaming. L'esempio seguente include i parametri dello stream per un live streaming e uno stream 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
   

   Per impostazione predefinita, questa guida utilizza lo stream VOD. Puoi utilizzare il live streaming modificando la variabile selectedStream dall'oggetto m.testVodStream all'oggetto m.testLiveStream.

Avviare lo stream

Crea la subroutine urlLoadRequested() per ascoltare i dati dello stream e chiama la subroutine playStream():

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

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

Crea il playStream() per avviare la riproduzione dello stream:

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

Ascolta i metadati dello stream

Crea la subroutine runLoop() con un ciclo while da eseguire durante la riproduzione dello stream e invia i metadati dello stream a IMA utilizzando StreamManager.onMessage():

Punto chiave: devi inoltrare tutti i messaggi all'SDK per garantire la corretta riproduzione degli annunci.

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

Ascolta gli eventi degli annunci

Ora che trasmetti i metadati dello stream a IMA, IMA può emettere eventi annuncio durante le interruzioni pubblicitarie. Crea listener di eventi pubblicitari in base alle esigenze per rispondere agli eventi pubblicitari:

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

Aggiungere il supporto per gli annunci ignorabili (facoltativo)

Per supportare gli annunci ignorabili, devi aggiungere un metodo seek all'oggetto player dell'SDK IMA DAI che cerca in modo programmatico il video nella posizione specificata, in secondi con virgola mobile.

Per supportare gli annunci ignorabili, devi anche assicurarti di impostare adUiNode nella tua richiesta.

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