البدء

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

يوضح هذا الدليل كيفية دمج حزمة تطوير البرامج لإعلانات الوسائط التفاعلية في تطبيق بسيط لمشغّل فيديو. إذا أردت ترغب في عرض أو متابعة تكامل نموذجي مكتمل، فقم بتنزيل مثال بسيط من GitHub. إذا كنت إذا كنت مهتمًا بمشغّل HTML5 الذي يحتوي على حزمة SDK مدمجة مسبقًا، فاطلع على المكوّن الإضافي لأداة تطوير البرامج لإعلانات الوسائط التفاعلية لـ Video.js.

نظرة عامة على إعلانات الوسائط التفاعلية من جهة العميل

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

  • AdDisplayContainer: عنصر حاوية يتم عرض الإعلانات فيه
  • AdsLoader: كائن يطلب الإعلانات ويتعامل مع الأحداث الواردة من الإعلانات ويطلب الردود يجب عليك فقط إنشاء مثيل برنامج تحميل إعلانات واحد، والذي يمكن إعادة استخدامه طوال عمر التطبيق.
  • AdsRequest: كائن يحدّد طلب الإعلانات تحدد طلبات الإعلانات عنوان URL لعلامة إعلانات نموذج عرض إعلانات الفيديو (VAST) إلى جانب مَعلمات إضافية، مثل سمات الإعلانات
  • AdsManager: كائن يحتوي على الاستجابة لطلب الإعلانات، ويتحكم في تشغيل الإعلان، ويراقب الإعلان الأحداث التي تم تنشيطها بواسطة حزمة تطوير البرامج (SDK).

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

قبل البدء، ستحتاج إلى ما يلي:

  • ثلاثة ملفات فارغة:
    • index.html
    • style.css
    • ads.js
  • لغة Python مثبتة على جهاز الكمبيوتر أو خادم ويب لاستخدامها في الاختبار

1. بدء خادم تطوير

ونظرًا لأن حزمة تطوير البرامج لإعلانات الوسائط التفاعلية تحمِّل التبعيات عبر البروتوكول نفسه الذي يتم تحميل الصفحة منه، استخدام خادم ويب لاختبار التطبيق. أبسط طريقة لبدء مشروع تطوير محلي هو استخدام خادم بايثون المدمج.

  1. يمكن أن يؤدي استخدام سطر أوامر من الدليل الذي يحتوي على تشغيل ملف index.html: 
      python -m http.server 8000
  2. في متصفِّح ويب، انتقِل إلى http://localhost:8000/.

يمكنك أيضًا استخدام أي خادم ويب آخر، مثل خادم خادم Apache HTTP.

2. إنشاء مشغّل فيديو بسيط

أولاً، عدِّل index.html لإنشاء عنصر فيديو HTML5 بسيط مضمّن في التفاف. وزرًا لبدء التشغيل. أضف أيضًا العلامات الضرورية لتحميل style.css وads.js. بعد ذلك، عدِّل styles.css ليصبح مشغّل الفيديو سريع الاستجابة للأجهزة المحمولة. أخيرًا، في ads.js، يجب تشغيل الفيديو عند التشغيل النقر فوقه.

index.html 

<!doctype html>
<html lang="en">
  <head>
    <title>IMA HTML5 Simple Demo</title>
    <meta charset="utf-8">
    <meta name="viewport" content="width=device-width, initial-scale=1, shrink-to-fit=no">
    <link rel="stylesheet" href="style.css">
  </head>
  <body>
    <div id="page-content">
      <div id="video-container">
        <video id="video-element">
          <source src="https://storage.googleapis.com/interactive-media-ads/media/android.mp4">
          <source src="https://storage.googleapis.com/interactive-media-ads/media/android.webm">
        </video>
      </div>
      <button id="play-button">Play</button>
    </div>
    <script src="ads.js"></script>
  </body>
</html>
style.css 
#page-content {
  position: relative;
  /* this element's width controls the effective height */
  /* of the video container's padding-bottom */
  max-width: 640px;
  margin: 10px auto;
}

#video-container {
  position: relative;
  /* forces the container to match a 16x9 aspect ratio */
  /* replace with 75% for a 4:3 aspect ratio, if needed */
  padding-bottom: 56.25%;
}

#video-element {
  /* forces the contents to fill the container */
  position: absolute;
  top: 0;
  left: 0;
  width: 100%;
  height: 100%;
}
ads.js 
var videoElement;

// On window load, attach an event to the play button click
// that triggers playback on the video element
window.addEventListener('load', function(event) {
  videoElement = document.getElementById('video-element');
  var playButton = document.getElementById('play-button');
  playButton.addEventListener('click', function(event) {
    videoElement.play();
  });
});

بعد إكمال هذه الخطوة، وعند فتح index.html في المتصفّح (من خلال صفحة التطوير الخادم) يجب أن تتمكن من رؤية عنصر الفيديو وسيبدأ الفيديو عند النقر على زر التشغيل

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

بعد ذلك، أضف إطار عمل إعلانات الوسائط التفاعلية باستخدام علامة نص برمجي في index.html، قبل علامة ads.js

index.html 
...

        </video>
      </div>
      <button id="play-button">Play</button>
    </div>
    <script src="//imasdk.googleapis.com/js/sdkloader/ima3.js"></script>
    <script src="ads.js"></script>
  </body>
</html>

4. إرفاق معالِجات الصفحات ومشغّل الفيديو

لتعديل سلوك مشغّل الفيديو باستخدام JavaScript، أضِف معالِجات الأحداث التي تؤدي إلى ظهور الإجراءات التالية:

  • عند انتهاء تحميل الصفحة، يجب إعداد حزمة تطوير البرامج لإعلانات الوسائط التفاعلية.
  • عند النقر على زر تشغيل الفيديو، حمِّل الإعلانات (ما لم تكن هناك إعلانات محمَّلة).
  • عندما يتم تغيير حجم نافذة المتصفّح، عدِّل عنصر الفيديو وadsManager. لجعل الصفحة تستجيب للأجهزة المحمولة
ads.js 
var videoElement;
// Define a variable to track whether there are ads loaded and initially set it to false
var adsLoaded = false;

window.addEventListener('load', function(event) {
  videoElement = document.getElementById('video-element');
  initializeIMA();
  videoElement.addEventListener('play', function(event) {
    loadAds(event);
  });
  var playButton = document.getElementById('play-button');
  playButton.addEventListener('click', function(event) {
    videoElement.play();
  });
});

window.addEventListener('resize', function(event) {
  console.log("window resized");
});

function initializeIMA() {
  console.log("initializing IMA");
}

function loadAds(event) {
  // Prevent this function from running on if there are already ads loaded
  if(adsLoaded) {
    return;
  }
  adsLoaded = true;

  // Prevent triggering immediate playback when ads are loading
  event.preventDefault();

  console.log("loading ads");
}

5- أنشئ حاوية الإعلان.

في معظم المتصفحات، تستخدم حزمة تطوير البرامج لإعلانات الوسائط التفاعلية عنصر حاوية إعلانات مخصصًا لعرض كلٍّ من الإعلانات عناصر واجهة المستخدم المتعلّقة بالإعلانات يجب تغيير حجم هذه الحاوية لتراكب عنصر الفيديو من أعلى اليسار. يتم ضبط ارتفاع وعرض الإعلانات الموضوعة في هذه الحاوية بواسطة adsManager، لذا لن تحتاج إلى ضبط هذه القيم يدويًا.

لتنفيذ عنصر حاوية الإعلان هذا، أنشئ أولاً div جديدة ضمن العنصر video-container ثم حدِّث CSS لوضع العنصر في أعلى اليسار الزاوية من video-element. أخيرًا، قم بتعريف متغير للحاوية داخل تعمل دالة initializeIMA() عند تحميل الصفحة.

index.html 
...

  <div id="video-container">
    <video id="video-element" controls>
      <source src="https://storage.googleapis.com/interactive-media-ads/media/android.mp4">
      <source src="https://storage.googleapis.com/interactive-media-ads/media/android.webm">
    </video>
    <div id="ad-container"></div>
  </div>

...
style.css 
...

#ad-container {
  position: absolute;
  top: 0;
  left: 0;
  width: 100%;
}
ads.js 
var videoElement;
var adsLoaded = false;
var adContainer;

...

function initializeIMA() {
  console.log("initializing IMA");
  adContainer = document.getElementById('ad-container');
}

6- إعداد AdsLoader وإرسال طلب عرض إعلانات

لطلب مجموعة من الإعلانات، أنشئ مثيل ima.AdsLoader. هذا المثيل تأخذ كائن AdDisplayContainer كإدخال ويمكن استخدامها لمعالجة ima.AdsRequest عناصر مرتبطة بعنوان URL لعلامة إعلان محدّدة. علامة الإعلان المستخدمة في يحتوي هذا المثال على إعلان ما قبل التشغيل مدته 10 ثوانٍ. ويمكنك اختبار عنوان URL لعلامة الإعلان هذه أو أي علامة أخرى باستخدام أداة فحص مجموعة فيديوهات إعلانات الوسائط التفاعلية

من بين أفضل الممارسات، ننصحك بالاحتفاظ بمثيل واحد من ima.AdsLoader فقط في العملية بأكملها. دورة حياة الصفحة. لإرسال طلبات إعلان إضافية، عليك إنشاء ima.AdsRequest جديدة. ولكن يجب إعادة استخدام ima.AdsLoader نفسها. لمزيد من المعلومات، يُرجى الاطّلاع على الأسئلة الشائعة حول حزمة تطوير البرامج لإعلانات الوسائط التفاعلية

ads.js 
var videoElement;
var adsLoaded = false;
var adContainer;
var adDisplayContainer;
var adsLoader;

...

function initializeIMA() {
  console.log("initializing IMA");
  adContainer = document.getElementById('ad-container');
  adDisplayContainer = new google.ima.AdDisplayContainer(adContainer, videoElement);
  adsLoader = new google.ima.AdsLoader(adDisplayContainer);

  // Let the AdsLoader know when the video has ended
  videoElement.addEventListener('ended', function() {
    adsLoader.contentComplete();
  });

  var adsRequest = new google.ima.AdsRequest();
  adsRequest.adTagUrl = 'https://pubads.g.doubleclick.net/gampad/ads?' +
      'iu=/21775744923/external/single_ad_samples&sz=640x480&' +
      'cust_params=sample_ct%3Dlinear&ciu_szs=300x250%2C728x90&' +
      'gdfp_req=1&output=vast&unviewed_position_start=1&env=vp&impl=s&correlator=';

  // Specify the linear and nonlinear slot sizes. This helps the SDK to
  // select the correct creative if multiple are returned.
  adsRequest.linearAdSlotWidth = videoElement.clientWidth;
  adsRequest.linearAdSlotHeight = videoElement.clientHeight;
  adsRequest.nonLinearAdSlotWidth = videoElement.clientWidth;
  adsRequest.nonLinearAdSlotHeight = videoElement.clientHeight / 3;

  // Pass the request to the adsLoader to request ads
  adsLoader.requestAds(adsRequest);
}

7. الاستماع إلى أحداث AdsLoader

عند تحميل الإعلانات بنجاح، تُصدر ima.AdsLoader حدث ADS_MANAGER_LOADED. تحليل الحدث الذي تم تمريره إلى معاودة الاتصال لإعداد عنصر AdsManager. يُحمِّل AdsManager الإعلانات الفردية كما هو محدّد في الاستجابة للإعلان للعلامة URL.

بالإضافة إلى ذلك، يجب الحرص على معالجة أي أخطاء قد تحدث أثناء عملية التحميل. إذا لم تكن الإعلانات تحميل الوسائط، فتأكد من استمرار تشغيل الوسائط، وبدون إعلانات، حتى لا يتداخل مع مع تجربة المستخدم.

ads.js 
var videoElement;
var adsLoaded = false;
var adContainer;
var adDisplayContainer;
var adsLoader;
var adsManager;

...

function initializeIMA() {
  console.log("initializing IMA");
  adContainer = document.getElementById('ad-container');
  adDisplayContainer = new google.ima.AdDisplayContainer(adContainer, videoElement);
  adsLoader = new google.ima.AdsLoader(adDisplayContainer);
  adsLoader.addEventListener(
      google.ima.AdsManagerLoadedEvent.Type.ADS_MANAGER_LOADED,
      onAdsManagerLoaded,
      false);
  adsLoader.addEventListener(
      google.ima.AdErrorEvent.Type.AD_ERROR,
      onAdError,
      false);

...

function onAdsManagerLoaded(adsManagerLoadedEvent) {
  // Instantiate the AdsManager from the adsLoader response and pass it the video element
  adsManager = adsManagerLoadedEvent.getAdsManager(
      videoElement);
}

function onAdError(adErrorEvent) {
  // Handle the error logging.
  console.log(adErrorEvent.getError());
  if(adsManager) {
    adsManager.destroy();
  }
}

8. بدء AdsManager

لبدء تشغيل الإعلان، يجب بدء تشغيل AdsManager. دعم الجوّال بشكل كامل في المتصفحات، فينبغي أن يؤدي ذلك إلى تفاعل المستخدم.

ads.js 
...

function loadAds(event) {
  // prevent this function from running on every play event
  if(adsLoaded) {
    return;
  }
  adsLoaded = true;

  // prevent triggering immediate playback when ads are loading
  event.preventDefault();

  console.log("loading ads");

  // Initialize the container. Must be done via a user action on mobile devices.
  videoElement.load();
  adDisplayContainer.initialize();

  var width = videoElement.clientWidth;
  var height = videoElement.clientHeight;
  try {
    adsManager.init(width, height, google.ima.ViewMode.NORMAL);
    adsManager.start();
  } catch (adError) {
    // Play the video without ads, if an error occurs
    console.log("AdsManager could not be started");
    videoElement.play();
  }
}

...

9. جعل AdsManager متجاوبًا

للتأكّد من أنّ حجم الإعلانات يتغيّر ديناميكيًا بحيث يتناسب مع حجم مشغّل الفيديو، إذا كانت الشاشة لتغيير الحجم أو الاتجاه، يجب أن يستدعي حدث تغيير حجم النافذة adsManager.resize().

ads.js 
...

window.addEventListener('resize', function(event) {
  console.log("window resized");
  if(adsManager) {
    var width = videoElement.clientWidth;
    var height = videoElement.clientHeight;
    adsManager.resize(width, height, google.ima.ViewMode.NORMAL);
  }
});

...

10. الاستماع إلى أحداث AdsManager

ويعمل AdsManager أيضًا على تنشيط العديد من الأحداث التي يجب معالجتها. يتم استخدام هذه الأحداث لتتبُّع التغييرات في الحالة وتشغيل المحتوى وإيقافه مؤقتًا في الفيديو وتسجيل الأخطاء.

معالجة الأخطاء

يمكن أن يكون معالج الأخطاء الذي تم إنشاؤه لـ AdsLoader بمثابة معالج أخطاء AdsManager عن طريق إضافة معالج أحداث جديد باستخدام دالة معاودة الاتصال نفسها.

ads.js 
...

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

  adsManager.addEventListener(
      google.ima.AdErrorEvent.Type.AD_ERROR,
      onAdError);
}

...

تشغيل أحداث التشغيل والإيقاف المؤقت

عندما تكون "AdsManager" جاهزة لإدراج إعلان للعرض، يتم تنشيط حدث CONTENT_PAUSE_REQUESTED. تعامل مع هذا الحدث من خلال بدء إيقاف مؤقت في مشغّل الفيديو الأساسي. وبالمثل، عند اكتمال إعلان، يطلق AdsManager حدث CONTENT_RESUME_REQUESTED. يمكنك معالجة هذا الحدث من خلال إعادة تشغيل التشغيل على ذات المحتوى الأساسي.

ads.js 
...

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

  adsManager.addEventListener(
      google.ima.AdErrorEvent.Type.AD_ERROR,
      onAdError);
  adsManager.addEventListener(
      google.ima.AdEvent.Type.CONTENT_PAUSE_REQUESTED,
      onContentPauseRequested);
  adsManager.addEventListener(
      google.ima.AdEvent.Type.CONTENT_RESUME_REQUESTED,
      onContentResumeRequested);
}

...

function onContentPauseRequested() {
  videoElement.pause();
}

function onContentResumeRequested() {
  videoElement.play();
}

تشغيل النقر للإيقاف المؤقت على الأجهزة الجوّالة

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

لتنفيذ النقر للإيقاف المؤقت، أضِف معالج نقرات إلى AdContainer وشغِّل التشغيل الأحداث أو إيقافها مؤقتًا على الفيديو الأساسي

ads.js 
...

function initializeIMA() {
  console.log("initializing IMA");
  adContainer = document.getElementById('ad-container');
  adContainer.addEventListener('click', adContainerClick);
  adDisplayContainer = new google.ima.AdDisplayContainer(adContainer, videoElement);
  adsLoader = new google.ima.AdsLoader(adDisplayContainer);

...

function adContainerClick(event) {
  console.log("ad container clicked");
  if(videoElement.paused) {
    videoElement.play();
  } else {
    videoElement.pause();
  }
}

...

تشغيل التشغيل على الإعلانات غير الخطية

تؤدي AdsManager إلى إيقاف فيديو المحتوى مؤقتًا عندما يكون الإعلان جاهزًا للعرض، ولكن يجب أن يكون هذا العنصر. الإعلانات غير الخطية، حيث يستمر تشغيل المحتوى أثناء يتم عرض إعلانك. لإتاحة الإعلانات غير الخطية، استمع إلى AdsManager حتى تنبعث من حدث LOADED. بعد ذلك، تحقق مما إذا كان الإعلان خطيًا، وإذا لم يكن خطيًا، استأنف التشغيل على عنصر فيديو.

ads.js 
...

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

  adsManager.addEventListener(
      google.ima.AdErrorEvent.Type.AD_ERROR,
      onAdError);
  adsManager.addEventListener(
      google.ima.AdEvent.Type.CONTENT_PAUSE_REQUESTED,
      onContentPauseRequested);
  adsManager.addEventListener(
      google.ima.AdEvent.Type.CONTENT_RESUME_REQUESTED,
      onContentResumeRequested);
  adsManager.addEventListener(
      google.ima.AdEvent.Type.LOADED,
      onAdLoaded);
}

...

function onAdLoaded(adEvent) {
  var ad = adEvent.getAd();
  if (!ad.isLinear()) {
    videoElement.play();
  }
}

هذا كل شيء! أنت الآن تطلب الإعلانات وتعرضها باستخدام حزمة تطوير البرامج لإعلانات الوسائط التفاعلية. لمزيد من المعلومات المتقدمة لحزمة تطوير البرامج (SDK)، فيمكنك الاطلاع على الأدلة الأخرى أو النماذج على GitHub.