Create the ads manager class

  • The IMA SDK StreamManager wrapper class in ads_manager.js handles stream requests, ad pod manifests, IMA stream events, and emsg events for HbbTV applications.

  • The sample app includes methods like requestStream(), onStreamEvent(), onEmsgEvent(), and loadAdPodManifest().

  • Ad UI is not supported on HbbTV, so avoid passing the adUiElement parameter in the StreamManager constructor to prevent serving incompatible ads.

  • The requestStream() method uses the network code and custom asset key to create a PodStreamRequest.

  • The onStreamEvent() method processes IMA stream events, such as STREAM_INITIALIZED and ad break events.

  • The onEmsgEvent() method passes emsg event data to the IMA SDK using streamManager.processMetadata().

  • The loadAdPodManifest() method constructs and preloads the ad pod manifest URL.

  • Production apps should use a consistently incrementing integer for podId and consider using the Early ad break notifications (EABN) API.

In ads_manager.js, define a wrapper class for the IMA SDK StreamManager that makes stream requests, gets the ad pod manifest, listens to IMA stream events, and passes emsg events to the IMA SDK.

In ads_manager.js, the IMA HbbTV sample app sets up the following methods:

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

Initialize ads manager

Initialize the ads manager class and set listeners for the IMA stream events. In this call, set the emsg event handler with the VideoPlayer.setEmsgEventHandler() method.

/**
 * 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

Make a request for an ad pod stream

Create the AdManager.requestStream() method to create a PodStreamRequest object using your Google Ad Manager network code and the stream's custom asset key. Test your HbbTV app using the IMA sample DASH pod serving stream with the following stream parameters:

  • Network code: '21775744923'
  • Custom asset key: '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();
  streamRequest.networkCode = networkCode;
  streamRequest.customAssetKey = customAssetKey;
  streamRequest.format = 'dash';
  debugView.log('AdsManager: make PodStreamRequest');
  this.streamManager.requestStream(streamRequest);
};
ads_manager.js

Listen to ad stream events

Create the AdManager.onStreamEvent() method to handle your app's response to the IMA stream events, STREAM_INITIALIZED, AD_BREAK_STARTED, and 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

Handle ad stream metadata

To pass the emsg event info to IMA, create the AdManager.onEmsgEvent() method using the StreamManager.processMetadata() method. The video player class calls this method with the VideoPlayer.setEmsgEventHandler() method.

/**
 * 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

Load the ad pod manifest

Create the AdManager.loadAdPodManifest() method to preload the ad pod manifest with the video player. Construct the manifest URL using the structure in Method: DASH pod manifest.

/**
 * 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('IMA SDK: No DAI pod session registered.');
    return;
  }

  var MANIFEST_BASE_URL = 'https://dai.google.com/linear/pods/v1/dash/network/';
  // Method: DASH pod manifest reference docs:
  // https://developers.google.com/ad-manager/dynamic-ad-insertion/api/pod-serving/reference/live#method_dash_pod_manifest
  var manifestUrl = MANIFEST_BASE_URL + networkCode + '/custom_asset/' +
    customAssetKey + '/stream/' + this.streamData.streamId + '/pod/' +
    this.getPodId() + '/manifest.mpd?pd=' + podDuration;
  this.videoPlayer.preload(manifestUrl);
};
ads_manager.js

The HbbTV sample app uses a randomly generated unique podId. In production apps, the podId is an integer that starts at one, and increments by one for each ad break. Verify the podId is the same value for all viewers of the ad break. To get a podId, we recommend using the Early ad break notifications (EABN) API. In a production environment, include the podId and podDuration in the HbbTV stream event AD_BREAK_ANNOUNCE.

Next, create the main application class for your HbbTV app that interacts with the HbbTV broadcast.

Previous
Set up the player class
Next
Build the application class