הגדרת 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

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

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

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

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

הפעלת הסרטון

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

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

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

יצירת קובץ Sdk.xml

מוסיפים קובץ חדש לפרויקט לצד MainScene.xml בשם Sdk.xml, ומוסיפים את ה-boilerplate הבא:

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() של listener כדי להגיב לאירועי טעינה של 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

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

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

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