IMA SDK'ları, multimedya reklamlarını 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ıyla uygulamalar, reklam ve içerik videosu (VOD veya canlı içerik) için akış isteğinde bulunur. Daha sonra SDK, uygulamanızın içinde reklam ve içerik videosu arasında geçişi yönetmek zorunda kalmamanız için birleştirilmiş video akışı döndürür.
İlgilendiğiniz DAI çözümünü seçme
Tam hizmet DAI
Bu kılavuzda, IMA DAI SDK'sı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 izlemek istiyorsanız GitHub'dan temel örneği indirin.
IMA DAI'ya genel bakış
IMA DAI'yı uygulamak için bu kılavuzda gösterildiği gibi iki ana SDK bileşeni gerekir:
StreamRequest
: Akış isteğini tanımlayan bir nesne. Yayın istekleri, seç-izle video veya canlı yayınlar için olabilir. İstekler; Content ID, API anahtarı veya kimlik doğrulama jetonu ve diğer parametreleri belirtir.StreamManager
: Dinamik reklam ekleme akışlarını ve DAI arka ucuyla etkileşimleri işleyen bir nesne. Akış yöneticisi ayrıca izleme ping'lerini işler 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ı, anında bir içerik videosu oynatır. Geliştirme ortamınızın doğru şekilde ayarlandığından emin olmak için örnek oynatıcıyı Roku oynatıcınıza dağıtın.
Video oynatıcınızı IMA DAI akış oynatıcısına dönüştürme
Akış oynatıcı uygulamak için bu adımları izleyin.
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 ikisini de düzenlemeniz gerekir.
Roku Reklamcılık Çerçevesi'ni yükleme
IMA DAI SDK'sı, Roku Reklamcılık Çerçevesi'ne bağlıdır. Çerçeveyi yüklemek için manifest
ve Sdk.xml
bölümlerine aşağıdakileri ekleyin:
manifest
bs_libs_required=roku_ads_lib,googleima3
Sdk.xml
Library "Roku_Ads.brs"
Library "IMA3.brs"
IMA DAI SDK'sını yükleme
IMA Dinamik Reklam Ekleme akışınızı yüklemenin ilk adımı, IMA DAI SDK'sını yükleyip başlatmaktır. Aşağıda, IMA DAI SDK'sı komut dosyası yüklenir.
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 bu görevi MainScene.xml
uygulamasında başlatın ve içerik akışını yüklemek için yapılan çağrıyı 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, IMA akış oynatıcısı oluşturmak için mevcut roVideoScreen
öğenizi kullanmanız gerekir. Bu akış oynatıcı üç geri çağırma yöntemi uygular: loadUrl
, adBreakStarted
ve adBreakEnded
. Ayrıca, yayın yüklendiğinde "S bilgilerini" özelliğini devre dışı bırakın. Böylece, kullanıcıların reklam arası başlayan etkinlik tetiklenmeden önce videodan önce gösterilen reklamı reklam başladığı anda atlamasını önlersiniz.
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şturabilir ve yürütebilirsiniz.
Bu örnekte bir canlı yayın ve VOD akışına ilişkin veriler bulunmaktadır. Bu özellikte VOD yayın kullanılır ancak selectedStream
m.testVodStream
yerine m.testLiveStream
olacak şekilde canlı yayın özelliğini de kullanabilirsiniz.
AdUI'yi (ör. adChoices simgeleri) destekleyebilmek için isteğinizin bir parçası olarak içerik videonuzu içeren düğüme de referans vermeniz 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 yayını başlatma
Akışınızı isteğinde bulunduktan sonra yapmanız gereken tek işlem kaldı: reklam ilerleme durumunu izlemek için etkinlik işleyiciler 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 DAI SDK'sının oynatıcı nesnesine, videoyu kayan nokta saniye cinsinden programatik olarak belirtilen konuma yönlendiren bir seek
yöntemi eklemeniz gerekir.
Atlanabilir reklamları desteklemek için isteğinizde adUiNode
değerini 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