Radiant Media Player

Video ads with the Google IMA HTML5 SDK

Documentation sections:

This documentation page applies when using the Google IMA HTML5 SDK with Radiant Media Player. For documentation on using rmp-vast go here.

Quick start guide

Radiant Media Player provides a complete client-side video ads solution. To get started you just need to get your hands on an ad tag URL from your ad provider and add it to your player code. Here is an example:

<!-- Include Radiant Media Player JavaScript file in your <body> or <head> -->
<script src="https://cdn.radiantmediatechs.com/rmp/4.6.31/js/rmp.min.js" 
<!-- Set up your wrapper div with its unique id -->
<div id="rmpPlayer"></div>
// First we specify bitrates to feed to the player
// You can use HLS, DASH or progressive download or a combination of those protocols
// You can use ads with on-demand, live or DVR content
var bitrates = {
  hls: 'https://dqwp3xzzbfhtw.cloudfront.net/vod/smil:bbb.smil/playlist.m3u8'
// Then we set our player settings
var settings = {
  licenseKey: 'your-license-key',
  bitrates: bitrates,
  width: 640,
  height: 360,
  ads: true,
  // This is the ad label that can be displayed on the player while a linear ad is playing
  labels: {
    ads: {
      controlBarCustomMessage: 'Ads'
  // We pass our adTag here - the player knows what to do with it
  adTagUrl: 'https://pubads.g.doubleclick.net/gampad/ads?sz=640x480&iu=/124319096/external/single_ad_samples&ciu_szs=300x250&impl=s&gdfp_req=1&env=vp&output=vast&unviewed_position_start=1&cust_params=deployment%3Ddevsite%26sample_ct%3Dlinear&correlator=',
  poster: 'https://www.radiantmediaplayer.com/images/poster-rmp-showcase.jpg'
var elementID = 'rmpPlayer';
var rmp = new RadiantMP(elementID);

Next sections include more options and documentation for advanced use cases including: ad scheduling, ad waterfalling, ad block detection or our ads API.

Certified Google IMA Integration

Radiant Media Player is a Google's video technology partner and has its IMA HTML5 SDK integration certified by Google. As such you are sure you can generate revenue according to best practices in the industry.

Supported ad-servers

You can make video ad requests to any VAST-compliant ad server with Radiant Media Player. Supported 3rd-party ad servers include:

  • DoubleClick for Publishers (DFP)
  • AdSense for video
  • DoubleClick Ad Exchange
  • Smart AdServer
  • YuMe
  • OpenX
  • SpotXchange
  • Innovid
  • Adap.tv
  • Smartclip
  • MediaMind
  • Brightroll
  • AdGlare

Supported IAB Video Suite


VAST 3 VAST 2 VMAP 1.0.1 VPAID 2 (HTML5/JavaScript)

IAB Video Suite support notes

  • The following VAST 3.0 features are not yet supported: any VAST 3.0 feature not yet supported by the DFP front end
  • The following VMAP features are not yet supported: VMAP-specific tracking events, VMAP-specific error codes, Overlay ads, Time offsets other than hh:mm:ss or "start" and "end", Display breakType attribute, repeatAfter attribute
  • The following features are not supported on iPhone: Non-linear ads (Overlays), Skippable (non-TrueView), TrueView InStream

Additional support notes

We provide the technology for you to render video ads in our web video player. Revenue generated with video ads remains 100% yours.

Supported OS/browsers for the IMA HTML5 SDK

  • Desktop: Chrome, Firefox, Safari 8+, Internet Explorer 11
  • Mobile: Chrome for Android 4.3+, Safari & Chrome for iOS 8+

Ads may work in other environments with Radiant Media Player but they are not officially supported.

When version for a browser is not specified we support the latest version of this browser.

Supported ad types

  • Linear video ads: pre-roll, mid-roll, post-roll on mobile & desktop
  • Skippable ads with InStream TrueWiew support (AdSense & DoubleClick)
  • Ad pods (playlist of video ads) & bumpers
  • Non-linear ads (overlays)
  • Companion ads through Google Publisher Tag (GPT) or our ads API
  • All DoubleClick, Ad Exchange or AdSense supported video ad type

Supported streaming protocols for media content

The following streaming protocols can be used for media content delivery when video ads are enabled within the player (this is for the media content behind the ad, not the ad itself, see next section for the ad):

  • On-demand video: HLS, DASH, MP4 & WebM progressive download
  • Live video: HLS & DASH
  • DVR video: HLS (pre-roll & overlay ads only)

You can also display audio-only ads within our audio-only player.

Supported formats and streaming protocols for the ad

A VAST response should hold information about the nature of the creative (type, size, bitrate ...) being returned. A VAST response can hold several formats at various bitrates so that an ad can be displayed on a larger range of devices. Radiant Media Player is equipped with a bandwidth and viewport size detection mechanism for playback of video ads. As such and assuming the creative type, size and bitrate can be found in the VAST response the player will automatically select the best suitable candidate to playback the ad based on device capabilities:

Example of formats (MIME types) that can be used for the ad:

  • Linear creatives: video/mp4, video/webm, application/vnd.apple.mpegurl, application/dash+xml, video/3gpp ...
  • Non-linear creatives: image/png, image/jpeg ...
  • VPAID creatives: application/javascript

For an example of a VAST response with a combination of formats see this adTag.

It is possible to stream video ads with adaptive bitrate streaming in HLS. However this is only possible where HLS is natively supported in HTML5 video (macOS Safari, iOS Safari, Android Chrome, MS Edge) and assuming a proper HLS stream is present in the VAST response.

Using Google Ads network with the IMA HTML5 SDK

When serving ads from the Google Ads network (DFP, ADX, AdSense for Video) please take note of the following:

  • DFP: we recommend using the IMA HTML5 SDK to display ads coming from DFP servers to benefit from all DFP features
  • ADX & AdSense for Video: you must use the IMA HTML5 SDK to render ads coming from ADX or AdSense for Video servers

ADX & AdSense for Video ads will not render with our VAST parser rmp-vast. DFP ads should render with rmp-vast but we still recommend using the IMA HTML5 SDK whenever possible. Please read our using the IMA HTML5 SDK in a WebView section for complementary information on using the IMA HTML5 SDK in a WebView.

CORS settings

To be servable in a JavaScript environment a VAST ad server's response must include the following HTTP CORS headers:

  • Access-Control-Allow-Origin: <origin header value>
  • Access-Control-Allow-Credentials: true

You can find more information on the subject here.

Autoplay of linear video ads

Radiant Media Player support autoplay of pre-roll linear ad assets on desktop and mobile devices. Read our autoplay support documentation page for more information.

Video ads player settings

General settings

ads: Boolean

Activate or not ads within the player. Default: false.

adTagUrl: String

Specifies the ad tag url that is requested by the player from the ad server. Default: ''.
We recommend using fully qualified URLs for the adTagUrl setting

adLocale: String

The targeted language for the ads UI provided by the IMA HTML5 SDK. ISO 639-1 (two-letter) code. Default: 'en'.
Some languages like Portuguese may require more than a two-letter code. For Portuguese Portuguese use 'pt_pt' and for Brazilian Portuguese use 'pt_br'. Contact us if you are in doubt about which language code to use.

adDisableCustomPlaybackForIOS10Plus: Boolean

On iPhone iOS 10+ inline HTML5 video playback allows for the display of skippable video ads. However fullscreen mode on iOS is limited to the default Apple-provided player that cannot support custom UI elements. When set to true this setting enables support for skippable video ads on iPhone iOS 10+ However in such case and when in fullscreen mode new ad requests will not be able to be loaded. When set to false the player will not support skippable video ads but new ad requests will render in fullscreen mode. More information here. Default: false.

adCountDown: Boolean

A countdwon to be displayed within the player control bar. It shows the remaining time for the video ads. Default: false.
If you are using video ads from AdSense or Ad Exchange set adCountDown: false. This is because most ads from AdSense or Ad Exchange already have a built-in ad countdown.

adMaxNumRedirects: Number

Specifies the maximum number of redirects before the subsequent redirects will be denied, and the ad load aborted. The number of redirects directly affects latency and thus user experience. This applies to all VAST wrapper ads. Default: 4.

adShowRemainingTime: Boolean

When set to true, a remaining time bar UI will be displayed on top of the player control bar for linear creatives. Default: false.

adTagReloadOnEnded: Boolean

When set to true this setting will cause the player to attempt to reload the initial adTag when a user requests content to be played after having ended. This setting is compatible with the adTagWaterfall setting and outstream ads but is disabled with related, playlist, loop setting and ad scheduler. This setting should not be used with VMAP adTags.

useRmpVastOnImaLoadError: Boolean

When the target client uses an ad-blocker the Google IMA HTML5 SDK JavaScript library could fail to load. When this happens and video ads cannot be displayed. We are able to detect such behaviour and when useRmpVastOnImaLoadError is set to true the player will attempt to load rmp-vast library as a fallback to the IMA HTML5 SDK and resume the ad loading process. This can help to fight ad-blockers but is not a guarantee for success as ad-blockers could also block VAST/creative HTTP requests after the library has loaded. Default: true.

adPauseOnClick: Boolean

When set to true this setting will cause to pause the playing linear ad (or content for a non-linear ad) when the ad is interacted with. Default: true. Note that for VPAID ads this setting is always set to false - it should be up to the VPAID creative to decide what to do upon interaction. On some devices the browser may still decide to pause a video asset when a new window opens.

adLoadVastTimeout: Number

Timeout (in milliseconds) when loading a VAST single wrapper. Default: 7000, which represents a 7 seconds timeout.

adLoadMediaTimeout: Number

Timeout (in milliseconds) when loading a creative media file (after a successful VAST response). If loading takes longer than this timeout, the ad playback is cancelled and the next ad in the pod plays or content resumes. Default: 10000 which represents a 10 seconds timeout.

adAutoAlign: Booleab

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. Equivalent to AdsRenderingSettings.autoAlign IMA HTML5 SDK setting. Default: true.
Setting added with player version 4.4.20.

adMaxBitrate: Number

Maximum recommended bitrate. The value is in kbit/s. The player will pick media with bitrate below the specified max from the VAST response, or the closest bitrate if there is no media with lower bitrate found. Default: -1, means the bitrate will automatically be selected by the player.

adForceNonLinearFullSlot: Boolean

Forces non-linear AdSense ads only to render as linear fullslot. If set, the content video will be paused and the non-linear text or image ad will be rendered as fullslot. The content video will resume once the ad has been skipped or closed. Default: false.

adUseStyledNonLinearAds: Boolean

Render non-linear ads with a close and recall button. Default: true.

adAutoplayOnlyPreroll: Boolean

When set to true this setting will cause the player to load and autoplay the provided pre-roll adTag when init is called. When the linear ad asset has completed content will not resume but will rather remain in a state as if it was never started (this behaviour is similar to having an outstream ad before content). A user interaction will thus be needed to start content after ad has completed. If a non-linear ad is returned by the ad server content will autoplay with the ad so it is up to the publisher to insure a compatible linear ad asset is returned by the ad server when using this setting (or otherwise to implement different case-scenario through the player API). This setting is not compatible with the Ad scheduler or VMAP adTag and is only available for the IMA HTML5 SDK. Default: false.

adParser: String

Specifies which VAST parser the player should use. Possible values are 'rmp-vast' and 'ima'. Default: 'ima'.

adForceImaInWebView: Number

When an Android or iOS WebView (this includes using the player in apps built with Cordova or in the Facebook in-app browser) is detected by the player it will force the adParser setting to 'rmp-vast'. The reason is that the Google IMA HTML5 SDK does not officially support Android or iOS WebView and could have unwanted side effects. This setting forces the player to use the IMA HTML5 SDK in an Android or iOS WebView. Note that we do not guarantee support for using adForceImaInWebView set to true as this is not an officially supported use-case for the IMA HTML5 SDK. See this section for more information on the subject. Default: false.

adContentDuration: Number

Specifies the duration of the content in seconds to be shown. Used in AdX requests only. Default: 0.

adContentKeywords: String

Specifies the keywords used to describe the content to be shown. Used in AdX requests only. Default: ''.

adContentTitle: String

Specifies the title of the content to be shown. Used in AdX requests only. Default: ''.

Ad Tag Variables & Macros

See the ad tag variables & macros documentation page.

Using the IMA HTML5 SDK in a WebView

It is to be noted that the IMA HTML5 SDK does not support being used in a WebView, this includes using it in a Cordova-based application or within the Facebook in-app browser for example. As such when the player detects a WebView it automatically switches to rmp-vast which does support being used in a WebView. It should also be noted that displaying video ads from Google ADX or AdSense for Video requires using the IMA HTML5 SDK. DFP ads should render with rmp-vast but not all DFP features may be supported. As such with the player default settings video ads coming from the Google Ads network may not always render in a WebView.

In order to work around this issue we have introduced the adForceImaInWebView setting (described above) which when set to true will allow the IMA HTML5 SDK to be used in a WebView. However since this is not an officially supported use-case for the IMA HTML5 SDK we do not guarantee support for this feature. When using adForceImaInWebView set to true, video ads and content should generally render as expected but drawbacks do exist, and you should be aware of those drawbacks. For example:

  • Poster rendering issues on Android
  • Click handling issues on iOS

If you want to use the adForceImaInWebView setting you must be happy to deal with those glitches. As an alternative this is what we recommend:

  • For WebView usage find adTags coming from outside the Google Ads network (any VAST-compliant ad sever should work with our rmp-vast parser)
  • Use the player API isWebView method to direct those adTags for WebView (this method can be used before init is called on player) while still using the IMA HTML5 SDK to render ads outside of WebView (e.g. desktop and mobile browsers)
Except as otherwise noted, the content of this page is licensed under the Creative Commons Attribution 3.0 License.