إعداد قوائم تشغيل إعلانية تلقائيًا

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

• عند إنشاء AdsManager، يتمّ تمرير contentPlayback كائن باستخدام طلب getAdsManager. يجب أن يحتوي هذا العنصر على سمة currentTime تعرض موضع شريط التمرير الحالي في الفيديو. إذا كنت تستخدم عنصر HTML5‏ video لعرض المحتوى، يمكنك ببساطة تمرير هذا العنصر إلى حزمة تطوير البرامج (SDK). يُستخدَم هذا العنصر لتتبُّع مستوى تقدّم تشغيل المحتوى حتى تتم إدراج الفواصل الإعلانية تلقائيًا في الأوقات المحدّدة في "مدير إعلانات Google". عليك أيضًا إبلاغ حزمة SDK بأنّك تريدها أن تتعامل مع حالة المحتوى نيابةً عنك.

  var adsRenderingSettings = new google.ima.AdsRenderingSettings();
  adsRenderingSettings.restoreCustomPlaybackStateOnAdBreakComplete = true;
  adsManager = adsManagerLoadedEvent.getAdsManager(
      videoContent, adsRenderingSettings); // See API reference for contentPlayback.

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

  var videoContent = document.getElementById('contentElement');
  var contentEndedListener = function() {adsLoader.contentComplete();};
  
  videoContent.addEventListener('ended', contentEndedListener);
  
  function onContentPauseRequested() {
    contentElement.removeEventListener('ended', contentEndedListener);
    ...
  }
  
  function onContentResumeRequested() {
    contentElement.addEventListener('ended', contentEndedListener);
    ...
  }

• يتم استخدام الحدثَين CONTENT_PAUSE_REQUESTED وCONTENT_RESUME_REQUESTED لإيقاف المحتوى مؤقتًا واستئنافه عند تشغيل الفواصل الإعلانية.
• إذا كان مشغّل الفيديو يتيح ميزة "السحب للتقديم أو الإيقاف"، وتغيّرت سمة الوقت الحالي لمشغّل الفيديو أثناء سحب المستخدم للمحتوى، لا يمكن لحزمة SDK التمييز بين تقدّم المحتوى بشكل طبيعي وتقديم المستخدم للمحتوى. يجب استخدام عنصر contentPlayback مخصّص كمَعلمة لـ getAdsManager. للحصول على مثال على حالة الاستخدام هذه، يمكنك الاطّلاع على المشاكل المتعلّقة بالتقديم/الترجيع.

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

إيقاف التشغيل التلقائي للفواصل الإعلانية

في بعض الحالات، قد تحتاج إلى منع حزمة SDK من تشغيل الفواصل الإعلانية إلى أن تتمكّن من عرضها. في هذا السيناريو، يمكنك إيقاف التشغيل التلقائي للفواصل الإعلانية بدلاً من إعلام حزمة SDK عندما تكون مستعدًا لتشغيل فاصل إعلاني. باستخدام هذه الإعدادات، بعد أن تحمّل حزمة SDK فاصل إعلاني، يتم بدء حدث AD_BREAK_READY. عندما يكون المشغّل جاهزًا لبدء عرض الفاصل الإعلاني، يمكنك استدعاء adsManager.start():

function requestAds() {}
  ...
  adsLoader.getSettings().setAutoPlayAdBreaks(false);
  ...
}

function onAdsManagerLoaded() {
  ...
  // For non-auto ad breaks, listen for ad break ready
  adsManager.addEventListener(
      google.ima.AdEvent.Type.AD_BREAK_READY,
      adBreakReadyHandler);
  ...
}

function adBreakReadyHandler() {
  // Once we're ready to play ads. To skip this ad break, simply return
  // from this handler without calling adsManager.start().
  adsManager.start();
}

جرّبه الآن

اطّلِع على الرمز البرمجي التالي لمعرفة طريقة التنفيذ الصحيحة.

مشكلة التقديم أو الإيقاف

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

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

باستخدام هذا الحل، يمكنك تخطّي الإعلان أثناء التشغيل الذي تبلغ مدته 0:10 ثانية بشكل صحيح وتشغيل الإعلان أثناء التشغيل الذي تبلغ مدته 0:20 ثانية فقط. ويتم ذلك باستخدام أداة تتبُّع مخصّصة لشريط التشغيل في مقتطف الرمز البرمجي التالي. يحتوي هذا الرمز على تعديلات (معروضة بخط عريض) على ads.js في ملف HTML5 المتقدم، وهو متاح في صفحة التنزيل.

var Ads = function(application, videoPlayer) {
  ...
  this.currentTime = 0;
  setInterval(this.updateCurrentTime, 1000);
};

Ads.prototype.updateCurrentTime = function() {
  if (!this.videoPlayer_.contentPlayer.seeking) {
    this.currentTime = this.videoPlayer_.contentPlayer.currentTime;
  }
};

Ads.prototype.onAdsManagerLoaded_ = function(adsManagerLoadedEvent) {
  this.application_.log('Ads loaded.');
  this.adsManager_ = adsManagerLoadedEvent.getAdsManager(this);
  this.processAdsManager_(this.adsManager_);
};

المشاكل المعروفة في متصفّح Safari للأجهزة الجوّالة

من المفترض أن تعمل هذه الطريقة على جميع المنصات باستثناء متصفّح Safari للأجهزة الجوّالة. على Safari المتوافق مع الأجهزة الجوّالة، لا يتم تنفيذ سمة التقديم/الترجيع لعلامة الفيديو بشكلٍ صحيح (تُعرِض دائماً قيمة خاطئة). لحلّ هذه المشكلة، عليك التحقّق مما إذا كان المستخدم يتخطّى الفيديو. في ما يلي رمز نموذجي لهذه الطريقة. تجدر الإشارة إلى أنّ الخطوط المميّزة بالخطّ العريض هي تعديلات على الرمز الحالي.

var Ads = function(application, videoPlayer) {
  ...
  this.currentTime = 0;
  setInterval(this.updateCurrentTime, 1000);
  this.seeking = false;
  this.seekCheckInterval = 1000;
  // You may need to adjust this value, depending on your platform
  this.seekThreshold = 100;
  this.previousTime = 0;
  setInterval(
      Application.bind(this, this.checkForSeeking),
      this.seekCheckInterval);
};

Ads.prototype.updateCurrentTime = function() {
  if (!this.seeking) {
    this.currentTime = this.videoPlayer_.contentPlayer.currentTime;
  }
};

Ads.prototype.checkForSeeking = function() {
  var currentTime = this.videoPlayer_.contentPlayer.currentTime;
  // How much time has passed since you last ran this method, in milliseconds
  var diff = (currentTime - this.previousTime) * 1000;
  // If that difference is greater than the time since you last ran this method,
  // plus the threshold, the user was seeking
  if (Math.abs(diff)  > this.interval + this.threshold) {
    this.seeking = true;
  } else {
    this.seeking = false;
  }
  // Grab the current video time again to make up for time spent in this method
  previousTime = this.videoPlayer_.contentPlayer.currentTime;
};

Ads.prototype.onAdsManagerLoaded_ = function(adsManagerLoadedEvent) {
  this.application_.log('Ads loaded.');
  this.adsManager_ = adsManagerLoadedEvent.getAdsManager(this);
  this.processAdsManager_(this.adsManager_);
};

بعد إجراء هذه التغييرات، تستخدم حزمة SDK الآن سمة currentTime لعنصر Ads لتحديد وقت تشغيل الفواصل الإعلانية، وليس سمة currentTime لمشغّل فيديو المحتوى.