IMA SDK ช่วยให้การผสานรวมโฆษณามัลติมีเดียในเว็บไซต์และแอปของคุณทำได้โดยง่าย IMA SDK สามารถขอโฆษณาจากเซิร์ฟเวอร์โฆษณาที่ สอดคล้องกับ VAST และจัดการการเล่นโฆษณาในแอปของคุณได้ เมื่อใช้ IMA DAI SDK แอปจะส่งคำขอสตรีมสำหรับโฆษณาและวิดีโอของเนื้อหา ไม่ว่าจะเป็น VOD หรือเนื้อหาสด จากนั้น SDK จะส่งคืนสตรีมวิดีโอแบบรวมเพื่อที่คุณจะได้ไม่ต้องจัดการเปลี่ยนไปมาระหว่างโฆษณากับวิดีโอเนื้อหาภายในแอป
เลือกโซลูชัน DAI ที่คุณสนใจ
DAI บริการเต็มรูปแบบ
คู่มือนี้สาธิตวิธีผสานรวม IMA DAI SDK เข้ากับแอปโปรแกรมเล่นวิดีโอแบบง่าย หากคุณต้องการดูหรือทำตามไปพร้อมกับตัวอย่างการผสานรวมที่สมบูรณ์ ให้ดาวน์โหลดตัวอย่างพื้นฐานจาก GitHub
ภาพรวม IMA DAI
การติดตั้งใช้งาน IMA DAI เกี่ยวข้องกับองค์ประกอบหลักของ SDK 2 รายการต่อไปนี้ตามที่แสดงในคู่มือนี้
StreamRequest
: ออบเจ็กต์ที่กำหนดคำขอสตรีม คำขอสตรีมอาจเป็นวิดีโอออนดีมานด์หรือสตรีมแบบสดก็ได้ คำขอจะระบุ Content ID รวมถึงคีย์ API หรือโทเค็นการตรวจสอบสิทธิ์ และพารามิเตอร์อื่นๆStreamManager
: ออบเจ็กต์ที่จัดการสตรีมการแทรกโฆษณาแบบไดนามิกและการโต้ตอบกับแบ็กเอนด์ DAI นอกจากนี้ ตัวจัดการสตรีมยังจัดการคําสั่ง ping ของการติดตาม รวมถึงส่งต่อเหตุการณ์ของสตรีมและเหตุการณ์โฆษณาไปยังผู้เผยแพร่โฆษณาอีกด้วย
สิ่งที่ต้องดำเนินการก่อน
- อ่านหน้าความเข้ากันได้ของเราเพื่อตรวจสอบว่าระบบรองรับ Use Case ที่คุณต้องการ
- ดาวน์โหลดโค้ดโปรแกรมเล่นตัวอย่าง Roku ของเรา
- ทำให้โค้ดโปรแกรมเล่นตัวอย่างใช้งานได้กับอุปกรณ์ Roku เพื่อยืนยันว่าการตั้งค่าการพัฒนาทำงานอยู่
เล่นวิดีโอ
โปรแกรมเล่นวิดีโอตัวอย่างที่มีให้จะเล่นวิดีโอเนื้อหานอกกล่อง ทำให้โปรแกรมเล่นตัวอย่างใช้งานได้กับโปรแกรมเล่นของ Roku เพื่อให้แน่ใจว่าได้ตั้งค่าสภาพแวดล้อมในการพัฒนาซอฟต์แวร์อย่างถูกต้องแล้ว
เปลี่ยนโปรแกรมเล่นวิดีโอเป็นโปรแกรมเล่นสตรีม IMA DAI
ทำตามขั้นตอนต่อไปนี้เพื่อใช้งานโปรแกรมเล่นสตรีม
สร้าง Sdk.xml
เพิ่มไฟล์ใหม่ลงในโปรเจ็กต์พร้อมกับ MainScene.xml
ที่มีชื่อว่า Sdk.xml
และเพิ่ม Boilerplate ต่อไปนี้
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>
คุณต้องแก้ไขทั้งสองไฟล์นี้ตลอดทั้งคู่มือนี้
โหลดเฟรมเวิร์กโฆษณาของ Roku
IMA DAI SDK ขึ้นอยู่กับเฟรมเวิร์กโฆษณาของ Roku หากต้องการโหลดเฟรมเวิร์ก ให้เพิ่มค่าต่อไปนี้ลงใน manifest
และ Sdk.xml
ประจักษ์
bs_libs_required=roku_ads_lib,googleima3
Sdk.xml
Library "Roku_Ads.brs"
Library "IMA3.brs"
โหลด IMA DAI SDK
ขั้นตอนแรกในการโหลดสตรีมการแทรกโฆษณาแบบไดนามิก IMA คือการโหลดและเปิดใช้งาน IMA DAI SDK รายการต่อไปนี้จะโหลดสคริปต์ IMA DAI SDK
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
ตอนนี้ให้เริ่มงานนี้ใน MainScene.xml
และนำการโทรออกเพื่อโหลดสตรีมเนื้อหา
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
ขั้นตอนต่อไป คุณต้องใช้ roVideoScreen
ที่มีอยู่เพื่อสร้างโปรแกรมเล่นสตรีม IMA สตรีมเพลเยอร์นี้มีเมธอด Callback 3 วิธี ได้แก่ loadUrl
, adBreakStarted
และ adBreakEnded
นอกจากนี้ ให้ปิดใช้งาน Trick Play
เมื่อโหลดสตรีมแล้ว วิธีนี้ช่วยป้องกันไม่ให้ผู้ใช้ข้ามโฆษณาตอนต้นทันทีที่เริ่มเล่น ก่อนที่เหตุการณ์ที่เริ่มต้นช่วงพักโฆษณาจะเริ่มทำงาน
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
สร้างและดำเนินการกับคำขอสตรีม
เมื่อมีโปรแกรมเล่นสตรีมแล้ว คุณจะสร้างและดำเนินการกับคำขอสตรีมได้
ตัวอย่างนี้มีข้อมูลสำหรับสตรีมแบบสดและสตรีม VOD ซึ่งใช้สตรีม VOD แต่คุณใช้การถ่ายทอดสดแทนได้โดยเปลี่ยน selectedStream
จาก m.testVodStream
เป็น m.testLiveStream
เพื่อให้รองรับ AdUI อย่างเช่นไอคอน adChoices ได้ คุณต้องส่งผ่านการอ้างอิงไปยังโหนดที่มีวิดีโอคอนเทนต์ซึ่งเป็นส่วนหนึ่งของคำขอด้วย
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
เพิ่ม Listener เหตุการณ์และเริ่มสตรีม
หลังจากขอสตรีมแล้ว ก็เหลือเพียงไม่กี่อย่างที่ต้องทำ ได้แก่ เพิ่มตัวฟังเหตุการณ์เพื่อติดตามความคืบหน้าของโฆษณา เริ่มสตรีม และส่งต่อข้อความ Roku ไปยัง 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
เพิ่มการรองรับโฆษณาที่ข้ามได้ (ไม่บังคับ)
หากต้องการรองรับโฆษณาแบบข้ามได้ คุณต้องเพิ่มเมธอด seek
ลงในออบเจ็กต์โปรแกรมเล่นของ IMA DAI SDK ที่ค้นหาวิดีโอไปยังตำแหน่งที่ระบุโดยใช้โปรแกรมในหน่วยวินาทีที่ลอยอยู่
คุณต้องตรวจสอบว่าได้ตั้งค่า adUiNode
ในคำขอแล้วจึงจะรองรับโฆษณาแบบข้ามได้
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