Server Side Ad Insertion using Google IMA

GoogleIMA

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

Name	Type	Optional	Description
ima	Any	false	A reference to the google.ima library.
contentContainerElement	Element	false	The element to display the ads in. The element must be inserted into the DOM before initializing the Ad player.
contentVideoElement	HTMLVideoElement	false	Specifies the alternative video ad playback element. We recommend always passing in your content video player.
localization	String	true	The language of text within UI elements.
adTagParameters	Map<String, String>	true	Ad tag parameters used for upcoming ad requests for a live stream.
contentSource	String	true	Required for VOD stream. Unique identifier for the publisher content, from a CMS. Required for on-demand streams.
video	String	true	Required for VOD stream. Identifier for the video content source. Required for on-demand streams.
asset	String	true	Required for live stream. This is used to determine which stream should be played. Required for live streams.
mediaType	MediaType	false	The content media type.
apiToken	String	true	The stream request API key. It is used to verify the applications that are attempting to access the content.
logger	Logger	true	Application 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);
});