برای گفتگو و ارائه بازخورد در مورد محصولات ما، به کانال رسمی Ad Manager Discord در سرور انجمن تبلیغات و اندازه‌گیری Google بپیوندید.

این صفحه به‌وسیله ‏Cloud Translation API‏ ترجمه شده است.

راه اندازی IMA SDK برای DAI، راه اندازی IMA SDK برای DAI، راه اندازی IMA SDK برای DAI، راه اندازی IMA SDK برای DAI

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

کیت‌های توسعه نرم‌افزار IMA ادغام تبلیغات چندرسانه‌ای را در وب‌سایت‌ها و برنامه‌های شما آسان می‌کنند. کیت‌های توسعه نرم‌افزار IMA می‌توانند از هر سرور تبلیغاتی سازگار با VAST درخواست تبلیغات کنند و پخش تبلیغات را در برنامه‌های شما مدیریت کنند. با کیت‌های توسعه نرم‌افزار IMA DAI، برنامه‌ها درخواست پخش جریانی برای تبلیغات و ویدیوی محتوا - چه 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 : شیء‌ای که جریان‌های درج تبلیغات پویا و تعاملات با بک‌اند 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 را بارگیری کنید

کیت توسعه نرم‌افزار IMA DAI به چارچوب تبلیغاتی Roku وابسته است. برای بارگذاری این چارچوب، موارد زیر را به manifest و Sdk.xml اضافه کنید:

bs_libs_required=roku_ads_lib,googleima3manifest

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

بارگیری SDK مربوط به IMA DAI

برای بارگذاری IMA DAI SDK، موارد زیر را انجام دهید:

مقداردهی اولیه IMA SDK با فراخوانی New_IMASDK() :

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

با ایجاد یک فیلد بولی sdkLoaded پیگیری کنید که آیا IMA بارگذاری شده است یا خیر:
```
<field id="sdkLoaded" type="Boolean" />Sdk.xml
```
زیرروال loadSdk() را از زیرروال اصلی runThread() فراخوانی کنید:
```
if not m.top.sdkLoaded
  loadSdk()
End IfSdk.xml
```

تابع 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 functionMainScene.xml

تابع loadImaSdk() را از تابع init() فراخوانی کنید.

زیرروال‌های شنونده‌ی 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 SubMainScene.xml

یک پخش‌کننده جریان IMA ایجاد کنید

برای ایجاد یک پخش‌کننده‌ی جریان IMA، موارد زیر را انجام دهید:

یک زیرروال setupVideoPlayer() ایجاد کنید که موارد زیر را انجام دهد:

برای ایجاد پخش‌کننده‌ی جریان از متد createPlayer() استفاده کنید.
از آن پخش‌کننده‌ی استریم بخواهید سه متد فراخوانی به loadUrl ، adBreakStarted و adBreakEnded را پیاده‌سازی کند.
غیرفعال کردن پخش ترفند هنگام بارگذاری پخش زنده، مانع از آن می‌شود که کاربران در لحظه شروع پخش زنده، قبل از شروع رویداد شروع پخش، از پیش‌پخش صرف‌نظر کنند.

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 SubSdk.xml

برای پشتیبانی از تبلیغات قابل رد شدن، یک متد فراخوانی seek اضافه کنید. برای جزئیات بیشتر، به افزودن پشتیبانی برای تبلیغات قابل رد شدن مراجعه کنید.

فیلدهای urlData ، adPlaying و video که در زیرروال setupVideoPlayer() استفاده شده‌اند را اضافه کنید:
```
<field id="urlData" type="assocarray" />
<field id="adPlaying" type="Boolean" />
<field id="video" type="Node" />Sdk.xml
```

ایجاد و اجرای درخواست جریان

برای درخواست جریان DAI خود، موارد زیر را انجام دهید:

یک زیرروال 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 SubSdk.xml

فیلدهای streamData و streamManagerReady که در زیرروال loadStream() استفاده شده‌اند را اضافه کنید:
```
<field id="streamManagerReady" type="Boolean" />
<field id="streamData" type="assocarray" />Sdk.xml
```
اگر مدیر جریان در دسترس نیست، زیرروال loadStream() را از زیرروال runThread() فراخوانی کنید:
```
if not m.top.streamManagerReady
  loadStream()
End IfSdk.xml
```
بین 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
```
به طور پیش‌فرض، این راهنما از پخش زنده (livestream) استفاده می‌کند. شما می‌توانید با تغییر متغیر selectedStream از شیء m.testVodStream به شیء m.testLiveStream ، از پخش زنده (livestream) استفاده کنید.

شروع استریم

زیرروال urlLoadRequested() را برای گوش دادن به داده‌های استریم و فراخوانی زیرروال playStream() ایجاد کنید:

Sub urlLoadRequested(message as Object)
  print "Url Load Requested ";message
  data = message.getData()

  playStream(data.manifest, data.format)
End SubMainScene.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 SubMainScene.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 SubSdk.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 FunctionSdk.xml

اضافه شدن پشتیبانی برای تبلیغات قابل رد شدن (اختیاری)

برای پشتیبانی از تبلیغات قابل رد شدن، باید یک متد seek به شیء پخش‌کننده‌ی 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 FunctionSdk.xml