תחילת העבודה עם IMA DAI SDK

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 Advanced. אם יש לך חשבון Ad Manager, אפשר לפנות למנהל החשבון כדי לקבל פרטים נוספים. מידע על ההרשמה ל-Ad Manager זמין במרכז העזרה של Ad Manager.

הערה: למידע על שילוב עם פלטפורמות אחרות או על השימוש ב-IMA SDK בצד הלקוח, אפשר לעיין במאמר ערכות SDK של מודעות מדיה אינטראקטיביות.

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

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

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

עליך לערוך את שני הקבצים האלה לאורך המדריך.

טעינת מסגרת הפרסום של Roku

IMA DAI SDK תלוי במסגרת הפרסום של Roku. כדי לטעון את ה-framework, צריך להוסיף את הקוד הבא ל-manifest ול-Sdk.xml:

מניפסט

bs_libs_required=roku_ads_lib,googleima3

Sdk.xml

Library "Roku_Ads.brs"
Library "IMA3.brs"

טעינת IMA DAI SDK

השלב הראשון בטעינת השידור של IMA DAI SDK הוא טעינה והפעלה של 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. נגן השידור הזה מטמיע שלוש שיטות של קריאה חוזרת: loadUrl, adBreakStarted ו-adBreakEnded. בנוסף, השביתו את הפעלת הטריקים בזמן טעינת השידור. כך המשתמשים לא יוכלו לדלג על מודעה לפני סרטון (pre-roll) ברגע שהיא מתחילה, לפני תחילת האירוע של ההפסקה למודעות.

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, כמו הסמלים של adChoices, עליך להעביר כחלק מהבקשה הפניה לצומת שמכיל את סרטון התוכן שלך.

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

יש להוסיף פונקציות event listener ולהתחיל את השידור

אחרי שמבקשים את השידור, נשארו רק כמה דברים לעשות: להוסיף מאזינים של אירועים כדי לעקוב אחרי ההתקדמות של המודעות, להפעיל את השידור ולהעביר הודעות מ-Roku ל-SDK.

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

כדי לתמוך במודעות שניתן לדלג עליהן, עליכם גם להגדיר את 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