Mit Full-Service-DAI einrichten

In diesem Leitfaden wird gezeigt, wie Sie das IMA DAI SDK in eine Videoplayer-App einbinden. Wenn Sie sich eine vollständige Beispielintegration ansehen oder nachvollziehen möchten, laden Sie das einfache Beispiel von GitHub herunter.

IMA DAI – Übersicht

Die Implementierung von IMA DAI umfasst zwei Hauptkomponenten des SDK, wie in diesem Leitfaden gezeigt:

• StreamRequest: Ein Objekt, das eine Streamanfrage definiert. Streamanfragen können entweder für Video-on-Demand- oder Livestreams gestellt werden. Bei Livestream-Anfragen wird ein Asset-Schlüssel angegeben, bei VOD-Anfragen eine CMS-ID und eine Video-ID. Beide Anfragetypen können optional einen API-Schlüssel enthalten, der für den Zugriff auf bestimmte Streams erforderlich ist, sowie einen Google Ad Manager-Netzwerkcode, damit das IMA SDK Anzeigenkennungen gemäß den Google Ad Manager-Einstellungen verarbeiten kann.
• StreamManager: Ein Objekt, das Streams für die dynamische Anzeigenbereitstellung und Interaktionen mit dem Backend für die dynamische Anzeigenbereitstellung verarbeitet. Der Stream-Manager verarbeitet auch Tracking-Pings und leitet Stream- und Anzeigenereignisse an den Publisher weiter.

Vorbereitung

• Lesen Sie sich die Seite zur Kompatibilität durch, um sicherzugehen, dass Ihr Anwendungsfall unterstützt wird.
• Beispiel-Player-Code für Roku herunterladen
• Stellen Sie den Beispielcode für den Player auf einem Roku-Gerät bereit, um zu prüfen, ob Ihre Entwicklungsumgebung funktioniert.

Spielen Sie Ihr Video ab.

Der bereitgestellte Beispiel-Videoplayer spielt ein Contentvideo sofort ab. Stellen Sie den Beispielplayer auf Ihrem Roku-Player bereit, um zu prüfen, ob Ihre Entwicklungsumgebung richtig eingerichtet ist.

Videoplayer in einen IMA-DAI-Streamplayer umwandeln

So implementieren Sie einen Streamplayer:

Sdk.xml erstellen

Fügen Sie Ihrem Projekt neben MainScene.xml eine neue Datei mit dem Namen Sdk.xml hinzu und fügen Sie den folgenden Boilerplate-Code ein:

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>

Sie müssen beide Dateien im Laufe dieser Anleitung bearbeiten.

Roku Advertising Framework laden

Das IMA DAI SDK ist vom Roku Advertising Framework abhängig. Fügen Sie manifest und Sdk.xml Folgendes hinzu, um das Framework zu laden:

bs_libs_required=roku_ads_lib,googleima3
manifest

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

IMA DAI SDK laden

So laden Sie das IMA DAI SDK:

1. Initialisieren Sie das IMA SDK mit dem Aufruf New_IMASDK():

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

2. Erstellen Sie ein boolesches Feld sdkLoaded, um zu prüfen, ob IMA geladen wurde:

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

3. Rufen Sie die Unterroutine loadSdk() aus der Hauptunterroutine runThread() auf:

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

4. Erstellen Sie die Funktion loadImaSdk() in MainScene.xml, um das Objekt sdkTask zu erstellen und auszuführen:

   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. Rufen Sie die Funktion loadImaSdk() aus der Funktion init() auf.

6. Erstellen Sie die Listener-Unterroutinen onSdkLoaded() und onSdkLoadedError(), um auf SDK-Ladeereignisse zu reagieren:

   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
   

IMA-Streamplayer erstellen

So erstellen Sie einen IMA-Stream-Player:

1. Erstellen Sie eine setupVideoPlayer()-Unterroutine, die Folgendes ausführt:

   1. Verwenden Sie die Methode createPlayer(), um den Streamplayer zu erstellen.

   2. Lassen Sie diesen Streamplayer drei Callback-Methoden implementieren: loadUrl, adBreakStarted und adBreakEnded.

   3. Deaktiviere die Trickwiedergabe, wenn der Stream geladen wird, um zu verhindern, dass Nutzer eine Pre-Roll-Anzeige überspringen, sobald der Stream gestartet wird, bevor das Ereignis „Werbeunterbrechung gestartet“ ausgelöst wird.

   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
   

   Fügen Sie eine seek-Callback-Methode hinzu, um überspringbare Anzeigen zu unterstützen. Weitere Informationen finden Sie unter Unterstützung für überspringbare Anzeigen hinzufügen.

2. Fügen Sie die Felder urlData, adPlaying und video hinzu, die in der Subroutine setupVideoPlayer() verwendet werden:

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

Streamanfrage erstellen und ausführen

So fordern Sie Ihren DAI-Stream an:

1. Erstellen Sie eine loadStream()-Unterroutine, um einen Stream zu erstellen und anzufordern. Wenn Sie Anzeigen-UI-Elemente wie Datenschutzinfo-Symbole unterstützen möchten, müssen Sie in Ihrer Anfrage auch einen Verweis auf den Knoten übergeben, der Ihr Contentvideo enthält:

   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. Fügen Sie die Felder streamData und streamManagerReady hinzu, die in der Subroutine loadStream() verwendet werden:

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

3. Wenn der Streammanager nicht verfügbar ist, rufen Sie die Unterroutine loadStream() aus der Unterroutine runThread() auf:

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

4. Wähle zwischen einem VOD oder einem Livestream aus. Das folgende Beispiel enthält Streamparameter für einen Livestream und einen VOD-Stream:

   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
   

   In diesem Leitfaden wird standardmäßig der VOD-Stream verwendet. Sie können stattdessen den Livestream verwenden, indem Sie die Variable selectedStream vom Objekt m.testVodStream in das Objekt m.testLiveStream ändern.

Stream starten

Erstellen Sie die Subroutine urlLoadRequested(), um auf die Streamdaten zu warten und die Subroutine playStream() aufzurufen:

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

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

Erstellen Sie die playStream(), um die Streamwiedergabe zu starten:

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

Auf Stream-Metadaten warten

Erstelle die Unterroutine runLoop() mit einer while-Schleife, die während der Streamwiedergabe ausgeführt wird und Streammetadaten mit StreamManager.onMessage() an IMA sendet:

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

Auf Anzeigenereignisse warten

Da Sie jetzt Stream-Metadaten an IMA übergeben, kann IMA während Werbeunterbrechungen Anzeigenereignisse ausgeben. Erstellen Sie nach Bedarf Anzeigen-Event-Listener, um auf Anzeigenereignisse zu reagieren:

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

Unterstützung für überspringbare Anzeigen hinzufügen (optional)

Damit überspringbare Anzeigen unterstützt werden, müssen Sie dem player-Objekt des IMA DAI SDK eine seek-Methode hinzufügen, die das Video programmatisch an die angegebene Position in Gleitkomma-Sekunden springen lässt.

Wenn Sie überspringbare Anzeigen unterstützen möchten, müssen Sie in Ihrer Anfrage auch adUiNode festlegen.

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