DAI 用 IMA SDK を設定する

プラットフォームを選択: HTML5 Android iOS tvOS Cast Roku

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 アド マネージャーの設定で指定された広告識別子を IMA SDK が処理するための Google アド マネージャー ネットワーク コードを任意で含めることができます。
  • 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
manifest


Library "Roku_Ads.brs"
Library "IMA3.brs"
Sdk.xml

IMA DAI SDK を読み込む

IMA DAI SDK を読み込むには、次の操作を行います。

  1. New_IMASDK() 呼び出しで IMA SDK を初期化します。

    sub loadSdk()
  If m.sdk = invalid
    m.sdk = New_IMASDK()
  End If
  m.top.sdkLoaded = true
End Sub
    Sdk.xml

  2. sdkLoaded ブール値フィールドを作成して、IMA が読み込まれたかどうかをトラッキングします。

    <field id="sdkLoaded" type="Boolean" />
    Sdk.xml

  3. メインの runThread() サブルーチンから loadSdk() サブルーチンを呼び出します。

    if not m.top.sdkLoaded
  loadSdk()
End If
    Sdk.xml

  4. MainScene.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 function
    MainScene.xml

  5. init() 関数から loadImaSdk() 関数を呼び出します。

  6. 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
    MainScene.xml

IMA ストリーム プレーヤーを作成する

IMA ストリーム プレーヤーを作成する手順は次のとおりです。

  1. 次の処理を行う setupVideoPlayer() サブルーチンを作成します。

    1. createPlayer() メソッドを使用してストリーム プレーヤーを作成します。

    2. ストリーム プレーヤーに loadUrl、adBreakStarted、adBreakEnded の 3 つのコールバック メソッドを実装します。

    3. ストリームが読み込まれたときにトリックプレイを無効にして、広告ブレーク開始イベントが発生する前に、ストリームが開始した瞬間にユーザーがプレロールをスキップできないようにします。

    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
    Sdk.xml

    スキップ可能な広告をサポートするために、seek コールバック メソッドを追加します。詳しくは、スキップ可能な広告のサポートを追加するをご覧ください。

  2. setupVideoPlayer() サブルーチンで使用される urlData、adPlaying、video フィールドを追加します。

    <field id="urlData" type="assocarray" />
<field id="adPlaying" type="Boolean" />
<field id="video" type="Node" />
    Sdk.xml

ストリーム リクエストを作成して実行する

DAI ストリームをリクエストする手順は次のとおりです。

  1. ストリームを作成してリクエストする 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 Sub
    Sdk.xml

  2. loadStream() サブルーチンで使用される streamData フィールドと streamManagerReady フィールドを追加します。

    <field id="streamManagerReady" type="Boolean" />
<field id="streamData" type="assocarray" />
    Sdk.xml

  3. ストリーム マネージャーが利用できない場合は、runThread() サブルーチンから loadStream() サブルーチンを呼び出します。

    if not m.top.streamManagerReady
  loadStream()
End If
    Sdk.xml

  4. VOD またはライブ配信を選択します。次の例には、ライブ配信と 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"
}
    MainScene.xml

    デフォルトでは、このガイドは 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
MainScene.xml

ストリームの再生を開始する 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
MainScene.xml

ストリーム メタデータをリッスンする

ストリーム再生中に実行され、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
Sdk.xml

広告イベントをリッスンする

ストリーム メタデータを 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
Sdk.xml

スキップ可能な広告のサポートを追加する（省略可）

スキップ可能な広告をサポートするには、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
Sdk.xml