IMA SDK を使用すると、マルチメディア広告をウェブサイトやアプリに簡単に統合できます。IMA SDK は、 VAST 準拠のあらゆる広告サーバーから広告をリクエストし、アプリでの広告再生を管理できます。IMA DAI SDK を使用すると、アプリは広告とコンテンツ動画（VOD またはライブ コンテンツ）のストリーム リクエストを行います。SDK は結合された動画ストリームを返すため、アプリ内で広告とコンテンツの動画を切り替える処理を管理する必要はありません。
関心のある DAI ソリューションを選択する
フルサービス DAI
このガイドでは、IMA DAI SDK をシンプルな動画プレーヤー アプリに統合する方法について説明します。完成したサンプル統合を確認または実行する場合は、GitHub から基本サンプルをダウンロードしてください。
IMA DAI の概要
このガイドで説明するように、IMA DAI の実装には 2 つの主要な SDK コンポーネントが含まれます。
StreamRequest: ストリーム リクエストを定義するオブジェクト。ストリーム リクエストは、ビデオ オンデマンドまたはライブ ストリームのいずれかになります。ライブ ストリームのリクエストではアセットキーが指定され、VOD のリクエストでは CMS ID と動画 ID が指定されます。どちらのリクエスト タイプにも、指定されたストリームへのアクセスに必要な API キーと、Google Ad Manager の設定で指定された広告 ID を IMA SDK が処理するための Google Ad Manager ネットワーク コードを任意で含めることができます。StreamManager: ダイナミック広告挿入ストリームと DAI バックエンドとのやり取りを処理するオブジェクト。ストリーム マネージャーは、トラッキング ping を処理し、ストリーム イベントと広告イベントをパブリッシャーに転送します。
前提条件
- 互換性に関するページをよくお読みになり、ご希望のユースケースがサポートされていることをご確認ください。
- 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 Advertising Framework を読み込む
IMA DAI SDK は Roku Advertising Framework に依存しています。フレームワークを読み込むには、次のコードを manifest と Sdk.xml に追加します。
bs_libs_required=roku_ads_lib,googleima3
Library "Roku_Ads.brs"
Library "IMA3.brs"
IMA DAI SDK を読み込む
IMA DAI SDK を読み込むには、次の操作を行います。
New_IMASDK()呼び出しで IMA SDK を初期化します。sub loadSdk() If m.sdk = invalid m.sdk = New_IMASDK() End If m.top.sdkLoaded = true End SubsdkLoadedブール値フィールドを作成して、IMA が読み込まれたかどうかをトラッキングします。<field id="sdkLoaded" type="Boolean" />メインの
runThread()サブルーチンからloadSdk()サブルーチンを呼び出します。if not m.top.sdkLoaded loadSdk() End IfMainScene.xmlにloadImaSdk()関数を作成して、sdkTaskオブジェクトを作成して実行します。function loadImaSdk() as void m.sdkTask = createObject("roSGNode", "imasdk") m.sdkTask.observeField("sdkLoaded", "onSdkLoaded") m.sdkTask.observeField("errors", "onSdkLoadedError") ' Change to m.testLiveStream to demo live instead of VOD. selectedStream = m.testVodStream m.videoTitle = selectedStream.title m.sdkTask.streamData = selectedStream m.sdkTask.observeField("urlData", "urlLoadRequested") m.sdkTask.video = m.video ' Setting control to run starts the task thread. m.sdkTask.control = "RUN" end functioninit()関数からloadImaSdk()関数を呼び出します。SDK の読み込みイベントに応答する
onSdkLoaded()リスナー サブルーチンとonSdkLoadedError()リスナー サブルーチンを作成します。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 ストリーム プレーヤーを作成する
IMA ストリーム プレーヤーを作成する手順は次のとおりです。
次の処理を行う
setupVideoPlayer()サブルーチンを作成します。createPlayer()メソッドを使用してストリーム プレーヤーを作成します。ストリーム プレーヤーに 3 つのコールバック メソッド（
loadUrl、adBreakStarted、adBreakEnded）を実装します。ストリームが読み込まれたときにトリックプレイを無効にして、広告ブレーク開始イベントがトリガーされる前に、ストリームが開始された瞬間にユーザーがプレロールをスキップできないようにします。
sub setupVideoPlayer() sdk = m.sdk m.player = sdk.createPlayer() m.player.top = m.top m.player.loadUrl = Function(urlData) ' This line prevents users from scanning during buffering ' or during the first second of the ad before we have a callback from roku. ' If there are no prerolls disabling trickplay isn't needed. 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 m.player.seek = Function(timeSeconds as Double) print "---- SDK requested seek to ----" ; timeSeconds m.top.video.seekMode = "accurate" m.top.video.seek = timeSeconds End Function End Subスキップ可能な広告をサポートするために、
seekコールバック メソッドを追加します。詳しくは、スキップ可能な広告のサポートを追加するをご覧ください。setupVideoPlayer()サブルーチンで使用されるurlData、adPlaying、videoフィールドを追加します。<field id="urlData" type="assocarray" /> <field id="adPlaying" type="Boolean" /> <field id="video" type="Node" />
ストリーム リクエストを作成して実行する
DAI ストリームをリクエストする手順は次のとおりです。
ストリームを作成してリクエストする
loadStream()サブルーチンを作成します。AdChoices アイコンなどの広告 UI をサポートするには、リクエストの一部として、コンテンツ動画を含むノードへの参照も渡す必要があります。Sub loadStream() sdk = m.sdk sdk.initSdk() setupVideoPlayer() request = {} streamData = m.top.streamData if streamData.type = "live" request = sdk.CreateLiveStreamRequest(streamData.assetKey, streamData.apiKey, streamData.networkCode) else if streamData.type = "vod" request = sdk.CreateVodStreamRequest(streamData.contentSourceId, streamData.videoId, streamData.apiKey, streamData.networkCode) else request = sdk.CreateStreamRequest() end if request.player = m.player 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 SubloadStream()サブルーチンで使用されるstreamDataフィールドとstreamManagerReadyフィールドを追加します。<field id="streamManagerReady" type="Boolean" /> <field id="streamData" type="assocarray" />ストリーム マネージャーが利用できない場合は、
runThread()サブルーチンからloadStream()サブルーチンを呼び出します。if not m.top.streamManagerReady loadStream() End IfVOD またはライブ配信を選択します。次の例には、ライブ配信と VOD ストリームのストリーム パラメータがあります。
m.testLiveStream = { title: "Live Stream", assetKey: "c-rArva4ShKVIAkNfy6HUQ", networkCode: "21775744923", apiKey: "", type: "live" } m.testVodStream = { title: "VOD stream" contentSourceId: "2548831", videoId: "tears-of-steel", networkCode: "21775744923", apiKey: "", type: "vod" }デフォルトでは、このガイドは VOD ストリームを使用します。代わりに、
m.testVodStreamオブジェクトのselectedStream変数をm.testLiveStreamオブジェクトに変更することで、ライブ配信を使用できます。
ストリームの開始
ストリームデータをリッスンして playStream() サブルーチンを呼び出す urlLoadRequested() サブルーチンを作成します。
Sub urlLoadRequested(message as Object)
print "Url Load Requested ";message
data = message.getData()
playStream(data.manifest, data.format)
End Sub
ストリームの再生を開始する playStream() を作成します。
Sub playStream(url as String, format as String)
vidContent = createObject("RoSGNode", "ContentNode")
vidContent.url = url
vidContent.title = m.videoTitle
vidContent.streamformat = format
m.video.content = vidContent
m.video.setFocus(true)
m.video.visible = true
m.video.control = "play"
m.video.EnableCookies()
End Sub
ストリーム メタデータをリッスンする
ストリーム再生中に実行され、StreamManager.onMessage() を使用してストリーム メタデータを IMA に送信する while ループを含む runLoop() サブルーチンを作成します。
Sub runLoop()
' Forward all timed metadata events.
m.top.video.timedMetaDataSelectionKeys = ["*"]
' Cycle through all the fields and just listen to them all.
m.port = CreateObject("roMessagePort")
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
' Only enable trickplay after a few seconds, in case we start with an ad,
' to prevent users from skipping through that ad.
If currentTime > 3 And not m.top.adPlaying
m.top.video.enableTrickPlay = true
End If
end while
End Sub
広告イベントをリッスンする
ストリーム メタデータを IMA に渡すようになったため、IMA は広告ブレーク中に広告イベントを発行できます。必要に応じて広告イベント リスナーを作成し、広告イベントに応答します。
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
' errors are critical and should terminate the stream.
m.errorState = True
End Function
スキップ可能な広告のサポートを追加する（省略可）
スキップ可能な広告をサポートするには、IMA DAI SDK の player オブジェクトに seek メソッドを追加する必要があります。このメソッドは、動画を指定された位置（浮動小数点秒単位）までプログラムでシークします。
スキップ可能な広告をサポートするには、リクエストで adUiNode も設定する必要があります。
m.player.seek = Function(timeSeconds as Double)
print "---- SDK requested seek to ----" ; timeSeconds
m.top.video.seekMode = "accurate"
m.top.video.seek = timeSeconds
End Function