הגדרה עם DAI בשירות מלא

במדריך הזה מוסבר איך לשלב את IMA DAI SDK באפליקציה של נגן וידאו. אם אתם רוצים לראות או לעקוב אחרי שילוב לדוגמה, אתם יכולים להוריד את הדוגמה הבסיסית מ-GitHub.

סקירה כללית על IMA DAI

הטמעת IMA DAI כוללת שני רכיבי SDK עיקריים, כפי שמוצג במדריך הזה:

• StreamRequest: אובייקט שמגדיר בקשה לשידור. הבקשות לשידור יכולות להיות לווידאו על פי דרישה (VOD) או לשידורים חיים. בבקשות לשידור חי מציינים מפתח נכס, ובבקשות ל-VOD מציינים מזהה CMS ומזהה סרטון. שני סוגי הבקשות יכולים לכלול מפתח API שנדרש כדי לגשת לסטרימים שצוינו, וקוד רשת של Google Ad Manager כדי ש-IMA SDK יטפל במזהי מודעות כפי שצוין בהגדרות של Google Ad Manager.
• StreamManager: אובייקט שמטפל בסטרימינג של הטמעת מודעות דינמיות ובאינטראקציות עם הקצה העורפי של DAI. מנהל השידור גם מטפל בפינגים של מעקב ומעביר אירועים של שידורים ומודעות לבעל האפליקציה.

דרישות מוקדמות

• כדאי לקרוא את דף התאימות שלנו כדי לוודא שהתרחיש לדוגמה שאתם מתכננים נתמך.
• מורידים את הקוד לדוגמה של נגן Roku.
• פורסים את קוד הנגן לדוגמה במכשיר Roku כדי לוודא שהגדרת הפיתוח פועלת.

הפעלת הסרטון

נגן הווידאו לדוגמה שסופק מפעיל סרטון תוכן באופן מיידי. פורסים את הנגן לדוגמה בנגן Roku כדי לוודא שסביבת הפיתוח מוגדרת כמו שצריך.

הפיכת נגן הווידאו לנגן סטרימינג של IMA DAI

כדי להטמיע נגן סטרימינג, פועלים לפי השלבים הבאים.

יצירת Sdk.xml

מוסיפים לפרויקט קובץ חדש בשם Sdk.xml לצד MainScene.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. מפעילים את 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. יוצרים את שגרות המשנה של המאזינים 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. משתמשים ב-method‏ createPlayer() כדי ליצור את נגן השידור החי.

   2. מגדירים בנגן הסטרימינג שלוש שיטות קריאה חוזרת: 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
   

   מוסיפים שיטת קריאה חוזרת (callback) מסוג 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() כדי ליצור ולבקש שידור. כדי לתמוך בממשק המשתמש של המודעות, כמו סמלי AdChoices, צריך גם להעביר הפניה לצומת שמכיל את סרטון התוכן כחלק מהבקשה:

   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():

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 יכול להפיק אירועי מודעות במהלך הפסקות למודעות. יוצרים רכיבי event listener של מודעות לפי הצורך כדי להגיב לאירועים של מודעות:

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 לאובייקט player של 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