Client Side Ad Insertion

The fl-ads-ima library integrates with GoogleIMA to offer Client Side Ad Insertion capability for both VOD and Live.

GoogleIMA

Setup

GoogleIMA SDK must be loaded.

// Add the script tag for GoogleIMA SDK
<script type="text/javascript" src="//imasdk.googleapis.com/js/sdkloader/ima3.js"></script>;

Create Ad Composable Player

AdComposablePlayer manages both main content player and ad player, providing a seamless main content playback with GoogleIMA ads served as per GoogleIMA Ad response.

Create Content Player

Create a content player using the PlayerBuilder for Player or WebMAF Player.

const contentPlayer = playerBuilder
  .mediaElement(videoElement)
  .mediaUrl(contentUrl)
  .drmLicenseUrl(playbackAsset.licenseUrl)
  .drmScheme(playbackAsset.drmScheme)
  .build();

Create Ad Player

Create an ad Player using main content Player and GoogleIMAAdRequest. Please note, the created ad player cannot be used standalone, as it just manages GoogleIMA Ad playback alone. The main content playback is not managed by this ad player.​

AdsRenderingSettings

The following parameters that control the rendering of ads.

Name	Required	Type	Description
autoAlign	false	boolean	Set to false if you wish to have fine grained control over the positioning of all non-linear ads. If this value is true, the ad is positioned in the bottom center. If this value is false, the ad is positioned in the top left corner. The default value is true.
bitrate	false	number	Maximum recommended bitrate in kbit/s.
enablePreloading	false	boolean	Enables preloading of video assets
loadVideoTimeout	false	number	Timeout (in milliseconds) when loading a video ad media file. If loading takes longer than this timeout, the ad playback is canceled and the next ad in the pod plays, if available.
mimeTypes	false	string[]	Only supported for linear video mime types. If specified, the player will include media that matches the MIME type(s) specified in the list and exclude media that does not match the specified MIME type(s). The format is a list of strings, e.g., [ 'video/mp4', 'video/webm', ... ] If not specified, the SDK will pick the media based on player capabilities.
playAdsAfterTime	false	number	For VMAP and ad rules playlists, only play ad breaks scheduled after this time (in seconds).
enableUiElements	false	boolean	Specifies whether the UI elements should be displayed or not.
useStyledLinearAds	false	boolean	Render linear ads with full UI styling
useStyledNonLinearAds	false	boolean	Render non-linear ads with a close and recall button.

const adTagUrl =
  'https://pubads.g.doubleclick.net/gampad/ads?sz=640x480&' +
  'iu=/124319096/external/ad_rule_samples&ciu_szs=300x250' +
  '&ad_rule=1&impl=s&gdfp_req=1&env=vp&output=vast&' +
  'cust_params=deployment%3Ddevsite%26sample_ar%3Dpremidpost&cmsid=496&' +
  'vid=short_onecue&correlator=&unviewed_position_start=1';

const adPlayer = flAdsIma
  .createPlayerBuilder()
  .ima(google.ima)
  .adRequest({ adTagUrl: adTagUrl, slotWidth: 628, slotHeight: 300 })
  .contentPlayer(contentPlayer)
  .contentVideoElement(videoElement) // videoElement on which ad is played.
  .contentContainerElement(videoWrapper) // adContainer on which ad UI and settings are rendered.
  .adsRenderingSettings({
    enableUiElements: true,
    useStyledLinearAds: true,
  })
  .build();

This player could be used like conventional player from FLPlayer library for playback.

note

GoogleIMA sdk will provide the skipAd button if the ad is skippable.

​

Listening to Ad Events

The player can subscribe to ad events to track the state of ad playback and implement custom UIs. The AdPlayer emits the following ad events:

Event Name	Description
adbreakstart	Called when an ad break starts
adbreakend	Called when an ad break ends
adstart	Called when playback of an advert starts
adend	Called when playback of an advert ends
adprogressupdate	Called when an advert is playing
adcuepoints	Called when cue points are available
adverttrackingevent	Called when an ad tracking event is signalled

player.subscribe("adstart", function (adInfo) {
    // update the player controls if needed
}

player.subscribe("adend", function (adInfo) {
    // update the player controls if needed
}

player.subscribe("adprogressupdate", function (adInfo, progress) {
    // update ad count down timer if needed
});

player.subscribe("adverttrackingevent", function (adTrackingEvent) {
  // signal ad and media events
});

Ad Metadata

AdBreakInfo

Represents an ad break object.

Property	Type	Description
adBreakID	string	Unique id of the ab break
contentTimePosition	AdContentTimePosition	The position of the ad break, can be on of preroll, midroll or postroll
adBreakStartTimeOffsetMs	number	The start position in milliseconds
remainingTimeMs	number	The time remaining in the ad break from the playhead provided, in milliseconds
durationMs	number	The duration of the ad break, in milliseconds
totalAds	number	Total number of adverts in the ad break
adBreakIndex	number	The index of the current ad break

note

The totalAds read from AdPlayer may not be accurate when it comes from adstart event. This may change once ad playback starts. GoogleIMA advises to read totalAds on or after FIRST_QUARTILE ad tracking event, to get a reliable data.

AdInfo

Represents an advert object.

Property	Type	Description
adID	string	The identifier of the advert
sequence	number	The sequence of the advert
adStartTimeOffsetMs	number	The start playhead position of the advert in milliseconds
durationMs	number	The duration of the advert in milliseconds
remainingTimeMs	number	Returns the natural playback time remaining for the advert in milliseconds
isSkippable	boolean	Indicates if the ad is skippable
skipOffsetMs	number	The value of skip offset for the advert, in milliseconds. If the VAST skip offset is not defined then this method returns -1, signifying that the advert cannot be skipped.
isFiller	boolean	Whether this advert represents filler content
adBreakInfo	AdBreakInfo	The ad break in which the advert belongs in
vastProperties	VastProperties	Represents a VAST properties of advert.

VASTProperties

Represents a VAST properties object.

Property	Type	Description
adSystem	string	The source ad server of the advert
AdTitle	string	The common name of the advert
adServingId	string	An identifier used to compare impression-level data across systems
creativeId	string	CreativeId of the advert
category	string	Category of the advert content
description	string	The longer description of the advert
advertiser	string	Advertiser name
pricing	string	Pricing element of the advert
survey	string	An URI to any resource file having to do with collecting survey data
expires	string	Number of seconds in which the ad is valid for execution
adChoicesIcons	Array of AdChoicesIcon	The List of AdChoicesIcon instances

AdChoicesIcon

Represents VAST response metadata related to WTA (Why This Ad?) privacy disclosures. These disclosures are returned inside the AdChoices element of the VAST response. WTA related attributes are part of the relevant Icon tag and are used to render the AdChoices icon.

Property	Type	Description
program	string	The program represented in the icon (e.g. AdChoices).
width	string	The pixel width of the icon asset.
height	string	The pixel height of the icon asset.
xPosition	string	The x-coordinate of the top, left corner of the icon asset relative to the ad display area. Values of "left" or "right" also accepted and indicate the leftmost or rightmost available position.
yPosition	string	The y-coordinate of the top left corner of the icon asset relative to the ad display area; values of"top" or "bottom" also accepted.
offset	string	The time of delay from when the associated linear creative begins playing to when the icon should be displayed; provided in the format HH:MM:SS.mmm or HH:MM:SS where .mmm is milliseconds (optional).
duration	string	The duration icon should be displayed unless clicked or ad is finished playing; provided in the format HH:MM:SS.mmm or HH:MM:SS where .mmm is milliseconds (optional).
apiFramework	string	Identifies the API needed to execute the icon resource file if applicable.
altText	string	The alternative text for the image. In an html5 image tag this should be the text for the alt attribute. This should enable screen readers to properly read back a description of the icon for visually impaired users.
imageURL	string	The URL of the image file for the icon (PNG is preferred).
clickThroughURL	string	The URL of the action that occurs when a user clicks the AdChoices icon. In most cases,the user sees the Ad Settings page that the media player opens when the icon is clicked.
fallbackImages	Array of IconClickFallbackImage	The List of IconClickFallbackImage instances.

IconClickFallbackImage

In cases where the WTA icon can not display the Ad Settings page, such as when the platform does not support a browser, WTA can show users a fallback image that contains the same disclosure information as the Ad Settings page. When an icon click occurs, the ad must pause and the image must be rendered above the video. The player must provide a means for the user to close the dialogue, for example by pressing the back button. The image must not be obstructed and should not be downloaded unless a click-action occurs.

Property	Type	Description
width	string	The pixel width of the image asset.
height	string	The pixel height of the image asset.
altText	string	The alternative text for the fallback image.
imageURL	string	The URL of the image file for the fallback image (PNG is preferred).

Events tracked as part of AdTrackingEvent

Event	Description
AD_BREAK_STARTED_EVENT	Fired when an ad break in a stream starts.
AD_STARTED_EVENT	Fired when an ad starts playing.
AD_FIRST_QUARTILE_EVENT	Fired when the ad playhead crosses first quartile.
AD_MIDPOINT_EVENT	Fired when the ad playhead crosses midpoint.
AD_THIRD_QUARTILE_EVENT	Fired when the ad playhead crosses third quartile.
AD_PAUSED_EVENT	Fired when an ad is paused.
AD_RESUMED_EVENT	Fired when an ad is resumed.
AD_MUTED_EVENT	Fired when an ad is muted.
AD_UNMUTED_EVENT	Fired when an ad is unmuted.
AD_ENDED_EVENT	Fired when an ad completes playing.
AD_BREAK_ENDED_EVENT	Fired when an ad break in a stream ends.
AD_CLICK	Fired when an ad is clicked.
AD_VIDEO_CLICKED	Fired when a non-clickthrough portion of a video ad is clicked.
AD_IMPRESSION	Fires when the impression URL has been pinged.
AD_USER_CLOSE	Fires when the ad is closed by the user.
AD_SKIPPED_EVENT	Fired when an ad was skipped.
AD_INTERACTION	Fires when an ad triggers the interaction callback. Ad interactions contain an interaction ID string in the ad data.
AD_SKIPPABLE_STATE_CHANGED	Fires when the displayed ads skippable state is changed.
AD_VIDEO_ICON_CLICKED	Fires when a user clicks a video icon.

CCPA compliance

The CCPA consent string must be sent as us_privacy query param with ad request url. Please check Google IMA SDK Documentation¹ to read further on for CCPA compliance. ​ The below code shows an ad request url with the IAB parameter "1YNN".

let adTagUrl =
  'https://pubads.g.doubleclick.net/gampad/ads' +
  'iu=/124319096/external/single_ad_samples&output=vast&us_privacy=1YNN';