راه‌اندازی با «درج آگهی پویا» با خدمات کامل

پلاتفرم را انتخاب کنید: HTML5 Android iOS tvOS Cast Roku

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

توجه: کیت توسعه نرم‌افزار IMA DAI برای Roku از هر دو جاری‌سازی HLS و DASH پشتیبانی می‌کند و هیچ تفاوتی در پیاده‌سازی آن‌ها وجود ندارد.

برای استفاده از IMA DAI، باید حساب Ad Manager 360 Advanced داشته باشید. اگر حساب Ad Manager دارید، برای جزئیات بیشتر با مدیر حسابتان تماس بگیرید. برای کسب اطلاعات درباره ثبت‌نام در Ad Manager، به مرکز راهنمایی Ad Manager بروید.

توجه: برای کسب اطلاعات درباره ادغام با پلاتفرم‌های دیگر یا استفاده از کیت‌های توسعه نرم‌افزار IMA سمت کارخواه، به کیت‌های توسعه نرم‌افزار آگهی‌های رسانه‌ای تعاملی مراجعه کنید.

نمای کلی 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

فایل جدیدی به نام 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 به 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، کارهای زیر را انجام دهید:

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