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

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

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

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

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

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

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

ملاحظة مهمة: لا تتوافق حزمة IMA SDK مع واجهة مستخدم الإعلانات على 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.