Configurer avec l'insertion dynamique d'annonces à service complet

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

Présentation de l'IMA DAI

L'implémentation d'IMA DAI implique deux composants principaux du SDK, comme indiqué dans ce guide :

• StreamRequest : objet qui définit une requête de flux. Les requêtes de flux peuvent concerner des flux de vidéo à la demande ou des flux en direct. Les demandes de diffusion en direct spécifient une clé d'élément, tandis que les demandes de VOD spécifient un ID CMS et un ID vidéo. Les deux types de requêtes peuvent éventuellement inclure une clé API nécessaire pour accéder aux flux spécifiés, ainsi qu'un code de réseau Google Ad Manager permettant au SDK IMA de gérer les identifiants d'annonces comme spécifié dans les paramètres Google Ad Manager.
• StreamManager : objet qui gère les flux d'insertion dynamique d'annonces et les interactions avec le backend d'insertion dynamique d'annonces. Le gestionnaire de flux gère également les pings de suivi et transmet les événements de flux et d'annonce à l'éditeur.

Prérequis

• Consultez notre page sur la compatibilité pour vous assurer que votre cas d'utilisation est pris en charge.
• Téléchargez notre exemple de code de lecteur Roku.
• Déployez l'exemple de code du lecteur 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 une vidéo de contenu prête à 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 IMA DAI

Suivez ces étapes pour implémenter un lecteur de flux.

Créer Sdk.xml

Ajoutez un fichier nommé Sdk.xml à votre projet, à côté de MainScene.xml, et ajoutez le code récurrent suivant :

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 devrez modifier ces deux fichiers tout au long de ce guide.

Charger le framework publicitaire Roku

Le SDK IMA DAI dépend du Roku Advertising Framework. Pour charger le framework, ajoutez le code suivant à manifest et Sdk.xml :

bs_libs_required=roku_ads_lib,googleima3
manifest

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

Charger le SDK IMA DAI

Pour charger le SDK IMA DAI, procédez comme suit :

1. Initialisez le SDK IMA avec l'appel New_IMASDK() :

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

2. Vérifiez si IMA a été chargé en créant un champ booléen sdkLoaded :

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

3. Appelez la sous-routine loadSdk() à partir de la sous-routine principale runThread() :

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

4. Créez la fonction loadImaSdk() dans MainScene.xml pour créer et exécuter l'objet 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. Appelez la fonction loadImaSdk() à partir de la fonction init().

6. Créez les sous-routines d'écouteur onSdkLoaded() et onSdkLoadedError() pour répondre aux événements de chargement du 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
   

Créer un lecteur de flux IMA

Pour créer un lecteur de flux IMA, procédez comme suit :

1. Créez une sous-routine setupVideoPlayer() qui effectue les opérations suivantes :

   1. Utilisez la méthode createPlayer() pour créer le lecteur de flux.

   2. Faites en sorte que ce lecteur de flux implémente trois méthodes de rappel : loadUrl, adBreakStarted et adBreakEnded.

   3. Désactivez la lecture rapide lorsque le flux est chargé pour empêcher les utilisateurs d'ignorer une annonce pré-roll au moment où le flux démarre, avant que l'événement de début de coupure publicitaire ne soit déclenché.

   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
   

   Ajoutez une méthode de rappel seek pour prendre en charge les annonces désactivables. Pour en savoir plus, consultez Ajouter la prise en charge des annonces désactivables.

2. Ajoutez les champs urlData, adPlaying et video utilisés dans la sous-routine setupVideoPlayer() :

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

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

Pour demander votre flux d'insertion dynamique d'annonce, procédez comme suit :

1. Créez une sous-routine loadStream() pour créer et demander un flux. Pour prendre en charge l'UI des annonces, comme les icônes Choisir sa pub, vous devez également transmettre une référence au nœud contenant votre vidéo de contenu dans votre requête :

   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. Ajoutez les champs streamData et streamManagerReady utilisés dans la sous-routine loadStream() :

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

3. Si le gestionnaire de flux n'est pas disponible, appelez la sous-routine loadStream() à partir de la sous-routine runThread() :

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

4. Sélectionnez une vidéo à la demande ou une diffusion en direct. L'exemple suivant comporte des paramètres de flux pour une diffusion en direct et un flux de 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
   

   Par défaut, ce guide utilise le flux VOD. Vous pouvez utiliser la diffusion en direct à la place en remplaçant la variable selectedStream de l'objet m.testVodStream par l'objet m.testLiveStream.

Démarrer le flux

Créez la sous-routine urlLoadRequested() pour écouter les données du flux et appeler la sous-routine playStream() :

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

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

Créez le playStream() pour démarrer la lecture du flux :

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

Écouter les métadonnées du flux

Créez la sous-routine runLoop() avec une boucle "while" à exécuter pendant la lecture du flux et envoyez les métadonnées du flux à IMA à l'aide de StreamManager.onMessage() :

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

Écouter les événements d'annonce

Maintenant que vous transmettez les métadonnées du flux à IMA, IMA peut émettre des événements d'annonce pendant les coupures publicitaires. Créez des écouteurs d'événements d'annonce si nécessaire pour répondre aux événements d'annonce :

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

Ajouter la prise en charge des annonces désactivables (facultatif)

Pour que les annonces désactivables soient acceptées, vous devez ajouter une méthode seek à l'objet player du SDK IMA DAI, qui recherche de manière programmatique la vidéo à l'emplacement spécifié, en secondes à virgule flottante.

Pour diffuser des annonces désactivables, vous devez également vous assurer de définir adUiNode dans votre requête.

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