الإعداد باستخدام "إدراج الإعلان الديناميكي" (DAI) مع الخدمة الكاملة

اختيار النظام الأساسي: HTML5 Android iOS tvOS Cast Roku

يوضّح هذا الدليل كيفية دمج حزمة تطوير البرامج (SDK) لتقنية IMA DAI في تطبيق مشغّل فيديو. إذا أردت الاطّلاع على نموذج دمج مكتمل أو اتّباعه، يمكنك تنزيل المثال الأساسي من GitHub.

ملاحظة: تتوافق حزمة IMA DAI SDK لأجهزة Roku مع كلّ من أحداث البث المباشر عبر بروتوكول HLS وDASH، بدون أي اختلافات في التنفيذ.

لاستخدام IMA DAI، يجب أن يكون لديك حساب "إصدار متقدّم من مدير إعلانات Google‏ 360". إذا كان لديك حساب على "مدير إعلانات Google"، يُرجى التواصل مع مدير حسابك لمزيد من التفاصيل. للحصول على معلومات حول الاشتراك في "إدارة إعلانات Google"، يُرجى الانتقال إلى مركز مساعدة "إدارة إعلانات Google".

ملاحظة: للحصول على معلومات عن الدمج مع منصات أخرى أو عن استخدام حِزم تطوير البرامج (SDK) لإعلانات الوسائط التفاعلية من جهة العميل، يُرجى الاطّلاع على حِزم تطوير البرامج لإعلانات الوسائط التفاعلية.

نظرة عامة على IMA DAI

يتضمّن تنفيذ ميزة "إدراج الإعلان الديناميكي" في "حزمة تطوير البرامج لإعلانات الوسائط التفاعلية" مكوّنَين رئيسيَّين في حزمة تطوير البرامج (SDK) كما هو موضّح في هذا الدليل:

• ‫ StreamRequest: عنصر يحدّد طلب بث يمكن أن تكون طلبات البث لفيديوهات عند الطلب أو أحداث بث مباشر. تحدّد طلبات البث المباشر مفتاح مادة عرض، بينما تحدّد طلبات الفيديو عند الطلب معرّف "نظام إدارة المحتوى" ومعرّف الفيديو. يمكن أن يتضمّن كلا نوعَي الطلبات اختياريًا مفتاح واجهة برمجة التطبيقات اللازم للوصول إلى أحداث بث معيّنة، ورمز شبكة "إدارة إعلانات Google" لكي تتعامل حزمة IMA SDK مع معرّفات الإعلانات على النحو المحدّد في إعدادات "إدارة إعلانات Google".
• ‫ StreamManager: عنصر يعالج أحداث بث "إدراج الإعلانات الديناميكية" والتفاعلات مع الخلفية الخاصة بهذه الميزة. يتولّى مدير البث أيضًا تتبُّع إشعارات الاتصال وإعادة توجيه أحداث البث والإعلانات إلى الناشر.

المتطلبات الأساسية

• يُرجى الاطّلاع على صفحة التوافق للتأكّد من أنّ حالة الاستخدام المقصودة متوافقة.
• تنزيل رمز مشغّل 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 الإعلاني

تعتمد حزمة تطوير البرامج (SDK) لتقنية 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

تحميل حزمة تطوير البرامج (SDK) لتقنية IMA DAI

لتحميل حزمة تطوير البرامج (SDK) لتقنية IMA DAI، اتّبِع الخطوات التالية:

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() للاستجابة لأحداث تحميل حزمة تطوير البرامج (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. استخدِم الإجراء 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
   

إنشاء طلب بث وتنفيذه

لطلب بث "إدراج إعلان ديناميكي"، اتّبِع الخطوات التالية:

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. اختاروا بين فيديو عند الطلب أو بث مباشر. يحتوي المثال التالي على مَعلمات بث مباشر وبث فيديو عند الطلب:

   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
   

   يستخدم هذا الدليل تلقائيًا بث الفيديو عند الطلب. يمكنك استخدام البث المباشر بدلاً من ذلك عن طريق تغيير المتغيّر 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():

نقطة أساسية: يجب إعادة توجيه جميع الرسائل إلى حزمة تطوير البرامج (SDK) لضمان تشغيل الإعلانات بشكل صحيح.

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 إلى عنصر المشغّل في حزمة تطوير البرامج (SDK) لتقنية 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