البدء

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

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

نظرة عامة على IMA من جهة العميل

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

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

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

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

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

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

بما أنّ حزمة تطوير البرامج (SDK) لـ IMA تحمّل التبعيات من خلال البروتوكول نفسه المستخدَم في الصفحة التي يتم تحميلها منها، عليك استخدام خادم ويب لاختبار تطبيقك. إنّ أبسط طريقة لبدء خادم تطوير محلي هي استخدام الخادم المضمّن في Python.

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

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

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

بعد ذلك، أضِف إطار عمل IMA باستخدام علامة نص برمجي في 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، أضِف عناصر معالجة أحداث تؤدي إلى تنفيذ الإجراءين التاليين:

  • عند انتهاء تحميل الصفحة، عليك إعداد حزمة تطوير برامج IMA.
  • عند النقر على زر تشغيل الفيديو، يتم تحميل الإعلانات (ما لم تكن هناك إعلانات مُحمَّلة).
  • عند تغيير حجم نافذة المتصفّح، عدِّل سمات عنصر الفيديو و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 هذا أو أي عنوان URL لعلامة إعلان باستخدام أداة فحص استجابة VAST.

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

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 SDK) أيّ نقرات لا تتم معالجتها من خلال 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.