Configurer le SDK IMA pour l'insertion dynamique d'annonces

Sélectionnez une plate-forme : HTML5 Android iOS tvOS Cast Roku

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 conforme à la norme VAST et gérer la lecture des annonces dans vos applications. Avec les SDK IMA DAI, les applications envoient une demande de flux pour les annonces et le contenu vidéo (VOD ou contenu en direct). Le SDK renvoie ensuite un flux vidéo combiné, ce qui vous évite d'avoir à gérer le basculement entre les vidéos d'annonces et de contenu dans votre application.

Sélectionnez la solution DAI qui vous intéresse.

Service complet Diffusion de pods

Insertion dynamique d'annonces (service complet)

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

Remarque : Le SDK IMA DAI pour Roku est compatible avec les flux HLS et DASH, sans différence d'implémentation.

Pour utiliser IMA DAI, vous devez disposer d'un compte Ad Manager 360 Advanced. Si vous possédez un compte Ad Manager, contactez votre responsable de compte pour en savoir plus. Pour savoir comment vous inscrire à Ad Manager, consultez le Centre d'aide Ad Manager.

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

Présentation d'IMA DAI

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

• StreamRequest : objet qui définit une requête de flux. Les demandes de flux peuvent concerner des vidéos à la demande ou des diffusions en direct. Les demandes de flux 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 demandes 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 publicitaires 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 DAI. Le gestionnaire de flux gère également les pings de suivi et transmet les événements de flux et d'annonces à 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 le lecteur exemple 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 Sdk.xml à votre projet, à côté de MainScene.xml, et ajoutez le code passe-partout 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 pour l'insertion dynamique d'annonces dépend du framework publicitaire Roku. 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. Créez un champ booléen sdkLoaded pour savoir si IMA a été chargé :

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

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. Demandez à ce lecteur de flux d'implémenter trois méthodes de rappel : loadUrl, adBreakStarted et adBreakEnded.

   3. Désactivez la lecture astucieuse lorsque le flux est chargé pour empêcher les utilisateurs de passer une annonce vidéo pré-roll au moment où le flux démarre, avant le déclenchement de l'événement de début de l'insertion publicitaire.

   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 demande de flux

Pour demander votre flux DAI :

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 AdChoices, vous devez également transmettre une référence au nœud contenant votre contenu vidéo dans votre demande :

   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 VOD ou un flux en direct. L'exemple suivant comporte des paramètres de flux pour un flux en direct et un flux 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 le flux 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 pour qu'elle s'exécute pendant la lecture du flux et envoyez les métadonnées du flux à IMA à l'aide de StreamManager.onMessage() :

Important : Vous devez transférer tous les messages au SDK pour assurer la lecture correcte des annonces.

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 publicitaires

Maintenant que vous transmettez les métadonnées du flux à IMA, IMA peut émettre des événements publicitaires pendant les pauses publicitaires. Créez des écouteurs d'événements d'annonces selon vos besoins pour répondre aux événements d'annonces :

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 prendre en charge les annonces désactivables, 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 décimales.

Pour prendre en charge les annonces désactivables, vous devez également vous assurer de définir adUiNode dans votre demande.

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