Les SDK IMA facilitent l'intégration d'annonces multimédias dans vos sites Web et applications. Les SDK IMA peuvent demander des annonces à partir de n'importe quel ad server compatible avec 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 des annonces et des contenus vidéo (VOD ou en direct). Le SDK renvoie ensuite un flux vidéo combiné pour vous éviter d'avoir à gérer le basculement entre l'annonce et la vidéo de contenu dans votre application.
Sélectionnez la solution d'insertion dynamique d'annonce qui vous intéresse
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 consulter 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
Comme le montre ce guide, l'implémentation de l'IMA DAI implique deux composants principaux du SDK:
StreamRequest
: objet qui définit une requête de flux. Les demandes de flux peuvent être pour des vidéos à la demande ou des diffusions 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 d'annonces dynamiques et les interactions avec le backend d'insertion dynamique d'annonce. Le gestionnaire de flux gère également les pings de suivi, et transfère les événements de flux et d'annonce à l'éditeur.
Conditions préalables
- Consultez notre page sur la compatibilité pour vous assurer que le cas d'utilisation prévu est pris en charge.
- Téléchargez l'exemple de code du 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
Le lecteur vidéo fourni à titre d'exemple permet de lire directement une vidéo de contenu. Déployez le lecteur d'exemple sur votre lecteur Roku pour vous assurer que votre environnement de développement est correctement configuré.
Transformez votre lecteur vidéo en lecteur de flux pour l'insertion dynamique d'annonces dynamiques
Pour implémenter un lecteur de flux, procédez comme suit :
Créer un fichier Sdk.xml
Ajoutez à votre projet un fichier nommé Sdk.xml
en plus 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 devez modifier ces deux fichiers tout au long de ce guide.
Charger le framework publicitaire 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 du chargement de votre flux d'insertion dynamique d'annonces IMA consiste à charger et à initialiser le SDK IMA DAI. La commande suivante permet de charger le script du SDK IMA DAI.
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 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 fonction Astuce
lorsque le flux est chargé. Cela empêche les utilisateurs d'ignorer une annonce vidéo pré-roll dès son lancement, avant le déclenchement de l'événement de début de 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 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 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 passant selectedStream
de m.testVodStream
à 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 contenu vidéo dans le cadre de votre demande.
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 le flux
Après avoir demandé votre diffusion, il ne vous reste plus que quelques actions à 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.
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'annonces. Celui-ci recherche automatiquement 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 l'élément 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