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

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

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

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

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

  • AdDisplayContainer: عنصر حاوٍ يحدّد المكان الذي تعرض فيه IMA عناصر واجهة مستخدم الإعلان وتقيس إمكانية العرض، بما في ذلك العرض النشط و Open Measurement.
  • 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.

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

أولاً، عدِّل ملف index.html لإنشاء عنصر فيديو بسيط بتنسيق HTML5 مضمّن في عنصر تضمين، وزر لتشغيل الفيديو. يستورد المثال التالي حزمة تطوير البرامج لإعلانات الوسائط التفاعلية ويعدّ عنصر الحاوية AdDisplayContainer. لمزيد من التفاصيل، يُرجى الاطّلاع على الخطوتَين استيراد حزمة تطوير البرامج لإعلانات الوسائط التفاعلية و إنشاء حاوية الإعلان على التوالي. 

<html>
  <head>
    <title>IMA HTML5 Simple Demo</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>
      <div id="adContainer"></div>
    </div>
    <button id="playButton">Play</button>
    <script src="//imasdk.googleapis.com/js/sdkloader/ima3.js"></script>
    <script src="ads.js"></script>
  </body>
</html>

index.html
 
#mainContainer {
  position: relative;
  width: 640px;
  height: 360px;
}

#content {
  position: absolute;
  top: 0;
  left: 0;
  width: 640px;
  height: 360px;
}

#contentElement {
  width: 640px;
  height: 360px;
  overflow: hidden;
}

#playButton {
  margin-top:10px;
  vertical-align: top;
  width: 350px;
  height: 60px;
  padding: 0;
  font-size: 22px;
  color: white;
  text-align: center;
  text-shadow: 0 1px 2px rgba(0, 0, 0, 0.25);
  background: #2c3e50;
  border: 0;
  border-bottom: 2px solid #22303f;
  cursor: pointer;
  -webkit-box-shadow: inset 0 -2px #22303f;
  box-shadow: inset 0 -2px #22303f;
}
style.css
 
let adsManager;
let adsLoader;
let adDisplayContainer;
let isAdPlaying;
let isContentFinished;
let playButton;
let videoContent;
let adContainer;

// On window load, attach an event to the play button click
// that triggers playback of the video element.
window.addEventListener('load', function(event) {
  videoContent = document.getElementById('contentElement');
  adContainer = document.getElementById('adContainer');
  adContainer.addEventListener('click', adContainerClick);
  playButton = document.getElementById('playButton');
  playButton.addEventListener('click', playAds);
  setUpIMA();
});
ads.js

أضِف العلامات اللازمة لتحميل الملفَين style.css وads.js. بعد ذلك، عدِّل ملف styles.css لجعل مشغّل الفيديو متجاوبًا مع الأجهزة الجوّالة. أخيرًا، في ads.js، عرِّف المتغيّرات وشغِّل الفيديو عند النقر على زر التشغيل.

يُرجى العِلم أنّ مقتطف الرمز ads.js يتضمّن طلبًا إلى setUpIMA()، والذي تم تحديده في القسم تهيئة AdsLoader وإجراء طلب إعلانات .

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

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

<script src="//imasdk.googleapis.com/js/sdkloader/ima3.js"></script>
index.html

4. إنشاء حاوية الإعلان

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

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

<div id="adContainer"></div>
index.html
 
#adContainer {
  position: absolute;
  top: 0;
  left: 0;
  width: 640px;
  height: 360px;
}
style.css
 
/**
 * Sets the 'adContainer' div as the IMA ad display container.
 */
function createAdDisplayContainer() {
  adDisplayContainer = new google.ima.AdDisplayContainer(
      document.getElementById('adContainer'), videoContent);
}
ads.js

5- تهيئة AdsLoader وتقديم طلب إعلان

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

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

الاستماع إلى الأحداث التي تم تحميلها والأحداث التي تتضمّن أخطاءً والردّ عليها باستخدام AdsLoader.addEventListener استمِع إلى الأحداث التالية:

  • ADS_MANAGER_LOADED
  • AD_ERROR

لإنشاء أدوات معالجة الأحداث onAdsManagerLoaded() وonAdError()، راجِع المثال التالي: 

/**
 * Sets up IMA ad display container, ads loader, and makes an ad request.
 */
function setUpIMA() {
  // Create the ad display container.
  createAdDisplayContainer();
  // Create ads loader.
  adsLoader = new google.ima.AdsLoader(adDisplayContainer);
  // Listen and respond to ads loaded and error events.
  adsLoader.addEventListener(
      google.ima.AdsManagerLoadedEvent.Type.ADS_MANAGER_LOADED,
      onAdsManagerLoaded, false);
  adsLoader.addEventListener(
      google.ima.AdErrorEvent.Type.AD_ERROR, onAdError, false);

  // An event listener to tell the SDK that our content video
  // is completed so the SDK can play any post-roll ads.
  const contentEndedListener = function() {
    // An ad might have been playing in the content element, in which case the
    // content has not actually ended.
    if (isAdPlaying) return;
    isContentFinished = true;
    adsLoader.contentComplete();
  };
  videoContent.onended = contentEndedListener;

  // Request video ads.
  const 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&correlator=';

  // Specify the linear and nonlinear slot sizes. This helps the SDK to
  // select the correct creative if multiple are returned.
  adsRequest.linearAdSlotWidth = 640;
  adsRequest.linearAdSlotHeight = 400;

  adsRequest.nonLinearAdSlotWidth = 640;
  adsRequest.nonLinearAdSlotHeight = 150;

  adsLoader.requestAds(adsRequest);
}
ads.js

6. الردّ على أحداث AdsLoader

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

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

/**
 * Handles the ad manager loading and sets ad event listeners.
 * @param {!google.ima.AdsManagerLoadedEvent} adsManagerLoadedEvent
 */
function onAdsManagerLoaded(adsManagerLoadedEvent) {
  // Get the ads manager.
  const adsRenderingSettings = new google.ima.AdsRenderingSettings();
  adsRenderingSettings.restoreCustomPlaybackStateOnAdBreakComplete = true;
  // videoContent should be set to the content video element.
  adsManager =
      adsManagerLoadedEvent.getAdsManager(videoContent, adsRenderingSettings);

  // Add listeners to the required events.
  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);
}

/**
 * Handles ad errors.
 * @param {!google.ima.AdErrorEvent} adErrorEvent
 */
function onAdError(adErrorEvent) {
  // Handle the error logging.
  console.log(adErrorEvent.getError());
  adsManager.destroy();
}
ads.js

لمزيد من التفاصيل حول أدوات معالجة الأحداث التي تم ضبطها في الدالة onAdsManagerLoaded()، يُرجى الاطّلاع على الأقسام الفرعية التالية:

التعامل مع أخطاء AdsManager

يمكن أن يعمل معالج الأخطاء الذي تم إنشاؤه لـ AdsLoader كمعالج أخطاء لـ AdsManager أيضًا. اطّلِع على معالج الأحداث الذي يعيد استخدام الدالة onAdError(). 

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

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

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

adsManager.addEventListener(
    google.ima.AdEvent.Type.CONTENT_PAUSE_REQUESTED, onContentPauseRequested);
adsManager.addEventListener(
    google.ima.AdEvent.Type.CONTENT_RESUME_REQUESTED,
    onContentResumeRequested);
ads.js

للاطّلاع على تعريفات الدالتَين onContentPauseRequested() وonContentResumeRequested()، راجِع المثال التالي: 

/**
 * Pauses video content and sets up ad UI.
 */
function onContentPauseRequested() {
  isAdPlaying = true;
  videoContent.pause();
  // This function is where you should setup UI for showing ads (for example,
  // display ad timer countdown, disable seeking and more.)
  // setupUIForAds();
}

/**
 * Resumes video content and removes ad UI.
 */
function onContentResumeRequested() {
  isAdPlaying = false;
  if (!isContentFinished) {
    videoContent.play();
  }
  // This function is where you should ensure that your UI is ready
  // to play content. It is the responsibility of the Publisher to
  // implement this function when necessary.
  // setupUIForContent();
}
ads.js

التعامل مع تشغيل المحتوى أثناء عرض الإعلانات غير الخطية

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

adsManager.addEventListener(google.ima.AdEvent.Type.LOADED, onAdLoaded);
ads.js

لإتاحة الإعلانات غير الخطية، استمع إلى AdsManager لإصدار الحدث LOADED. تحقَّق مما إذا كان الإعلان خطيًا، وإذا لم يكن كذلك، استأنِف التشغيل على عنصر الفيديو.

للاطّلاع على تعريف الدالة onAdLoaded()، راجِع المثال التالي. 

/**
 * Handles ad loaded event to support non-linear ads. Continues content playback
 * if the ad is not linear.
 * @param {!google.ima.AdEvent} adEvent
 */
function onAdLoaded(adEvent) {
  let ad = adEvent.getAd();
  if (!ad.isLinear()) {
    videoContent.play();
  }
}
ads.js

7. تفعيل ميزة "النقر للإيقاف مؤقتًا" على الأجهزة الجوّالة

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

لتنفيذ ميزة "النقر للإيقاف المؤقت"، أضِف دالة معالج النقر adContainerClick() التي تحمل الاسم في أداة معالجة أحداث تحميل النافذة. 

/**
 * Handles clicks on the ad container to support expected play and pause
 * behavior on mobile devices.
 * @param {!Event} event
 */
function adContainerClick(event) {
  console.log("ad container clicked");
  if(videoContent.paused) {
    videoContent.play();
  } else {
    videoContent.pause();
  }
}
ads.js

8. بدء AdsManager

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

/**
 * Loads the video content and initializes IMA ad playback.
 */
function playAds() {
  // Initialize the container. Must be done through a user action on mobile
  // devices.
  videoContent.load();
  adDisplayContainer.initialize();

  try {
    // Initialize the ads manager. This call starts ad playback for VMAP ads.
    adsManager.init(640, 360);
    // Call play to start showing the ad. Single video and overlay ads will
    // start at this time; the call will be ignored for VMAP ads.
    adsManager.start();
  } catch (adError) {
    // An error may be thrown if there was a problem with the VAST response.
    videoContent.play();
  }
}
ads.js

9- إتاحة تغيير حجم المشغّل

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

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

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