Les SDK IMA facilitent l'intégration d'annonces multimédias dans vos sites Web et applications. Les SDK IMA peuvent demander des annonces à n'importe quel ad server compatible avec VAST et gérer la lecture des annonces dans vos applications. Avec les SDK IMA pour l'insertion dynamique d'annonce, les applications envoient une demande de flux pour l'annonce 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 annonces et les vidéos de contenu dans votre application.
Sélectionnez la solution d'insertion dynamique d'annonce qui vous intéresse.
Insertion dynamique d'annonces avec service complet
Ce guide explique comment intégrer le SDK IMA pour l'insertion dynamique d'annonce dans 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 sur GitHub.
Présentation de l'insertion dynamique d'annonces IMA
L'implémentation d'IMA DAI implique deux composants SDK principaux, comme expliqué dans ce guide:
StreamRequest
: objet qui définit une requête de flux. Les requêtes de flux peuvent concerner les vidéos à la demande ou les 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. Il 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 le cas d'utilisation prévu est accepté.
- 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 la configuration de votre 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 pour l'insertion dynamique d'annonces
Suivez ces étapes pour implémenter un lecteur de flux.
Créer le fichier Sdk.xml
Ajoutez à votre projet un fichier nommé Sdk.xml
à côté de MainScene.xml
, puis 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 l'environnement publicitaire de Roku
Le SDK IMA DAI dépend du framework publicitaire Roku. Pour charger le framework, ajoutez les éléments suivants à manifest
et Sdk.xml
:
fichier manifeste
bs_libs_required=roku_ads_lib,googleima3
Sdk.xml
Library "Roku_Ads.brs"
Library "IMA3.brs"
Charger le SDK IMA DAI
La première étape pour charger votre flux d'insertion dynamique d'annonce IMA consiste à charger et initialiser le SDK IMA DAI. La commande suivante permet de charger le script du SDK IMA pour l'insertion dynamique d'annonce.
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
Lancez 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 fonctionnalité de lecture piège lorsque le flux est chargé. Cela empêche les utilisateurs d'ignorer une annonce vidéo pré-roll dès qu'elle commence, avant le déclenchement de l'événement de démarrage de la coupure publicitaire.
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 demande 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 une diffusion en direct et un flux de vidéo à la demande. Elle utilise le flux de VOD, mais vous pouvez utiliser le direct à la place en remplaçant selectedStream
de m.testVodStream
par m.testLiveStream
.
Pour prendre en charge l'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: "Livestream",
assetKey: "sN_IYUG8STe1ZzhIIE_ksA",
apiKey: "",
type: "live"
}
m.testVodStream = {
title: "VOD stream"
contentSourceId: "2548831",
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
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 la diffusion
Une fois que vous avez demandé votre diffusion, il ne vous reste plus qu'à ajouter des écouteurs d'événements pour suivre la progression de votre annonce, démarrer votre diffusion et transférer les messages Roku au SDK.
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
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)
Pour accepter les annonces désactivables, vous devez ajouter une méthode seek
à l'objet player du SDK IMA pour l'insertion dynamique d'annonce, qui recherche par programmation la vidéo à l'emplacement spécifié, en secondes à virgule flottante.
Pour accepter les annonces désactivables, vous devez également vous assurer de définir le adUiNode
dans votre demande.
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