إنشاء فئة "مدير الإعلانات"

ملاحظة: قبل المتابعة باستخدام هذا الدليل، يجب إكمال الخطوات الواردة في مقالة إعداد فئة اللاعب.

في ads_manager.js، حدِّد فئة غلاف لـ StreamManager في "حزمة تطوير البرامج للإعلانات التفاعلية" (IMA SDK) التي تنفّذ طلبات البث، وتحصل على بيان حزمة الإعلانات، وتستمع إلى أحداث بث IMA، وتمرِّر أحداث emsg إلى حزمة IMA SDK.

في ads_manager.js، يضبط تطبيق IMA HbbTV النموذجي الطرق التالية:

• requestStream()
• onStreamEvent()
• onEmsgEvent()
• loadAdPodManifest()

تهيئة "مدير الإعلانات"

ابدأ بتفعيل فئة "مدير الإعلانات" وضبط أدوات معالجة أحداث بث IMA. في هذا الطلب، اضبط معالج أحداث emsg باستخدام الطريقة VideoPlayer.setEmsgEventHandler().

نقطة أساسية: لا تتيح حزمة تطوير البرامج للإعلانات التفاعلية واجهة مستخدم الإعلان على HbbTV. لا تمرِّر المَعلمة adUiElement في الدالة الإنشائية StreamManager. قد يؤدي تمرير adUiElement إلى عرض "مدير إعلانات Google" إعلانات غير متوافقة.

/**
 * Wraps IMA SDK ad stream manager.
 * @param {!VideoPlayer} videoPlayer Reference an instance of the wrapper from
 * video_player.js.
 */
var AdManager = function(videoPlayer) {
  this.streamData = null;
  this.videoPlayer = videoPlayer;
  // Ad UI is not supported for HBBTV, so no 'adUiElement' is passed in the
  // StreamManager constructor.
  this.streamManager = new google.ima.dai.api.StreamManager(
      this.videoPlayer.videoElement);
  this.streamManager.addEventListener(
      [
        google.ima.dai.api.StreamEvent.Type.STREAM_INITIALIZED,
        google.ima.dai.api.StreamEvent.Type.ERROR,
        google.ima.dai.api.StreamEvent.Type.CLICK,
        google.ima.dai.api.StreamEvent.Type.STARTED,
        google.ima.dai.api.StreamEvent.Type.FIRST_QUARTILE,
        google.ima.dai.api.StreamEvent.Type.MIDPOINT,
        google.ima.dai.api.StreamEvent.Type.THIRD_QUARTILE,
        google.ima.dai.api.StreamEvent.Type.COMPLETE,
        google.ima.dai.api.StreamEvent.Type.AD_BREAK_STARTED,
        google.ima.dai.api.StreamEvent.Type.AD_BREAK_ENDED,
        google.ima.dai.api.StreamEvent.Type.AD_PROGRESS,
        google.ima.dai.api.StreamEvent.Type.PAUSED,
        google.ima.dai.api.StreamEvent.Type.RESUMED
      ],
      this.onStreamEvent.bind(this),
      false);

  this.videoPlayer.setEmsgEventHandler(this.onEmsgEvent, this);
};
ads_manager.js

إرسال طلب لعرض بث مجموعة إعلانات متسلسلة

أنشئ طريقة AdManager.requestStream() لإنشاء عنصر PodStreamRequest باستخدام معرّف شبكة "إدارة إعلانات Google" ومفتاح أصل البث المباشر المخصّص. اختبِر تطبيق HbbTV باستخدام عيّنة من بث عرض الإعلانات المتجاوبة مع بيئة العرض الديناميكي (DASH) من IMA مع معلَمات البث التالية:

• معرِّف الشبكة: '21775744923'
• مفتاح العنصر المخصّص: 'hbbtv-dash'

/**
 * Makes a pod stream request.
 * @param {string} networkCode The network code.
 * @param {string} customAssetKey The custom asset key.
 */
AdManager.prototype.requestStream = function (networkCode, customAssetKey) {
  var streamRequest = new google.ima.dai.api.PodStreamRequest();
  var secretKey = getStreamSecretKeys();

  streamRequest.networkCode = networkCode;
  streamRequest.customAssetKey = customAssetKey;
  streamRequest.format = 'dash';

  if (secretKey.STREAM_CREATE_SECRET) {
    var expirationTime = Math.trunc(new Date().getTime() / 1000) + 3600;
    var params = {
      custom_asset_key: customAssetKey,
      exp: expirationTime,
      network_code: networkCode
    };
    streamRequest.authToken =
        this.generateAuthToken(params, secretKey.STREAM_CREATE_SECRET);
    debugView.log('AdsManager: make Auth-PodStreamRequest');
  } else {
    debugView.log('AdsManager: make PodStreamRequest without auth');
  }

  this.streamManager.requestStream(streamRequest);
};
ads_manager.js

الاستماع إلى أحداث بث الإعلانات

أنشئ طريقة AdManager.onStreamEvent() للتعامل مع استجابة تطبيقك لأحداث بث IMA، STREAM_INITIALIZED وAD_BREAK_STARTED وAD_BREAK_ENDED.

/**
 * Handles IMA playback events.
 * @param {!Event} event The event object.
 */
AdManager.prototype.onStreamEvent = function(event) {
  switch (event.type) {
    // Once the stream response data is received, generate pod manifest url
    // for the video stream.
    case google.ima.dai.api.StreamEvent.Type.STREAM_INITIALIZED:
      debugView.log('IMA SDK: stream initialized');
      this.streamData = event.getStreamData();
      break;
    case google.ima.dai.api.StreamEvent.Type.ERROR:
      break;
    // Hide video controls while ad is playing.
    case google.ima.dai.api.StreamEvent.Type.AD_BREAK_STARTED:
      debugView.log('IMA SDK: ad break started');
      this.adPlaying = true;
      this.adBreakStarted = true;
      break;
    // Show video controls when ad ends.
    case google.ima.dai.api.StreamEvent.Type.AD_BREAK_ENDED:
      debugView.log('IMA SDK: ad break ended');
      this.adPlaying = false;
      this.adBreakStarted = false;
      break;
    // Update ad countdown timers.
    case google.ima.dai.api.StreamEvent.Type.AD_PROGRESS:
      break;
    default:
      debugView.log('IMA SDK: ' + event.type);
      break;
  }
};
ads_manager.js

التعامل مع البيانات الوصفية لتدفق الإعلانات

لتمرير معلومات حدث emsg إلى IMA، أنشئ طريقة AdManager.onEmsgEvent() باستخدام الطريقة StreamManager.processMetadata(). تستدعي فئة مشغّل الفيديو هذه الطريقة باستخدام الطريقة VideoPlayer.setEmsgEventHandler().

/**
 * Callback on Emsg event.
 * Instructs IMA SDK to fire back VAST events accordingly.
 * @param {!Event} event The event object.
 */
AdManager.prototype.onEmsgEvent = function(event) {
  var data = event.event.messageData;
  var pts = event.event.calculatedPresentationTime;
  if ((data instanceof Uint8Array) && data.byteLength > 0) {
    this.streamManager.processMetadata('ID3', data, pts);
  }
};
ads_manager.js

تحميل بيان مجموعة الإعلانات المتسلسلة

أنشِئ طريقة AdManager.loadAdPodManifest() لتحميل بيان مجموعة الإعلانات المتسلسلة مسبقًا باستخدام مشغّل الفيديو. أنشئ عنوان URL لملف بيان مصادَق عليه باستخدام البنية الواردة في الطريقة: ملف بيان مجموعة DASH.

/**
 * Creates DAI pod url and instructs video player to load manifest.
 * @param {string} networkCode The network code.
 * @param {string} customAssetKey The custom asset key.
 * @param {number} podDuration The duration of the ad pod.
 */
AdManager.prototype.loadAdPodManifest = function (networkCode, customAssetKey, podDuration) {
  if (!this.streamData) {
    debugView.log('AdsManager: No stream data available.');
    return;
  }

  var adBreakId = this.getAdBreakId();
  var expirationTime = Math.trunc(new Date().getTime() / 1000) + 3600;

  var params = {
    ad_break_id: adBreakId,
    custom_asset_key: customAssetKey,
    exp: expirationTime,
    network_code: networkCode,
    pd: podDuration
  };

  var secretKey = getStreamSecretKeys();
  var token = this.generateAuthToken(params, secretKey.MANIFEST_SECRET);
  var encodedToken = encodeURIComponent(token);

  var manifestUrl = 'https://dai.google.com/linear/pods/v1/dash/network/' +
    networkCode + '/custom_asset/' + customAssetKey + '/stream/' +
    this.streamData.streamId + '/ad_break_id/' + adBreakId +
    '/manifest.mpd?pd=' + podDuration + '&auth-token=' + encodedToken;

  this.videoPlayer.preload(manifestUrl);
};
ads_manager.js

يستخدم تطبيق HbbTV النموذجي قيمة adBreakId فريدة يتم إنشاؤها عشوائيًا. في التطبيقات المتاحة للإنتاج، تكون قيمة adBreakId عبارة عن سلسلة أبجدية رقمية، مثل ab-001، تزداد بمقدار واحد لكل فاصل إعلاني. تأكَّد من أنّ قيمة adBreakId هي نفسها لكل مشاهدي الفاصل الإعلاني. للحصول على قيمة adBreakId، ننصحك باستخدام DAI Ad Break API. في بيئة التشغيل الفعلي، أدرِج القيمة adBreakId والقيمة podDuration في حدث بث HbbTV AD_BREAK_ANNOUNCE.

ملاحظة مهمة: يجب مصادقة طلب بيان مجموعة إعلانات متسلسلة. بدون مصادقة، لا يمكن لخدمة "إدارة إعلانات Google" عرض الإعلانات في ملف بيان مجموعة الإعلانات المتسلسلة. للمصادقة على الطلب، يمكنك إما جدولة فاصلك الإعلاني باستخدام DAI Ad Break API أو تضمين auth-token مَعلمة طلب البحث في عنوان URL لطلب بيان وصف مجموعة الإعلانات المتسلسلة.

بعد ذلك، أنشئ فئة التطبيق الرئيسية لتطبيق HbbTV التي تتفاعل مع بث HbbTV.