Commencer

Restez organisé à l'aide des collections Enregistrez et classez les contenus selon vos préférences.

Les SDK IMA facilitent l'intégration d'annonces multimédias dans vos sites Web et vos applications. Les SDK IMA peuvent demander des annonces à partir de n'importe quel ad server compatible VAST et gérer la lecture des annonces dans vos applications. Avec les SDK d'insertion dynamique d'annonce IMA, les applications envoient des demandes de flux d'annonces et de vidéos de contenu (VOD ou contenu en direct). Le SDK renvoie ensuite un flux vidéo combiné, ce qui vous évite d'avoir à gérer le passage d'une annonce à une vidéo de contenu dans votre application.

Ce guide explique comment intégrer le SDK IMA à une application de lecteur vidéo simple. Si vous souhaitez afficher ou suivre un exemple d'intégration terminé, téléchargez l'exemple de base depuis GitHub.

Présentation de l'insertion dynamique d'annonce IMA

La mise en œuvre de l'insertion dynamique d'annonce IMA implique deux composants principaux du SDK, comme indiqué dans ce guide:

  • StreamRequest : objet qui définit une requête de flux. Il peut s'agir de vidéos à la demande ou de diffusions en direct. Les requêtes spécifient un Content ID, ainsi qu'une clé API ou un jeton d'authentification, ainsi que d'autres paramètres.
  • StreamManager : objet qui gère les flux d'insertion dynamique d'annonce et les interactions avec le backend d'insertion dynamique d'annonce. Le gestionnaire de flux gère également le suivi des pings et transmet les événements de flux et d'annonce à l'éditeur.

Conditions préalables

Avant de commencer:

  • Lisez notre page de compatibilité pour vous assurer que votre cas d'utilisation prévu est compatible.
  • Téléchargez notre exemple de code de lecteur Roku.
  • Déployez l'exemple de code de lecteur ci-dessus sur un appareil Roku pour vérifier que votre configuration de développement fonctionne.

Lire la vidéo

L'exemple de lecteur vidéo fourni lit un contenu vidéo prêt à l'emploi. Déployez l'exemple de lecteur sur votre lecteur Roku pour vous assurer que votre environnement de développement est correctement configuré.

Transformer votre lecteur vidéo en lecteur de flux d'insertion dynamique d'annonce IMA

Créer un fichier Sdk.xml

Ajoutez un fichier à votre projet en plus de MainScene.xml appelé Sdk.xml, puis ajoutez le code récurrent suivant:

Fichier 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>

Vous devez modifier ces deux fichiers tout au long de ce guide. Un titre au-dessus de chaque extrait de code indique dans quel fichier vous devez ajouter cet extrait.

Charger le framework publicitaire Roku

Le SDK IMA dépend du cadre publicitaire Roku. Pour charger le framework, ajoutez les éléments suivants à manifest et Sdk.xml:

fichier manifeste
bs_libs_required=roku_ads_lib,googleima3
Fichier sdk.xml
Library "Roku_Ads.brs"
Library "IMA3.brs"

Charger le SDK IMA

Pour charger votre flux d'insertion dynamique d'annonces IMA, la première étape consiste à charger et à initialiser le SDK IMA. La commande suivante charge le script du SDK IMA.

Fichier sdk.xml
<interface>
  <field id="sdkLoaded" type="Boolean" />
  <field id="errors" type="stringarray" />
</interface>

sub init()
  m.top.functionName = "runThread"
End Sub

sub runThread()
  if not m.top.sdkLoaded
    loadSdk()
  End If
End Sub

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

À présent, démarrez cette tâche dans MainScene.xml et supprimez l'appel pour charger le flux de contenu.

Fichierprincipal.xml
function init()
  m.video = m.top.findNode("myVideo")
  m.video.notificationinterval = 1
  loadImaSdk()
end function

function loadImaSdk() as void
  m.sdkTask = createObject("roSGNode", "imasdk")
  m.sdkTask.observeField("sdkLoaded", "onSdkLoaded")
  m.sdkTask.observeField("errors", "onSdkLoadedError")

  m.sdkTask.control = "RUN"
end function

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

Créer un lecteur de flux IMA

Vous devez ensuite utiliser votre roVideoScreen existant pour créer un lecteur de flux IMA. Ce lecteur de flux implémente trois méthodes de rappel : loadUrl, adBreakStarted et adBreakEnded. Désactivez également les tours de jeu lorsque le flux est chargé. Cela permet aux utilisateurs d'ignorer une annonce vidéo pré-roll au moment où elle commence, avant le déclenchement de l'événement de début de la coupure publicitaire.

Fichier sdk.xml
<interface>
  <field id="sdkLoaded" type="Boolean" />
  <field id="errors" type="stringarray" />
  <field id="urlData" type="assocarray" />
  <field id="adPlaying" type="Boolean" />
  <field id="video" type="Node" />
</interface>

...
sub setupVideoPlayer()
  sdk = m.sdk
  m.player = sdk.createPlayer()
  m.player.top = m.top
  m.player.loadUrl = Function(urlData)
    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 Float)
    print "---- SDK requested seek to ----" ; timeSeconds
    m.top.video.seekMode = "accurate"
    m.top.video.seek = timeSeconds
  End Function
End Sub

Créer et exécuter une requête de flux

Maintenant que vous disposez d'un lecteur de flux, vous pouvez créer et exécuter une requête de flux. Cet exemple contient des données pour un flux en direct et un flux de vidéo à la demande. Le flux de vidéo à la demande est actuellement utilisé. Pour utiliser le direct plutôt que la vidéo à la demande, remplacez selectedStream m.testVodStream par m.testLiveStream.

Pour être compatible avec AdUI, comme les icônes adChoices, vous devez également transmettre une référence au nœud contenant votre contenu vidéo dans votre requête.

Fichierprincipal.xml
function init()
  m.video = m.top.findNode("myVideo")
  m.video.notificationinterval = 1
  m.testLiveStream = {
    title: "Live Stream",
    assetKey: "sN_IYUG8STe1ZzhIIE_ksA",
    apiKey: "",
    type: "live"
  }
  m.testVodStream = {
    title: "VOD stream"
    contentSourceId: "2528370",
    videoId: "tears-of-steel",
    apiKey: "",
    type: "vod"
  }
  loadImaSdk()
end function

function loadImaSdk() as void
  m.sdkTask = createObject("roSGNode", "imasdk")
  m.sdkTask.observeField("sdkLoaded", "onSdkLoaded")
  m.sdkTask.observeField("errors", "onSdkLoadedError")

  selectedStream = m.testVodStream
  m.videoTitle = selectedStream.title
  m.sdkTask.streamData = selectedStream

  m.sdkTask.video = m.video
  m.sdkTask.control = "RUN"
end function
Fichier sdk.xml
<interface>
  <field id="sdkLoaded" type="Boolean" />
  <field id="errors" type="stringarray" />
  <field id="urlData" type="assocarray" />
  <field id="adPlaying" type="Boolean" />
  <field id="video" type="Node" />
  <field id="streamData" type="assocarray" />
  <field id="streamManagerReady" type="Boolean" />
</interface>

sub runThread()
  if not m.top.sdkLoaded
    loadSdk()
  End If
  if not m.top.streamManagerReady
    loadStream()
  End If
End Sub

Sub loadStream()
  sdk = m.sdk
  sdk.initSdk()
  setupVideoPlayer()

  request = {}
  if m.top.streamData.type = "live"
    request = sdk.CreateLiveStreamRequest(m.top.streamData.assetKey, m.top.streamData.apiKey)
  else if m.top.streamData.type = "vod"
    request = sdk.CreateVodStreamRequest(m.top.streamData.contentSourceId, m.top.streamData.videoId, m.top.streamData.apiKey)
  else
    request = sdk.CreateStreamRequest()
  end if

  request.player = m.player
  request.adUiNode = m.top.video
  request.videoObject = 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

Ajouter des écouteurs d'événements et démarrer le flux

Après avoir demandé votre diffusion, il ne vous reste que quelques tâches à effectuer : ajouter des écouteurs d'événements pour suivre la progression des annonces, démarrer votre diffusion et transférer les messages Roku au SDK. Il est extrêmement important que vous transmettiez tous les messages au SDK afin de garantir la bonne lecture de l'annonce.

Fichierprincipal.xml
function loadImaSdk() as void
  m.sdkTask = createObject("roSGNode", "imasdk")
  m.sdkTask.observeField("sdkLoaded", "onSdkLoaded")
  m.sdkTask.observeField("errors", "onSdkLoadedError")

  selectedStream = m.testVodStream
  m.videoTitle = selectedStream.title
  m.sdkTask.streamData = selectedStream

  m.sdkTask.observeField("urlData", "urlLoadRequested")
  m.sdkTask.video = m.video
  m.sdkTask.control = "RUN"
end function

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

  playStream(data.manifest)
End Sub

Sub playStream(url as Object)
  vidContent = createObject("RoSGNode", "ContentNode")
  vidContent.url = url
  vidContent.title = m.videoTitle
  vidContent.streamformat = "hls"
  m.video.content = vidContent
  m.video.setFocus(true)
  m.video.visible = true
  m.video.control = "play"
  m.video.EnableCookies()
End Sub
Fichier sdk.xml
sub runThread()
  if not m.top.sdkLoaded
    loadSdk()
  End If
  if not m.top.streamManagerReady
    loadStream()
  End If
  If m.top.streamManagerReady
    runLoop()
  End If
End Sub

Sub runLoop()
  m.top.video.timedMetaDataSelectionKeys = ["*"]

  m.port = CreateObject("roMessagePort")

  ' Listen to all fields.

  ' IMPORTANT: Failure to listen to the position and timedmetadata fields
  ' could result in ad impressions not being reported.
  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
    If currentTime > 3 And not m.top.adPlaying
       m.top.video.enableTrickPlay = true
    End If
  end while
End Sub

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
  m.errorState = True
End Function