إعداد حزمة تطوير البرامج لإعلانات الوسائط التفاعلية لعرض الإعلانات أثناء التشغيل

اختيار المنصة: HTML5 Android iOS tvOS Cast Roku

تسهّل حِزم تطوير البرامج (SDK) لإعلانات الوسائط التفاعلية دمج إعلانات الوسائط المتعددة في مواقعك الإلكترونية وتطبيقاتك. يمكن لحِزم تطوير البرامج لإعلانات الوسائط التفاعلية طلب الإعلانات من أي خادم إعلانات متوافق مع VAST وإدارة تشغيل الإعلانات في تطبيقاتك. باستخدام حِزم تطوير البرامج لإدراج الإعلانات الديناميكي في "إعلانات الوسائط التفاعلية"، تقدّم التطبيقات طلب بث لإعلان وفيديو محتوى، سواء كان فيديو عند الطلب أو محتوى مباشرًا. بعد ذلك، تعرض حزمة SDK بث فيديو مدمجًا، ما يغنيك عن إدارة التبديل بين الفيديو الإعلاني وفيديو المحتوى داخل تطبيقك.

اختيار حلّ "الإعلانات الديناميكية أثناء عرض الفيديو" الذي يهمّك

الخدمة الكاملة عرض الإعلانات المجمّعة

إدراج إعلان ديناميكي شامل

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

ملاحظة: تتوافق أداة تطوير البرامج لإعلانات الوسائط التفاعلية (DAI) من IMA على Roku مع كلّ من بث HLS وبث DASH، بدون أي اختلافات في التنفيذ.

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

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

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

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

• ‫ StreamRequest: كائن يحدّد طلب بث. يمكن أن تكون طلبات البث المباشر لفيديوهات عند الطلب أو أحداث بث مباشر. تحدّد طلبات البث المباشر مفتاح مادة عرض، بينما تحدّد طلبات الفيديو عند الطلب معرّفًا في "نظام إدارة المحتوى" ومعرّف فيديو. يمكن أن يتضمّن كلا نوعَي الطلبات اختياريًا مفتاح واجهة برمجة التطبيقات اللازم للوصول إلى عمليات البث المحدّدة، ورمز شبكة "مدير إعلانات Google" لكي تتعامل أداة تطوير البرامج لإعلانات الوسائط التفاعلية (IMA) مع معرّفات الإعلانات على النحو المحدّد في إعدادات "مدير إعلانات 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) لخدمة "الإعلانات الديناميكية أثناء عرض الفيديو" من "إعلانات الوسائط التفاعلية" على إطار عمل الإعلانات في Roku. لتحميل إطار العمل، أضِف ما يلي إلى manifest وSdk.xml:

bs_libs_required=roku_ads_lib,googleima3
manifest

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

تحميل حزمة تطوير البرامج لإدراج إعلان ديناميكي من "إعلانات الوسائط التفاعلية"

لتحميل حزمة تطوير البرامج لإعلانات البث المباشر من "إعلانات الوسائط التفاعلية"، اتّبِع الخطوات التالية:

1. إعداد حزمة تطوير البرامج لإعلانات الوسائط التفاعلية باستخدام طلب 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
   

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

لطلب بث 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
   

   يستخدم هذا الدليل تلقائيًا بث الفيديو عند الطلب. يمكنك استخدام البث المباشر بدلاً من ذلك من خلال تغيير المتغيّر 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 إلى عنصر المشغّل في حزمة 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 Function
Sdk.xml