Premiers pas

Les SDK IMA permettent d'intégrer facilement des annonces multimédias à vos sites Web et applications. Les SDK IMA peuvent demander des annonces à 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 effectuent une demande de diffusion d'annonce et de contenu vidéo en VOD ou en direct. Le SDK renvoie ensuite un flux vidéo combiné, ce qui vous évite d'avoir à basculer entre l'annonce et la 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.

Remarque:Le SDK IMA pour l'insertion dynamique d'annonce pour Roku est compatible avec les flux HLS et DASH, sans aucune différence au niveau de l'implémentation.

Pour utiliser l'insertion dynamique d'annonce IMA, vous devez disposer d'un compte Ad Manager 360 Advanced. Si vous possédez un compte Ad Manager, contactez-le pour en savoir plus. Pour en savoir plus sur l'inscription à Ad Manager, consultez le Centre d'aide Ad Manager.

Remarque:Pour plus d'informations sur l'intégration avec d'autres plates-formes ou sur l'utilisation des SDK IMA côté client, consultez la page SDK Interactive Media Ads.

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

L'implémentation 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. Les demandes de flux peuvent porter sur des diffusions à la demande ou en direct. Les requêtes spécifient un ID de contenu, 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'annonces et les interactions avec le backend d'insertion dynamique d'annonce. Le gestionnaire de flux gère également le suivi des pings, et transfère les événements de flux et d'annonce à l'éditeur.

Prérequis

Avant de commencer, vous devez:

• Consultez notre page de compatibilité pour vous assurer que votre cas d'utilisation 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 le bon fonctionnement de la configuration de développement.

Lire la vidéo

L'exemple de lecteur vidéo fourni contient une vidéo prête à l'emploi. Déployez l'exemple de lecteur sur le lecteur Roku pour vous assurer que votre environnement de développement est correctement configuré.

Transformez votre lecteur vidéo en lecteur d'insertion dynamique d'annonce IMA.

Créer un fichier Sdk.xml

Ajoutez à votre projet un fichier nommé Sdk.xml appelé MainScene.xml et 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 en-tête au-dessus de chaque extrait de code indique dans quel fichier vous devez ajouter cet extrait.

Charger le Framework de publicité Roku

Le SDK IMA dépend du framework publicitaire de Roku. Pour charger le framework, ajoutez le code suivant à 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

Commencez maintenant cette tâche dans MainScene.xml et supprimez l'appel pour charger le flux de contenu.

MainScene.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 la lecture du contenu pendant le chargement du flux. Cela permet d'éviter que les utilisateurs ignorent une annonce pré-roll au moment où elle commence, avant le déclenchement de l'événement de début de 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
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 demande 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 en cours d'utilisation. Pour utiliser "En direct" au lieu de "VOD", remplacez selectedStream par m.testVodStream par m.testLiveStream.

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

MainScene.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 = {}
  streamData = m.top.streamData
  if streamData.type = "live"
    request = sdk.CreateLiveStreamRequest(streamData.assetKey, streamData.apiKey)
  else if streamData.type = "vod"
    request = sdk.CreateVodStreamRequest(streamData.contentSourceId, streamData.videoId, streamData.apiKey)
  else
    request = sdk.CreateStreamRequest()
  end if

  request.player = m.player
  request.videoObject = m.top.video
  ' Required to support UI elements for 'Why This Ad?' and skippability
  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

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

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

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

Ajouter la compatibilité avec les annonces désactivables (facultatif)

Afin de pouvoir diffuser des annonces désactivables, vous devez ajouter une méthode seek à l'objet player du SDK IMA, qui recherche la vidéo à l'emplacement spécifié en secondes à virgule flottante.

Remarque:Pour accepter les annonces désactivables, vous devez aussi définir le paramètre adUiNode dans votre demande.

Fichier SDK.xml

  ...

  m.player.loadUrl = Function(urlData)
    m.top.video.enableTrickPlay = false
    m.top.urlData = urlData
  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

  m.player.adBreakStarted = Function(adBreakInfo as Object)
    print "---- Ad Break Started ---- "
    m.top.adPlaying = True
    m.top.video.enableTrickPlay = false
  End Function

  ...