تمت ترجمة هذه الصفحة بواسطة Cloud Translation API‏.

البدء

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

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

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

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

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

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

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

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

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

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

باستخدام سطر أوامر، من الدليل الذي يحتوي على ملف index.html، يتم تشغيل:
```
  python -m http.server 8000
```
ملاحظة: http.server متاح فقط في Python 3.x.
في متصفّح الويب، انتقِل إلى http://localhost:8000/.

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

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");
}

وفي معظم المتصفّحات، تستخدم حزمة تطوير البرامج لإعلانات الوسائط التفاعلية عنصر حاوية إعلان مخصّصًا لعرض كلٍّ من الإعلانات وعناصر واجهة المستخدم ذات الصلة بالإعلانات. يجب تغيير حجم هذه الحاوية لتثبيت عنصر الفيديو من أعلى يمين الصفحة. يتم ضبط ارتفاع الإعلانات التي يتم وضعها في هذه الحاوية وعرضها من خلال الكائن 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. لإتاحة المتصفّحات المتوافقة مع الأجهزة الجوّالة بالكامل، يجب أن يتم ذلك من خلال تفاعل المستخدم.

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

البدء

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

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

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

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

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

4- إرفاق معالجات الصفحة أو مشغّل الفيديو

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

6- إعداد AdsLoader وتقديم طلب إعلانات

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

8- بدء إدارة الإعلانات

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

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

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

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

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

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