راه‌اندازی کیت توسعه نرم‌افزار IMA برای DAI

کیت‌های توسعه نرم‌افزار IMA ادغام آگهی‌های چندرسانه‌ای در وب‌سایت‌ها و برنامه‌هایتان را آسان می‌کنند. کیت‌های توسعه نرم‌افزار IMA می‌توانند از هر سرور آگهی مطابق با VAST درخواست آگهی کنند و بازپخش آگهی را در برنامه‌هایتان مدیریت کنند. با کیت‌های توسعه نرم‌افزار IMA DAI، برنامه‌ها درخواست جاری‌سازی برای ویدیو آگهی و محتوا (چه ویدیو به‌درخواست و چه محتوای زنده) ارسال می‌کنند. سپس کیت توسعه نرم‌افزار یک جریان ویدیویی ترکیبی برمی‌گرداند، بنابراین لازم نیست جابه‌جایی بین ویدیو آگهی و محتوا را در برنامه‌تان مدیریت کنید.

راه‌حل DAI موردعلاقه‌تان را انتخاب کنید

«بازرسی پویای ARP» کامل

این راهنما نحوه ادغام IMA DAI SDK در برنامه پخش‌کننده ویدیو را نشان می‌دهد. اگر می‌خواهید یک نمونه ادغام کامل را مشاهده کنید یا با آن همراهی کنید، نمونه اولیه را از GitHub بارگیری کنید.

نمای کلی IMA DAI

پیاده‌سازی IMA DAI شامل دو جزء اصلی SDK است که در این راهنما نشان داده شده است:

• StreamRequest: شیئی که درخواست جاری‌سازی را تعریف می‌کند. درخواست‌های جاری‌سازی می‌تواند برای ویدیو به‌درخواست یا جاری‌سازی زنده باشد. درخواست‌های جاری‌سازی زنده یک کلید دارایی را مشخص می‌کنند، درحالی‌که درخواست‌های VOD یک شناسه CMS و شناسه ویدیو را مشخص می‌کنند. هر دو نوع درخواست می‌توانند به‌صورت اختیاری شامل کلید API موردنیاز برای دسترسی به جاری‌سازی‌های مشخص‌شده و کد شبکه Google Ad Manager برای IMA SDK باشند تا شناسه‌های آگهی را همان‌طور که در تنظیمات Google Ad Manager مشخص شده است مدیریت کند.
• 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» به «چارچوب تبلیغات Roku» وابسته است. برای بار کردن چارچوب، موارد زیر را به manifest و Sdk.xml اضافه کنید:

bs_libs_required=roku_ads_lib,googleima3
manifest

Library "Roku_Ads.brs"
Library "IMA3.brs"
Sdk.xml

بار کردن کیت توسعه نرم‌افزار درج آگهی پویا در آگهی‌های رسانه‌ای تعاملی

برای بار کردن کیت توسعه نرم‌افزار IMA DAI، مراحل زیر را انجام دهید:

1. کیت توسعه نرم‌افزار IMA را با فراخوانی New_IMASDK() مقداردهی اولیه کنید:

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

2. با ایجاد فیلد بولی sdkLoaded، بار شدن IMA را پیگیری کنید:

   <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() را برای پاسخ دادن به رویدادهای بار کیت توسعه نرم‌افزار ایجاد کنید:

   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. آن پخش‌کننده جاری‌سازی را طوری پیاده‌سازی کنید که سه روش برگشتی داشته باشد: 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() برای ایجاد و درخواست جاری‌سازی ایجاد کنید. برای پشتیبانی از واسط کاربر آگهی، مانند نمادهای «انتخاب‌های آگهی»، باید همچنین ارجاعی به گره حاوی ویدیو محتوای خود به‌عنوان بخشی از درخواستتان ارسال کنید:

   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 ایجاد کنید تا درطول بازپخش جاری‌سازی اجرا شود و فراداده جاری‌سازی را بااستفاده از StreamManager.onMessage() به IMA ارسال کند:

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» اضافه کنید که ویدیو را به‌صورت برنامه‌ریزی‌شده به مکان مشخص‌شده در ثانیه‌های ممیز شناور می‌برد.

برای پشتیبانی از آگهی‌های ردشدنی، باید مطمئن شوید که 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