تفعيل الإعلانات الصورية الخطية

تتيح حزمة IMA SDK لـ HTML5 استخدام الإعلانات الصورية الخطية بالإضافة إلى إعلانات الفيديو الخطية. للاطّلاع على تفاصيل حول إعلانات الفيديو الخطية، يُرجى مراجعة نظرة عامة على الإعلانات في Video Solutions.

يمكن أن يؤدي تفعيل الإعلانات الصورية الخطية إلى زيادة الطلب على مساحتك الإعلانية، لأنّ الإعلانات الصورية الخطية تتنافس مع إعلانات الفيديو الخطية على مساحتك الإعلانية. تتولّى IMA عرض الإعلانات الصورية الخطية، ولكن عليك إعداد ميزة رصد محتوى الفيديو. يختلف تنفيذ ميزة "رصد المحتوى" في IMA حسب ما إذا كنت تنشئ مشغّل المحتوى في إطار المصدر نفسه الذي تستخدمه لمشغّل الإعلانات، أو إذا كنت تنشئ مشغّل الإعلانات في إطار متعدّد المصادر.

ملاحظة: للوصول إلى طلبات الإعلانات الصورية الخطية، يجب إعداد ميزة "رصد المحتوى". في حال عدم إعداد ميزة "رصد المحتوى"، لن تكون مساحتك الإعلانية مؤهَّلة.

يتناول هذا الدليل كيفية إعداد ميزة "رصد المحتوى" لتفعيل الإعلانات الصورية الخطية، وتغيير مشغّل فيديو المحتوى، وإيقاف جمع إشارات المحتوى.

إعداد ميزة "رصد المحتوى"

لتفعيل الإعلانات الصورية الخطية لطلبات عرض الإعلانات، اتّبِع الخطوات التالية:

المصدر نفسه

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

• الخيار المفضّل: مرِّر مشغّل الفيديو إلى طلب AdsManagerLoadedEvent.getAdsManager(). على الرغم من أنّ getAdsManager() تتيح لك تمرير عنصر يحتوي على سمة currentTime، يجب تمرير مثيل HTMLVideoElement إلى getAdsManager() لإتاحة رصد المحتوى.

  function onAdsManagerLoaded(adsManagerLoadedEvent) {
    // Set any AdsRenderingSettings here.
    const adsRenderingSettings = new google.ima.AdsRenderingSettings();
  
    // Get the ads manager.
    adsManager =
      adsManagerLoadedEvent.getAdsManager(videoElement, adsRenderingSettings);
  }
  

• إذا لم تتمكّن من توفير مشغّل المحتوى أثناء طلب AdsManagerLoadedEvent.getAdsManager()، يمكنك استدعاء طريقة AdsManager.configureAdsManager() باستخدام مشغّل الفيديو. لكي تعمل ميزة رصد المحتوى، يجب أن يكون المحتوى HTMLVideoElement.

function onAdsManagerLoaded(adsManagerLoadedEvent) {
  adsManager =
    adsManagerLoadedEvent.getAdsManager(null);
  adsManager.configureAdsManager(videoElement);
}

في حال عدم إعداد ميزة "رصد المحتوى"، قد تتوقف خوادم إعلانات Google عن عرض الإعلانات الصورية الخطية.

إذا كان مشغّل المحتوى في المصدر نفسه الذي تحمّل منه حزمة IMA SDK، لن تحتاج إلى إجراء أي تغييرات على عملية تنفيذ حزمة IMA SDK للتعامل مع تغيير مشغّل المحتوى أو إيقاف جمع إشارات المحتوى.

متعدّد المصادر

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

إذا واصلت وضع مشغّل المحتوى في مصدر مختلف عن حزمة IMA SDK بدون تنفيذ فئة CrossOriginProxy، قد تتوقف خوادم إعلانات Google عن عرض الإعلانات الصورية الخطية.

لتحميل فئة CrossOriginProxy في تطبيقك، اتّبِع الخطوات التالية:

1. في ملف HTML، استورِد ملف ima_proxy.js:

   <html>
     <head>
       <title>IMA HTML5 cross-origin iframe sample</title>
       <link rel="stylesheet" href="style.css">
     </head>
   
     <body>
       <div id="mainContainer">
         <div id="content">
           <video id="contentElement">
             <source src="https://storage.googleapis.com/gvabox/media/samples/stock.mp4"></source>
           </video>
         </div>
   
         <!-- The cross-origin iframe where you load IMA SDK and play ads. -->
         <iframe id="adContainerIframe"
                 src="https://cross-origin-domain.com/ads-sandbox.html" >
         </iframe>
   
       </div>
       <button id="playButton">Play</button>
   
       <script src="//imasdk.googleapis.com/js/sdkloader/ima_proxy.js"></script>
       <script src="main.js"></script>
     </body>
   </html>
   

2. في ملف main.js، احصل على مثيل CrossOriginProxy.

3. استدعِ طريقة setVideoElements() مع مصفوفة من جميع مشغّلات الفيديو التي تعرض الإعلانات على صفحتك أو تطبيقك.

قبل تقديم طلب عرض الإعلان، عليك تمرير عناصر الفيديو إلى مثيل CrossOriginProxy باستخدام طلب setVideoElements(). يمرّر المثال التالي صفيفة تحتوي على مشغّل فيديو واحد للمحتوى:

// On window load attach an event to the play button click
// that triggers playback of the content video element.
window.addEventListener('load', function(event) {
videoContent = document.getElementById('contentElement');
ima.crossOriginProxy.getInstance().setVideoElements([videoContent]);
playButton = document.getElementById('playButton');
playButton.addEventListener('click', playAds);
});

تغيير مشغّل فيديو المحتوى

إذا غيّرت مشغّل فيديو المحتوى أو أضفت مشغّل فيديو آخر، عليك تمرير مصفوفة جديدة إلى طريقة setVideoElements(). عند إجراء طلب البيانات الجديد من setVideoElements()، تبدأ واجهة IMA في جمع الإشارات لمشغّل المحتوى الجديد، وتتوقف عن جمع الإشارات لأي مشغّلات محتوى تم تمريرها في طلبات البيانات السابقة.

يمرّر المثال التالي عنصر الفيديو الجديد إلى الفئة CrossOriginProxy:

function createNewContentPlayer(newPlayerId) {
newVideoContent = document.getElementById(newPlayerId);
ima.crossOriginProxy.getInstance().setVideoElements([newVideoContent]);

// Continue with any other steps needed to initiate the content player
}

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

عند الانتهاء من تشغيل الإعلانات واستدعاء الطريقة AdsLoader.destroy()، عليك أيضًا استدعاء الطريقة setVideoElements() باستخدام مصفوفة فارغة. يؤدي إجراء طلب setVideoElements() باستخدام مصفوفة فارغة إلى إسقاط الإشارة إلى مشغّلات المحتوى التي تحتفظ بها وكالة التسويق عبر المؤثرين (IMA) ويمنع حدوث مشاكل تسرّب الذاكرة.