البدء

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

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

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

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

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

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

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

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

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

ولأنّ حزمة تطوير البرامج لإعلانات الوسائط التفاعلية تحمِّل التبعيات عبر البروتوكول نفسه المستخدَم في الصفحة التي تم تحميلها منه، ستحتاج إلى استخدام خادم ويب لاختبار تطبيقك. إنّ أبسط طريقة لبدء خادم تطوير محلي هي استخدام خادم Python المدمج.

  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.