ตั้งค่า IMA SDK สําหรับ DAI

เลือกแพลตฟอร์ม HTML5 Android iOS tvOS Cast Roku

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

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

บริการเต็มรูปแบบ การแสดงพอดแคสต์

DAI แบบบริการเต็มรูปแบบ

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

หมายเหตุ: IMA DAI SDK สำหรับ Roku รองรับทั้งสตรีม HLS และ DASH โดยไม่มีความแตกต่างในการใช้งาน

หากต้องการใช้ IMA DAI คุณต้องมีบัญชี Ad Manager 360 ขั้นสูง หาก คุณมีบัญชี Ad Manager โปรดติดต่อผู้จัดการฝ่ายดูแลลูกค้าเพื่อขอรายละเอียดเพิ่มเติม ดูข้อมูล เกี่ยวกับการลงชื่อสมัครใช้ Ad Manager ได้ที่ ศูนย์ช่วยเหลือของ Ad Manager

หมายเหตุ: ดูข้อมูลเกี่ยวกับการผสานรวมกับแพลตฟอร์มอื่นๆ หรือการใช้ SDK ฝั่งไคลเอ็นต์ของ IMA ได้ที่ SDK โฆษณาสื่ออินเทอร์แอกทีฟ

ภาพรวม DAI ของ IMA

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

• StreamRequest: ออบเจ็กต์ที่กำหนดคำขอสตรีม คำขอสตรีมอาจเป็นคำขอสำหรับวิดีโอออนดีมานด์หรือไลฟ์สด คำขอไลฟ์สดจะระบุคีย์เนื้อหา ส่วนคำขอ VOD จะระบุรหัส CMS และรหัสวิดีโอ คำขอทั้ง 2 ประเภทอาจมีคีย์ API ที่จำเป็นต่อการเข้าถึงสตรีมที่ระบุ และรหัสเครือข่าย Google Ad Manager สำหรับ 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>

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

โหลดกรอบการโฆษณาของ Roku

IMA DAI SDK ขึ้นอยู่กับกรอบการโฆษณาของ Roku หากต้องการโหลด เฟรมเวิร์ก ให้เพิ่มข้อมูลต่อไปนี้ลงใน 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. เริ่มต้น IMA SDK ด้วยการเรียก New_IMASDK()

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

2. ติดตามว่า IMA โหลดแล้วหรือไม่โดยสร้างsdkLoadedฟิลด์บูลีน

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

3. เรียกใช้รูทีนย่อย loadSdk() จากรูทีนย่อยหลัก runThread() โดยทำดังนี้

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

4. สร้างฟังก์ชัน loadImaSdk() ใน MainScene.xml เพื่อสร้างและเรียกใช้ออบเจ็กต์ 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. เรียกใช้ฟังก์ชัน loadImaSdk() จากฟังก์ชัน init()

6. สร้างรูทีนย่อยของ Listener onSdkLoaded() และ onSdkLoadedError() เพื่อ ตอบสนองต่อเหตุการณ์การโหลด SDK

   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. ให้โปรแกรมเล่นสตรีมนั้นใช้วิธีการเรียกกลับ 3 วิธี ได้แก่ loadUrl, adBreakStarted และ adBreakEnded

   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. เพิ่มฟิลด์ urlData, adPlaying และ video ที่ใช้ใน setupVideoPlayer() รูทีนย่อย

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

สร้างและดำเนินการคำขอสตรีม

หากต้องการขอสตรีม DAI ให้ทำดังนี้

1. สร้างloadStream()รูทีนย่อยเพื่อสร้างและขอสตรีม หากต้องการ รองรับ 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. เพิ่มฟิลด์ streamData และ streamManagerReady ที่ใช้ในloadStream() รูทีนย่อย

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

3. หากตัวจัดการสตรีมไม่พร้อมใช้งาน ให้เรียกloadStream()รูทีนย่อย จากรูทีนย่อยrunThread()

   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 คุณใช้ไลฟ์สดแทนได้โดยเปลี่ยนตัวแปร selectedStream จากออบเจ็กต์ m.testVodStream เป็นออบเจ็กต์ m.testLiveStream

เริ่มสตรีม

สร้างurlLoadRequested()รูทีนย่อยเพื่อฟังข้อมูลสตรีม และเรียกใช้playStream()รูทีนย่อย

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

รอรับข้อมูลเมตาของสตรีม

สร้างrunLoop()รูทีนย่อยที่มีลูป while เพื่อเรียกใช้ระหว่างการเล่นสตรีม และส่งข้อมูลเมตาสตรีมไปยัง IMA โดยใช้ StreamManager.onMessage()

ประเด็นสำคัญ: คุณต้องส่งต่อข้อความทั้งหมดไปยัง SDK เพื่อให้มั่นใจว่าโฆษณาจะเล่นได้อย่างถูกต้อง

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

เพิ่มการรองรับโฆษณาแบบข้ามได้ (ไม่บังคับ)

หากต้องการรองรับโฆษณาที่ข้ามได้ คุณต้องเพิ่มseekเมธอดลงใน ออบเจ็กต์เพลเยอร์ของ IMA DAI SDK ซึ่งจะค้นหาวิดีโอไปยังตำแหน่งที่ระบุโดยอัตโนมัติใน หน่วยวินาทีแบบทศนิยม

หากต้องการรองรับโฆษณาแบบข้ามได้ คุณต้องตรวจสอบว่าได้ตั้งค่า 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