หน้านี้ได้รับการแปลโดย Cloud Translation API

เริ่มต้นใช้งาน IMA DAI SDK

IMA SDK ช่วยให้ผสานรวมโฆษณามัลติมีเดียลงในเว็บไซต์และแอปได้อย่างง่ายดาย IMA SDK สามารถส่งคําขอโฆษณาจากเซิร์ฟเวอร์โฆษณา ที่เป็นไปตามข้อกําหนดของ VAST ใดก็ได้ และจัดการการเล่นโฆษณาในแอป เมื่อใช้ IMA DAI SDK แอปจะส่งคําขอสตรีมสําหรับโฆษณาและวิดีโอเนื้อหา ไม่ว่าจะเป็น VOD หรือเนื้อหาสด จากนั้น SDK จะแสดงผลสตรีมวิดีโอแบบรวม คุณจึงไม่ต้องจัดการการสลับระหว่างโฆษณากับวิดีโอเนื้อหาภายในแอป

เลือกโซลูชัน DAI ที่คุณสนใจ

DAI แบบครบวงจร

คู่มือนี้แสดงวิธีผสานรวม IMA DAI SDK เข้ากับแอปโปรแกรมเล่นวิดีโอแบบง่าย หากต้องการดูหรือทําตามตัวอย่างการผสานรวมที่เสร็จสมบูรณ์ ให้ดาวน์โหลดตัวอย่างพื้นฐานจาก GitHub

ภาพรวม IMA DAI

การติดตั้งใช้งาน IMA DAI ประกอบด้วยคอมโพเนนต์ SDK หลัก 2 รายการตามที่แสดงในคู่มือนี้

StreamRequest: ออบเจ็กต์ที่กําหนดคําขอสตรีม คำขอสตรีมอาจเป็นคำขอสำหรับวิดีโอออนดีมานด์หรือสตรีมแบบสดก็ได้ คำขอจะระบุรหัสเนื้อหา รวมถึงคีย์ 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>

คุณจะต้องแก้ไขทั้ง 2 ไฟล์นี้ตลอดทั้งคู่มือนี้

โหลดเฟรมเวิร์กการโฆษณาของ Roku

IMA DAI SDK ขึ้นอยู่กับเฟรมเวิร์กโฆษณาของ Roku หากต้องการโหลดเฟรมเวิร์ก ให้เพิ่มข้อมูลต่อไปนี้ลงใน manifest และ Sdk.xml

manifest

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 สตรีมเพลเยอร์นี้ใช้เมธอดการเรียกกลับ 3 รายการ ได้แก่ 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

หากต้องการรองรับ 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 &lt;&gt; 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"] &lt;&gt; 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 ไปยังออบเจ็กต์ player ของ 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