IMA SDK für die dynamische Anzeigenbereitstellung einrichten

Plattform auswählen:HTML5 Android iOS tvOS Cast Roku

Mit den IMA SDKs lassen sich Multimedia-Anzeigen ganz einfach in Ihre Websites und Apps einbinden. Mit IMA SDKs können Anzeigen von jedem VAST-konformen Ad-Server angefordert und die Anzeigenwiedergabe in Ihren Apps verwaltet werden. Mit IMA DAI SDKs senden Apps eine Streamanfrage für Anzeigen- und Contentvideos – entweder VOD- oder Liveinhalte. Das SDK gibt dann einen kombinierten Videostream zurück, sodass Sie das Umschalten zwischen Anzeigen- und Inhaltsvideo in Ihrer App nicht verwalten müssen.

Wählen Sie die DAI-Lösung aus, die Sie interessiert

Full Service Pod-Bereitstellung

Komplettservice für die dynamische Anzeigenbereitstellung

In dieser Anleitung wird gezeigt, wie Sie das IMA DAI SDK in eine einfache Videoplayer-App einbinden. Wenn Sie sich ein vollständiges Beispiel für die Integration ansehen oder die Anleitung anhand eines Beispiels nachvollziehen möchten, laden Sie das einfache Beispiel von GitHub herunter.

Hinweis:Das IMA DAI SDK für Roku unterstützt sowohl HLS- als auch DASH-Streams. Es gibt keine Implementierungsunterschiede.

Wenn Sie IMA DAI verwenden möchten, benötigen Sie ein Ad Manager 360 Advanced-Konto. Wenn Sie ein Ad Manager-Konto haben, wenden Sie sich an Ihren Account Manager, um weitere Informationen zu erhalten. Informationen zur Registrierung für Ad Manager finden Sie in der Ad Manager-Hilfe.

Hinweis:Informationen zur Integration in andere Plattformen oder zur Verwendung der clientseitigen IMA SDKs finden Sie unter Interactive Media Ads SDKs.

IMA DAI – Übersicht

Die Implementierung von IMA DAI umfasst zwei Haupt-SDK-Komponenten, wie in diesem Leitfaden beschrieben:

• StreamRequest: Ein Objekt, das eine Streamanfrage definiert. Streamanfragen können entweder für Video-on-Demand- oder Livestreams erfolgen. In Livestream-Anfragen wird ein Asset-Schlüssel angegeben, in 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 die angegebenen Streams erforderlich ist, sowie einen Google Ad Manager-Netzwerkcode, damit das IMA SDK Anzeigen-IDs 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 unsere Seite zur Kompatibilität durch, um sicherzugehen, dass Ihr geplanter Anwendungsfall unterstützt wird.
• Beispielcode für Roku-Player herunterladen
• Stellen Sie den Beispiel-Player-Code auf einem Roku-Gerät bereit, um zu prüfen, ob Ihre Entwicklungsumgebung funktioniert.

Spielen Sie Ihr Video ab.

Der bereitgestellte Beispielvideoplayer gibt standardmäßig ein Contentvideo wieder. Stelle den Beispielplayer auf deinem Roku-Player bereit, um sicherzugehen, dass deine Entwicklungsumgebung richtig eingerichtet ist.

Videoplayer in einen IMA DAI-Streamplayer umwandeln

So implementieren Sie einen Stream-Player:

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.

Laden Sie das Roku Advertising Framework.

Das IMA DAI SDK hängt vom Roku Advertising Framework ab. Fügen Sie Folgendes zu manifest und Sdk.xml 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 New_IMASDK()-Aufruf:

   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 erfassen, 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() über die Funktion init() auf.

6. Erstellen Sie die Unterroutinen für die Listener 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-Streamplayer:

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

   1. Verwenden Sie die Methode createPlayer(), um den Stream-Player zu erstellen.

   2. Der Stream-Player muss drei Callback-Methoden implementieren: loadUrl, adBreakStarted und adBreakEnded.

   3. Deaktiviere die Trick Play-Funktion, wenn der Stream geladen wird, damit Nutzer keine Pre-Roll-Anzeige überspringen können, sobald der Stream beginnt, bevor das Ereignis „ad break started“ 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 Unterroutine 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. Damit die Anzeigen-Benutzeroberfläche, z. B. AdChoices-Symbole, unterstützt wird, müssen Sie auch eine Referenz auf den Knoten übergeben, der Ihr Content-Video 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 Unterroutine loadStream() verwendet werden:

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

3. Wenn der Stream-Manager 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 und einem Livestream aus. Im folgenden Beispiel sind Stream-Parameter für einen Livestream und einen VOD-Stream enthalten:

   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 m.testVodStream-Objekt zum m.testLiveStream-Objekt ändern.

Stream starten

Erstellen Sie die Unterroutine urlLoadRequested(), um die Streamdaten zu erfassen und die Unterroutine playStream() aufzurufen:

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

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

Erstelle 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 Streammetadaten warten

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

Wichtig :Sie müssen alle Nachrichten an das SDK weiterleiten, damit die Anzeigen korrekt wiedergegeben werden.

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 Listener für Anzeigenereignisse, 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 die Methode seek hinzufügen, mit der das Video programmatisch an die angegebene Stelle gesucht wird (in Gleitkommazahlen).

Damit überspringbare Anzeigen unterstützt werden, 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