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

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

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

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

بعد ذلك، أضِف إطار عمل 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 هذا أو أي عنوان URL لعلامة إعلان باستخدام أداة فحص استجابة VAST.

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

الاستماع إلى أحداث الأخطاء والإعلانات المحمَّلة والردّ عليها باستخدام 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&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 = 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. يمكنك معالجة هذا الحدث من خلال بدء إيقاف مؤقت في مشغّل الفيديو الأساسي. وبالمثل، عند اكتمال عرض إعلان، يُطلق AdsManager الحدث CONTENT_RESUME_REQUESTED. يمكنك معالجة هذا الحدث من خلال إعادة تشغيل محتوى الفيديو الأساسي. 

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