قواعد الإعلانات

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

  • عند إنشاء AdsManager، يتم تمرير العنصر contentPlayback من خلال طلب getAdsManager. ويجب أن يحتوي هذا الكائن على السمة currentTime التي تعرض موضع رأس التشغيل الحالي للفيديو. إذا كنت تستخدم عنصر video في HTML5 لعرض المحتوى الخاص بك، ما عليك سوى تمرير هذا العنصر إلى حزمة تطوير البرامج (SDK). يُستخدَم هذا الكائن لتتبُّع تقدّم تشغيل المحتوى، بحيث يتم إدراج الفواصل الإعلانية تلقائيًا في الأوقات المحدّدة في "مدير الإعلانات". عليك أيضًا إعلام حزمة تطوير البرامج (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 على الأجهزة الجوّالة، لم يتم تنفيذ خاصية التقديم/الترجيع لعلامة الفيديو بشكل صحيح (لأنّها تعرض القيمة "false" دائمًا). للتحايل على ذلك، تحتاج إلى إجراء فحصك لمعرفة ما إذا كان المستخدم يسعى إلى الوصول إلى الفيديو. فيما يلي نموذج التعليمات البرمجية لهذه الطريقة. مرة أخرى، الأسطر المميزة بالخط العريض أدناه هي تعديلات على التعليمة البرمجية الحالية.

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) الآن السمة CurrentsTime للعنصر Ads لتحديد وقت تشغيل الفواصل الإعلانية، وليس السمة currentTime في مشغّل الفيديو للمحتوى.