Skip to main content

Server Side Ad Insertion using Google IMA

GoogleIMA DAI​

Setup​

GoogleIMA DAI SDK must be loaded.

// Add the script tag for GoogleIMA DAI SDK
<script src="//imasdk.googleapis.com/js/sdkloader/ima3_dai.js"></script>

Specifications​

  1. Server-side ads insertion (SSAI) a.k.a Dynamic Ad Insertion (DAI) provides a combined video stream of ads and content (ads stitching), resulting in a seamless, broadcast-like viewing experience. QP Google IMA ads player supports:
  2. Various ad formats, including standard linear and non-linear in-stream ads, interactive in-stream ads, and skippable ads.
  3. Multiple ad placements: It can deliver pre-roll, mid-roll, and post-roll ads.
  4. Can make ad requests to Google Ad Manager, the Google AdSense network, or any VAST-compliant ad server.
  5. Replacement for all ad tag parameters used for the upcoming ad requests in a Live IMA DAI Streams.

Usage​

This first step is the creation of a DAI Stream Manager instance that will be used to retrieve the playback URL as well as a reference to the internal Google IMA DAI stream manager.

Create a DAI Stream Manager​

To create a DAI Stream Manager a DaiStreamManagerBuilder is provided. This builder will accept several inputs including the content source id and video id to request a VOD stream or an asset key to request a live stream.

Create a builder instance.​

const builder: DaiStreamManagerBuilder =
  flAdsIma.createDaiStreamManagerBuilder();

Builder Parameters

NameTypeOptionalDescription
imaAnyfalseA reference to the google.ima library.
contentContainerElementElementfalseThe element to display the ads in. The element must be inserted into the DOM before initializing the Ad player.
contentVideoElementHTMLVideoElementfalseSpecifies the alternative video ad playback element. We recommend always passing in your content video player.
localizationStringtrueThe language of text within UI elements.
adTagParametersMap<String, String>trueAd tag parameters used for upcoming ad requests for a live stream.
contentSourceStringtrueRequired for VOD stream. Unique identifier for the publisher content, from a CMS. Required for on-demand streams.
videoStringtrueRequired for VOD stream. Identifier for the video content source. Required for on-demand streams.
assetStringtrueRequired for live stream. This is used to determine which stream should be played. Required for live streams.
mediaTypeMediaTypefalseThe content media type.
apiTokenStringtrueThe stream request API key. It is used to verify the applications that are attempting to access the content.
loggerLoggertrueApplication developers can configure a logger with their own tag information and logger levels.

Request for VOD Stream​

Provide the necessary data to request for a VOD stream.

builder
  .ima(google.ima)
  .contentContainerElement(videoWrapper)
  .contentVideoElement(videoElement)
  .contentSource('2548831')
  .video('tears-of-steel')
  .mediaType(MediaType.HLS);

Request for Live Stream​

Provide the necessary data to request for a live stream.

builder
  .ima(google.ima)
  .contentContainerElement(adWrapper)
  .contentVideoElement(videoElement)
  .asset('XYrjlG09QTa8pxAo5Fzjww')
  .mediaType(MediaType.HLS);

Extract DAI stream manager metadata​

Create a new instance of the DAI Stream Manager.

const daiStreamManager: DaiStreamManager = builder.build();

Extract the required metadata streamUrl and streamManager that will be used to create a Quickplay player.

const daiMetadata: DaiStreamMetadata = await daiStreamManager.getDaiMetadata();

Create Ad Composed Player​

AdComposedPlayer managers both content and ad playback. It basically extends the conventional Player functionality and adds ads rendering to it.

const contentPlayer: Player = flPlayer
  .createPlayerBuilder()
  .mediaElement(mediaElement)
  .mediaUrl(daiMetadata.streamurl)
  .mediaType(MediaType.HLS)
  .build();

const adsPlayer = flAdsIma
  .createPlayerBuilder()
  .ima(google.ima)
  .imaDaiManager(daiMetadata.streamManager)
  .contentPlayer(contentPlayer)
  .contentVideoElement(videoElement)
  .contentContainerElement(videoWrapper)
  .build();

Replacement of all the tag parameters in a Live IMA DAI Stream​

You can change ad campaign targeting by replacing all the ad tag parameters used for the upcoming ad requests in a Live IMA DAI Streams.

const newAdTagParameters: { [key: string]: any } = {
    param1: value1,
    param2: value2,
    ...
}

adsPlayer.setAdTagParameters(newAdTagParameters);

Listening to Ad Events​

To listen to ad events, subscribe to any of the following events adbreakstart, adbreakend, adstart or adend.

adsPlayer.subscribe(`adbreakstart`, (adBreak: AdBreak) => {
  console.log('Ad break started', adBreak);
});

adsPlayer.subscribe(`adstart`, (adInfo: AdInfo) => {
  console.log('Ad started', adInfo);
});

adsPlayer.subscribe(`adend`, (adInfo: AdInfo) => {
  console.log('Ad ended', adInfo);
});

adsPlayer.subscribe(`adbreakend`, (adBreak: AdBreak) => {
  console.log('Ad break ended', adBreak);
});

Handling Ad Blockers​

To avoid issues with ad blockers, you must ensure that google.ima is available before creating the SSAI ad player. If it’s not available (due to an ad blocker), fall back to the content player.

if (
  typeof google === 'undefined' ||
  typeof google.ima === 'undefined' ||
  typeof google.ima.dai === 'undefined'
) {
  const contentPlayer = flPlayer
    .createPlayerBuilder()
    .mediaElement(mediaElement)
    .mediaUrl(daiMetadata.streamurl)
    .mediaType(MediaType.HLS)
    .build();
} else {
  const adsPlayer = flAdsIma
    .createPlayerBuilder()
    .ima(google.ima)
    .imaDaiManager(manager)
    .contentPlayer(contentPlayer)
    .contentVideoElement(videoElement)
    .contentContainerElement(adContainer)
    .playbackPolicy(adPolicy)
    .logger(logger)
    .build();
}