IMA SDK를 사용하면 멀티미디어 광고를 웹사이트와 앱에 쉽게 통합할 수 있습니다. IMA SDK는 모든 VAST 호환 광고 서버에서 광고를 요청하고 앱에서 광고 재생을 관리할 수 있습니다. IMA DAI SDK를 사용하면 앱에서 광고 및 콘텐츠 동영상(VOD 또는 라이브 콘텐츠)의 스트림을 요청합니다. 그러면 SDK가 결합된 동영상 스트림을 반환하므로 앱 내에서 광고와 콘텐츠 동영상 간의 전환을 관리할 필요가 없습니다.
관심 있는 DAI 솔루션 선택
전체 서비스 DAI
이 가이드에서는 IMA DAI SDK를 간단한 동영상 플레이어 앱에 통합하는 방법을 보여줍니다. 완료된 샘플 통합을 보거나 확인하려면 GitHub에서 기본 예를 다운로드하세요.
IMA DAI 개요
IMA DAI를 구현하려면 이 가이드에 설명된 대로 두 가지 주요 SDK 구성요소가 필요합니다.
StreamRequest
: 스트림 요청을 정의하는 객체입니다. 스트림 요청은 VOD 또는 라이브 스트림에 대한일 수 있습니다. 요청은 콘텐츠 ID는 물론 API 키나 인증 토큰과 기타 매개변수를 지정합니다.StreamManager
: 동적 광고 삽입 스트림 및 DAI 백엔드와의 상호작용을 처리하는 객체입니다. 또한 스트림 관리자는 핑 추적을 처리하고 스트림 및 광고 이벤트를 게시자에게 전달합니다.
기본 요건
- 호환성 페이지를 검토하여 원하는 사용 사례가 지원되는지 확인합니다.
- Roku 샘플 플레이어 코드 다운로드
- 샘플 플레이어 코드를 Roku 기기에 배포하여 개발 설정이 작동하는지 확인합니다.
동영상 재생
제공된 샘플 동영상 플레이어는 즉시 콘텐츠 동영상을 재생합니다. 샘플 플레이어를 Roku 플레이어에 배포하여 개발 환경이 제대로 설정되었는지 확인합니다.
동영상 플레이어를 IMA DAI 스트림 플레이어로 전환
스트림 플레이어를 구현하려면 다음 단계를 따르세요.
Sdk.xml 만들기
프로젝트에 MainScene.xml
과 함께 Sdk.xml
라는 새 파일을 추가하고 다음 상용구를 추가합니다.
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 스트림 플레이어를 만들어야 합니다. 이 스트림 플레이어는 loadUrl
, adBreakStarted
, adBreakEnded
라는 세 가지 콜백 메서드를 구현합니다. 또한 스트림이 로드될 때는 트릭 플레이를 사용 중지하세요. 이렇게 하면 프리롤이 시작되는 순간, 즉 광고 시점 시작 이벤트가 실행되기 전에 사용자가 프리롤을 건너뛸 수 없습니다.
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
로 변경하여 라이브 스트림을 대신 사용할 수 있습니다.
adChoices 아이콘과 같은 AdUI를 지원하려면 콘텐츠 동영상이 포함된 노드에 대한 참조도 요청의 일부로 전달해야 합니다.
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
이벤트 리스너 추가 및 스트림 시작
스트림을 요청한 후 광고 진행 상황을 추적할 이벤트 리스너를 추가하고, 스트림을 시작하고, 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