IMA SDK'ları, multimedya reklamları web sitelerinize ve uygulamalarınıza entegre etmenizi kolaylaştırır. IMA SDK'ları, VAST uyumlu herhangi bir reklam sunucusundan reklam isteyebilir ve uygulamalarınızda reklam oynatmayı yönetebilir. IMA DAI SDK'ları sayesinde uygulamalar, reklam ve içerik videosu (VOD veya canlı içerik) için akış isteğinde bulunur. SDK, daha sonra birleştirilmiş bir video akışı döndürür. Böylece, uygulamanız içinde reklam ve içerik videosu arasında geçişi yönetmeniz gerekmez.
İlgilendiğiniz DAI çözümünü seçme
Tam hizmet DAI
Bu kılavuzda, IMA SDK'nın basit bir video oynatıcı uygulamasına nasıl entegre edileceği gösterilmektedir. Tamamlanmış bir örnek entegrasyonu görüntülemek veya takip etmek isterseniz GitHub'dan temel örneği indirin.
IMA DAI'ya genel bakış
IMA DAI'yı uygulamak, bu kılavuzda gösterildiği gibi iki ana SDK bileşeni içerir:
StreamRequest
: Akış isteğini tanımlayan bir nesne. Akış istekleri seç-izle video veya canlı yayınlar için olabilir. İstekler bir içerik kimliğinin yanı sıra API anahtarı veya kimlik doğrulama jetonu ve diğer parametreleri belirtir.StreamManager
: Dinamik reklam ekleme akışlarını ve DAI arka ucuyla etkileşimlerini işleyen bir nesne. Akış yöneticisi ayrıca izleme ping'lerini yönetir ve akış ile reklam etkinliklerini yayıncıya yönlendirir.
Ön koşullar
- Amaçladığınız kullanım alanının desteklendiğinden emin olmak için uyumluluk sayfamızı okuyun.
- Roku örnek oynatıcı kodumuzu indirin
- Geliştirme kurulumunuzun çalıştığını doğrulamak için örnek oynatıcı kodunu bir Roku cihaza dağıtın.
Videonuzu oynatma
Sağlanan örnek video oynatıcı, kullanıma hazır bir içerik videosu oynatır. Geliştirme ortamınızın düzgün şekilde ayarlanması için örnek oynatıcıyı Roku oynatıcınıza dağıtın.
Video oynatıcınızı bir IMA DAI akış oynatıcısına dönüştürme
Akış oynatıcısı uygulamak için aşağıdaki adımları uygulayın.
Sdk.xml oluştur
Projenize MainScene.xml
ile birlikte Sdk.xml
adlı yeni bir dosya ekleyin ve aşağıdaki ortak metni ekleyin:
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>
Bu kılavuz boyunca bu dosyaların her ikisini de düzenlemeniz gerekir.
Roku Reklamcılık Çerçevesini yükleme
IMA SDK, Roku Reklamcılık Çerçevesi'ne bağlıdır. Çerçeveyi yüklemek için manifest
ve Sdk.xml
öğelerine aşağıdaki kodu ekleyin:
manifest
bs_libs_required=roku_ads_lib,googleima3
Sdk.xml
Library "Roku_Ads.brs"
Library "IMA3.brs"
IMA SDK'yı yükleme
IMA Dinamik Reklam Ekleme akışınızı yüklemenin ilk adımı, IMA SDK'yı yüklemek ve başlatmaktır. Aşağıdaki komut, IMA SDK komut dosyasını yükler.
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
Şimdi MainScene.xml
ürününde bu görevi başlatın ve içerik akışını yükleme çağrısını kaldırın.
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
IMA akış oynatıcısı oluşturma
Ardından, bir IMA akış oynatıcısı oluşturmak için mevcut roVideoScreen
öğenizi kullanmanız gerekir. Bu akış oynatıcısı üç geri çağırma yöntemi uygular: loadUrl
, adBreakStarted
ve adBreakEnded
. Ayrıca, yayın yüklenirken hileli oyna özelliğini devre dışı bırakın. Bu, kullanıcıların videodan önce gösterilen reklamı reklam başladığı anda, reklam arası başlama etkinliği tetiklenmeden önce atlamasını önler.
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
Akış isteği oluşturma ve yürütme
Artık bir akış oynatıcınız olduğuna göre akış isteği oluşturup yürütebilirsiniz.
Bu örnekte bir canlı yayın ve VOD akışı için veriler bulunmaktadır. Seç-izle yayını kullanır ancak selectedStream
yerine m.testVodStream
olan ayarı m.testLiveStream
olarak değiştirerek canlı yayını kullanabilirsiniz.
Reklam Seçenekleri simgeleri gibi AdUI'yi destekleyebilmek için isteğinizin bir parçası olarak içerik videonuzu içeren düğüme de bir referans iletmeniz gerekir.
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
Etkinlik işleyicileri ekleme ve akışı başlatma
Akışınızı istedikten sonra yapılacak birkaç şey kaldı: Reklam ilerlemesini izlemek için etkinlik dinleyicileri eklemek, akışınızı başlatmak ve Roku mesajlarını SDK'ya yönlendirmek.
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
Atlanabilir reklamlar için destek ekleyin (isteğe bağlı)
Atlanabilir reklamları desteklemek için IMA SDK'nın oynatıcı nesnesine, videoyu belirtilen konuma (kayan nokta saniyeler) programatik olarak arayan bir seek
yöntemi eklemeniz gerekir.
Atlanabilir reklamları desteklemek için isteğinizde adUiNode
özelliğini ayarladığınızdan da emin olmanız gerekir.
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