Skip to main content

Client Side Ad Insertion

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

GoogleIMA

Supported Google IMA SDK version: 3.30.3

Create Ad Composed Player

AdComposedPlayer manages both content and ad playback. It basically extends the conventional Player functionality and adds Ad Rendering to it.

note

This section is specific to Google IMA SDK integration.

The IMA SDK will show additional views on top of the player while an ad is playing (e.g., a ‘more info’ link and a skip button, if applicable). Since advertisers expect a consistent experience across apps, the IMA SDK does not allow customization of the views that it shows while an ad is playing. It is therefore not possible to remove or reposition the skip button, change the fonts, or make other customizations to the visual appearance of these views. The IMA SDK may report whether ads are obscured by application provided views rendered on top of the player. Apps that need to overlay views that are essential for controlling playback must register them with the IMA SDK so that they can be omitted from viewability calculations. Apps that use a custom player UI must register overlay views. Player library provides an API to register the views that are on top of the ad view group, but that are essential for controlling Ad playback. The AdOverlayUIScope defines the context for the views that are part of ad view group.

The following ad views UI scopes are defined:

PropertyDescription
PLAYBACK_CONTROLS_UI_SCOPEUIScope for playback controls overlaying the player.
CLOSE_AD_UI_SCOPEUIScope for ad close buttons overlaying the player.
OTHER_UI_SCOPEUIScope for other overlays.
NOT_VISIBLE_UI_SCOPEUIScope for overlays that are not visible

Here are the steps to initialize the playback session for IMA ads:

  1. Retrieve ad tag url.
val 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';
  1. Provide the UI scope info for an overlay view shown on top of an ad view group. Below is one possible way to provide that information.
val adOverlayUIScopes = mutableListOf<AdOverlayUIScope>()
val playerControlsUIScope = AdOverlayUIScope(playerControlsView,
AdOverlayUIScope.PLAYBACK_CONTROLS_UI_SCOPE
)
adOverlayUIScopes.add(playerControlsUIScope)
val showDebugOverlayBtnUIScope = AdOverlayUIScope(showDebugOverlayBtn,
AdOverlayUIScope.OTHER_UI_SCOPE
)
adOverlayUIScopes.add(showDebugOverlayBtnUIScope)
val debugOverlayViewUIScope = AdOverlayUIScope(debugOverlayView,
AdOverlayUIScope.OTHER_UI_SCOPE
)
adOverlayUIScopes.add(debugOverlayViewUIScope)
  1. Create the content Player.
val contentPlayer = PlayerBuilder()
.mediaURL(contentUrl)
.mediaType(MediaType.DASH)
.build(applicationContext)
  1. Create IMA targeted AdRequest instance.
note

Pass a collection of AdOverlayUIScope instances, if necessary, to initialize AdRequest

    val adRequest = GoogleIMAAdRequest(adURL, adOverlayUIScopes)
  1. Wrap the content player with IMA targeted AdComposedPlayer.
    val player = with(contentPlayer) {
IMAAdPlayerFactory.imaAdComposedPlayerWith(
applicationContext,
this,
adRequest
)
}
  1. Convert the AdComposedPlayer to a ComposablePlayer
    val composablePlayer = composablePlayerWith(player)
  1. Pass the required view to the player using the attachRendererView method so that the SDK can display the ad view and content view as required, playerRoot is a FrameLayout. Although it can be done directly, we suggest to attach the view inside the Player.Listener#onPlayerViewAvailable() callback from the library.
    composablePlayer.attachRendererView(
playerRoot,
FrameLayout.LayoutParams(
ViewGroup.LayoutParams.MATCH_PARENT,
ViewGroup.LayoutParams.MATCH_PARENT
)
)

Listening to Ad Events

One can configure AdComposedPlayer#adEventListener property for listening to Ad Events. The following ad events are notified via AdEventListener callbacks:


//Called when an Ad started playing
fun onAdStart(adInfo: AdInfo)

//Called when an Ad finished playing
fun onAdEnd(adInfo: AdInfo)

// Returns an List of offsets, in milliseconds, indicating when a scheduled Ad Break will play.
fun onAdCuePointsAvailable(cuePoints: LongArray)

// Called when the first Ad, in an Ad Break, have started playing
fun onAdBreakStart(adBreakInfo: AdBreakInfo?)

// Called when all the Ads, in an Ad Break, have finished playing
fun onAdBreakEnd(adBreakInfo: AdBreakInfo?)

// Called when an error has been encountered during Ads playback
fun onAdError(error: Error)

// Called when an ad tracking event is signalled.
fun onAdTrackingEvent(adTrackingEvent: AdTrackingEvent)

Events tracked as part of AdTrackingEvent

EventDescription
ALL_ADS_LOADED_EVENTFired when the VAST response has been received.
ALL_ADS_COMPLETED_EVENTFired when all the valid ads in the ads response finished playing, or when the response doesn't return any valid ads.
AD_CUEPOINTS_CHANGED_EVENTFired when VOD stream cuepoints have changed.
AD_PERIOD_STARTED_EVENTFired when an ad period in a stream starts.
AD_PERIOD_ENDED_EVENTFired when an ad period in a stream ends.
AD_BREAK_FETCH_ERROR_EVENTFired when an ad break will not play back any ads.
AD_BREAK_READY_EVENTFired when an ad break is ready from VMAP or ad rule ads.
AD_BREAK_STARTED_EVENTFired when an ad break in a stream starts.
AD_BUFFERING_EVENTFired when playback stalls while the ad buffers.
AD_STARTED_EVENTFired when an ad starts playing.
AD_FIRST_QUARTILE_EVENTFired when the ad playhead crosses first quartile.
AD_MIDPOINT_EVENTFired when the ad playhead crosses midpoint.
AD_THIRD_QUARTILE_EVENTFired when the ad playhead crosses third quartile.
AD_PAUSED_EVENTFired when an ad is paused.
AD_RESUMED_EVENTFired when an ad is resumed.
AD_ENDED_EVENTFired when an ad completes playing.
AD_BREAK_ENDED_EVENTFired when an ad break in a stream ends.
AD_SKIPPED_EVENTFired when an ad was skipped.
AD_SKIPPABLE_STATE_CHANGED_EVENTFired when an ad changes its skippable state.
AD_TAPPED_EVENTFired when a non-clickthrough portion of a video ad is clicked.
AD_ICON_TAPPED_EVENTFired when ad icon is tapped.
AD_ICON_FALLBACK_IMAGE_CLOSED_EVENTFired on closing the icon fallback image dialog. This event only fires for Connected TV devices.
AD_CLICKED_EVENTFired when an ad is clicked.
AD_AUXILIARY_DATA_EVENTFired to enable the SDK to communicate a message to be logged.

Ad Metadata

AdInfo

Represents an advert object.

PropertyTypeDescription
adIDstringThe identifier of the advert
sequencenumberThe sequence of the advert
adStartTimeOffsetMsnumberThe start playhead position of the advert in milliseconds
durationMsnumberThe duration of the advert in milliseconds
remainingTimeMsnumberReturns the natural playback time remaining for the advert in milliseconds
isSkippablebooleanIndicates if the ad is skippable
skipOffsetMsnumberThe 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.
isFillerbooleanWhether this advert represents filler content
adBreakInfoAdBreakInfoThe ad break in which the advert belongs in
adVastPropertiesAdVastPropertiesRepresents a VAST properties of this advert.
note

The totalAds read from AdPlayer may not be accurate when it comes from onAdStart 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.

AdVASTProperties

Represents a VAST properties object.

PropertyTypeDescription
adSystemstringThe source ad server of the advert
adTitlestringThe common name of the advert
adServingIdstringAn identifier used to compare impression-level data across systems
adIdstringThe Ad identifier of the creative
creativeIdstringThe identifier of the creative
categorystringCategory of the advert content
descriptionstringThe longer description of the advert
advertiserstringAdvertiser name
pricingstringPricing element of the advert
surveystringAn URI to any resource file having to do with collecting survey data
expiresstringNumber of seconds in which the ad is valid for execution
adChoicesIconsCollection of AdChoicesIconThe 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.

PropertyTypeDescription
programstringThe program represented in the icon (e.g. AdChoices).
widthstringThe pixel width of the icon asset.
heightstringThe pixel height of the icon asset.
xPositionstringThe 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.
yPositionstringThe y-coordinate of the top left corner of the icon asset relative to the ad display area; values of"top" or "bottom" also accepted.
offsetstringThe 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).
durationstringThe 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).
apiFrameworkstringIdentifies the API needed to execute the icon resource file if applicable.
altTextstringThe 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.
imageURLstringThe URL of the image file for the icon (PNG is preferred).
clickThroughURLstringThe 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.
fallbackImagesCollection of IconClickFallbackImageThe 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.

PropertyTypeDescription
widthstringThe pixel width of the image asset.
heightstringThe pixel height of the image asset.
altTextstringThe alternative text for the fallback image.
imageURLstringThe URL of the image file for the fallback image (PNG is preferred).

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';