Documentation

Video Advertisement With Google IMA HTML5 SDK

Quick start guide

Radiant Media Player provides a complete client-side video advertisement solution. To get started you just need to get your hands on a VAST tag from your advertisement service provider and configure the player to display advertisement. The player will automatically display advertisement when requested and manage content pausing and resuming.

Here is a complete example:

<!-- Include Radiant Media Player JavaScript file in your <body> or <head> -->
<script src="https://cdn.radiantmediatechs.com/rmp/10.1.1/js/rmp.min.js"></script>
<!-- Player container element -->
<div id="rmp"></div>
<script>
  // Streaming source - HLS in this example
  const src = {
    hls: 'https://your-hls-url.m3u8'
    // You may provide alternate or different source types - the player will automatically pick the best option
    // dash: 'https://your-dash-url.mpd'
    // mp4: ['https://your-mp4-url.mp4']
  };
  // Player settings
  const settings = {
    licenseKey: 'your-license-key',
    src,
    width: 640, 
    height: 360,
    ads: true,
    // We pass our adTag here - the player will attempt to load it upon startup
    adTagUrl: 'https://your-ad-tag-url',
    contentMetadata: {
      poster: [
        'https://your-poster-url.jpg'
      ]
    }
  };
  const rmp = new RadiantMP('rmp');
  // Initialization ... and done!
  async function initRmpPlayer() {
    try {
      await rmp.init(settings);
    } catch(error) {
      console.error('Radiant Media Player failed to initialize', error);
    }
  }
  initRmpPlayer();
</script>

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:

  • Google Ad Manager
  • AdSense for video
  • 24/7 Real Media
  • Adap.tv/ONE By AOL
  • AdForm
  • AdJuggler
  • Adman
  • Adotube
  • Adrise
  • AerServ
  • Brightroll
  • Emediate
  • Innovid
  • Mov.ad
  • Oasis
  • OpenX
  • Revive
  • Sizmek
  • Smart Ad Server
  • Smartclip
  • SpotXchange
  • SpringServe
  • Videology
  • VideoPlaza
  • YuMe
  • Zedo
  • Zoom.in

Supported IAB Video Suite

VAST/VMAP/VPAID/SIMID support

VAST 4 VAST 3 VAST 2 VMAP 1.0.1 SIMID 1.0 VPAID 2 (HTML5/JavaScript)
(1) (2) (3)

SIMID and VPAID support

See our SIMID and VPAID advertisement documentation page.

IAB Video Suite support notes

  • (1) The following VAST 4.0 features are supported: AdID, Mezzanine File, New VAST error codes, AdVerifications support
  • (1) The following VAST 4.2 features are supported: Support for Secure Interactive Media Interface Definition (SIMID), Allowance of multiple UniversalAdID nodes
  • (2) The Google IMA HTML5 SDK does not support any VAST 3.0 feature not yet supported by the Ad Manager front end.
  • (3) 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

More support information for the Google HTML5 IMA SDK can be found here.

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, Opera and Safari 12+
  • Mobile: Chrome, Firefox, Opera for Android 6+, Safari for iOS 12+, Latest Amazon Silk 94+ for fireOS 6+

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 TrueView 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 advertisement is enabled in the player:

  • On-demand video: HLS, MPEG-DASH, MP4 & WebM progressive download
  • Live video: HLS & MPEG-DASH
  • DVR video: HLS & MPEG-DASH

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

Supported formats and streaming protocols for the advertisement

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, video/3gpp ...
  • Non-linear creatives: image/png, image/jpeg ...
  • SIMID & VPAID creatives: application/javascript

Using Google Ads network with the IMA HTML5 SDK

When serving advertisement from Google Ads network (Google Ad Manager, AdSense for Video) you should use the Google IMA HTML5 SDK with our player.

Google Ad Manager, ADX & AdSense for Video advertisement may not render with our VAST parser rmp-vast. We cannot guarentee full support. Also read our using the Google IMA HTML5 SDK in a WebView section for complementary information on using the IMA HTML5 SDK in a WebView. The choice of VAST parser is made through the adParser player setting ('ima' or 'rmp-vast').

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 advertisement

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 advertisement player settings

General settings

ads: Boolean

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

adTagUrl: String

Specifies the VAST ad tag URL that should be requested by the player from the ad server. Default: ''.
We recommend using fully qualified URLs for the adTagUrl setting

adsResponse: String

Specifies a VAST document (as in XML string) to be used as the ads response instead of making a request via an ad tag url. This can be useful for debugging and other situations where a VAST response is already available. Default: ''. Using the adTagUrl setting is preferred when both options are available.

adLocale: String

The targeted language for the advertisement UI provided by the Google IMA HTML5 SDK. Format should be ISO 639-1 (two-letter) code. Default: 'auto', which means player will automatically detect viewer language.
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.

adForceNativeFullscreenOnIosForAds: Boolean

Forces native fullscreen on iOS when video ads are enabled in the player. This allows a fullscreen experience for video ads on iOS but skippable video ads will not be skippable when in fullscreen mode. When set to false the player will use an emulated fullscreen mode that allows for skippable ads to be skippable in fullscreen mode at the cost of a lesser viewing experience in fullscreen mode. Default: true.

adEnablePreloading: Boolean

Enables ad media preloading for the Google IMA SDK. This should be enabled when using VMAP/Ad with when mid-roll or post-roll. Default: false.

adCountDown: Boolean

A countdwon to be displayed within the player control bar. It shows the remaining time for the video advertisement. Default: true.
If you are using video advertisement from AdSense or Ad Exchange set adCountDown to 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 (or VMAP/ad-schedule) when a user requests content to be played after having ended. This setting is compatible with the adTagWaterfall setting and outstream ads. Default: true.

adLoadVastTimeout: Number

Timeout (in milliseconds) when loading a VAST single wrapper. Default: 8000, which represents a 8 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: 12000 which represents a 12 seconds timeout.

adLiveStreamPrefetchSeconds: Number

This property specifies the maximum number of seconds the IMA SDK should wait before reaching out to the ad server after you call AdsLoader.requestAds() for a live stream. The actual request time will be randomized. For example, if you set AdsRequest.liveStreamPrefetchSeconds to 30, the SDK waits 0 to 30 seconds after you call AdsLoader.requestAds() to actually make the request to the server. Default: 0.

adAutoAlign: 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. Equivalent to AdsRenderingSettings.autoAlign IMA HTML5 SDK setting. Default: true.

adShowMarkers: String

Adds markers on timeline for on-demand streams indicating to viewers when ad-breaks are scheduled. Works for VMAP tags and our ad-scheduler. Default: true.

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.

adNonLinearAdSlotWidth: Number

Specifies the width of the rectangular area within which a non linear ad is displayed. This value is used as one of the criteria for ads selection. This value does not need to match actual ad's width. Default: -1. By default the player uses the current player width for this value, but it can be customized to address specific use-cases.

adNonLinearAdSlotHeight: Number

Specifies the height of the rectangular area within which a non linear ad is displayed. This value is used as one of the criteria for ads selection. This value does not need to match actual ad's height. Default: -1. By default the player uses the current player height for this value, but it can be customized to address specific use-cases.

adUseStyledNonLinearAds: Boolean

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

adContinuousPlayback: String

Sets the continuous play context for an ads request. Available values are 'auto', 'yes', 'no'. Default: 'auto' which means 'yes' for playlist/related and 'no' for other cases.

adParser: String

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

adPageUrl: String

Specifies the full url of the page that will be included in the Google ad request for targeting purposes. The url needs to be a valid url. If specified, this value will be used for the [PAGEURL] VAST macro. Default: '' (which means that adsRequest.pageUrl will not be set).

adCookiesEnabled: Boolean

Whether the SDK should store a Google Ad Manager cookie (GFP Cookie) on the publisher's domain, as a first-party cookie. This enables persistence across multiple visits to the same domain without using third-party cookies. Defaults to true. This setting will not affect other cookies which may be set by other parties or for other purposes. User consent and opt-outs may also disable usage of first-party cookies. These will be picked up by publisher's usage of an IAB compliant Consent Management Provider, if in the same frame. Default: true.

adPpid: String

Sets the publisher provided id to be used with Google IMA SDK (client-side video advertisement only). Default: ''.

adSessionId: String

Sets the session ID to be used with Google IMA SDK (client-side video advertisement only). This is a temporary random ID. It is used exclusively for frequency capping. A session ID must be a UUID. Default: ''.

adCompanionBackfillMode: String

Sets the companion backfill mode to be used with Google IMA SDK (client-side video advertisement only). Possible values are 'always' or 'onmasterad'. Default: 'always'.

adContentDuration: Number

Specifies the duration of the content in seconds to be shown. Used in AdX requests only. Automatically obtained for VOD content if not set. 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: ''.

OMID support (OM Web SDK)

We support OMID (Open Measurement (OM) Web SDK) with Google IMA to enable third-party viewability and verification measurement. This feature is enabled by default. For more information about OMID support in Google IMA SDK see this documentation.

omidAccessModeRules: Object

The OM SDK supports running verification scripts in different access modes, which control how much the verification script can access. The three access modes are: 'FULL', 'LIMITED'. If you want to set different access modes for different verification script providers you can use omidAccessModeRules setting. Example:

const omidAccessModeRules = {
  'OTHER': 'FULL', // 'OTHER' is used to set the default access mode for all vendors not explicitly included below
  'MOAT': 'FULL',
  'DOUBLEVERIFY': 'LIMITED',
  'INTEGRAL_AD_SCIENCE' 'LIMITED',
  'NIELSEN': 'FULL',
  'COMSCORE': 'FULL',
  'MEETRICS': 'FULL',
  'GOOGLE': 'FULL' 
};

To implement 'CREATIVE' access mode, you must follow both of the following steps: sandbox the video player in a secure iframe, isolated from the rest of your site. Set the OmidAccessMode for your viewability partner to 'FULL'.

Ad Tag Variables

Ad-servers may use ad tag variables to optimise fill rate and ad-targeting. Those ad tag variables will be replaced automatically by Radiant Media Player just before the ad tag URL is requested to the ad-server. This is supported for both Google IMA and rmp-vast.

Note that the below ad tag variables are only replaced when the player attempts to load the ad tag URL from the server - the player will not replace those variables within the body of the VAST or VMAP response for tracking URIs or redirects. See the VAST macros section for variables that can be replaced within the body of a VAST response.

The following ad tag variables are supported:

  • __domain__: the Internet domain where the player stands
  • __page-url__: the full page URL where the player stands
  • __referrer__: the page URL that brought the viewer to the page where the player stands
  • __player-width__: current player width in pixels
  • __player-height__: current player height in pixels
  • __random-number__: a 12-digits random number (generally used for cache busting)
  • __timestamp__: the number of milliseconds elapsed since 1 January 1970 00:00:00 UTC (UNIX timestamp)
  • __mobile__: writes "mobile" if player is rendered on a mobile device
  • __ima__: writes "ima" if video ads are rendered with Google IMA
  • __item-title__: title for the currently playing video (taken from contentMetadata.title setting) - for playlist/related this variable is pulled from the JSON file for each item
  • __item-description__: description for the currently playing video (taken from contentMetadata.description setting) - for playlist/related this variable is pulled from the JSON file for each item
  • __item-duration__: duration in seconds for the currently playing video - only for on-demand streaming where mid/post rolls are used
  • __current-time__: current player time in seconds - only for on-demand streaming where mid/post rolls are used
  • __device-ua__: device user agent
  • __autoplay__: autoplay mode for player - value set is either auto or click
  • __muted__: muted mode for player - value set is either 1 (muted) or 0 (unmuted)
  • __language__: player language in ISO 639-1 (two-letter) format (value set by the viewer in browser or system settings) - examples: it, fr, en
  • __gdpr__: When added to an ad tag, this variable tells if GDPR is required 0 (no) or 1 (yes). This must be used with the __gdpr-consent__ macro. Example: https://www.radiantmediaplayer.com/vast/tags/inline-linear.xml?gdpr=__gdpr__&gdpr_consent=__gdpr-consent__. The IAB Transparency and Consent Framework (TCF) v2.0 must be implemented on your site/app for this variable to work.
  • __gdpr-consent__: When GDPR is required, as defined by the __gdpr__ variable, this variable adds a GDPR consent string (a.k.a. TC string). If GDPR is not required, __gdpr-consent__ is replaced with ''. The IAB Transparency and Consent Framework (TCF) v2.0 must be implemented on your site/app for this variable to work.
  • __uspdata__: When added to an ad tag, this variable is replaced with the US Privacy String found on page (read from window.__uspapi API). Example: https://www.radiantmediaplayer.com/vast/tags/inline-linear.xml?us_privacy=__uspdata__. The USP API must be implemented on your site/app for this variable to work.

All variables are replaced with string values - an empty string is used if they cannot be filled

The ad tag variables are automatically RFC3986 URI encoded when replaced as recommended in the VAST 3 specifications

Only the first instance of a given variable will be replaced - use JavaScript for multiple replacements or to append custom ad tag variables

Only use ad tag variables when your ad-server support them to avoid unnecessary computing at run time

Example:

https://www.radiantmediaplayer.com/vast/tags/inline-linear.xml?height=__player-height__&width=__player-width__&url=__page-url__&title=__item-title__

When making the ad request the player will try to load:

https://www.radiantmediaplayer.com/vast/tags/inline-linear.xml?height=360&width=640&url=https%3A%2F%2Fwww.radiantmediaplayer.com%2Fdocs%2Flatest%2Fad-tag-variables-macros.html&title=Ad%20Tag%20Variables%20And%20Macros

Google IMA specific ad tag variables

When using the Google IMA SDK with Radiant Media Player (which is default), all ad tag variables supported by Google Ad Manager are supported. The IMA SDK will add targeting variables before sending the ad request to Google Ad Manager servers.

Example:

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&url=%5Breferrer_url%5D&correlator=%5Btimestamp%5D&description_url=__page-url__

VAST Macros

VAST macros as defined in the VAST 4.2 specification enable the video player to provide certain details to the ad server at the time tracking URIs are accessed or when the VAST tag is requested. Macros will automatically be replaced by the player when pinging tracking URIs.

Supported macros with Google IMA: up to VAST 4.1 macros as of November 2020

Supported macros with rmp-vast: up to VAST 4.2 macros as of November 2020

See the VAST 4.2 specifications for more information on VAST macros.

Ad-blocker detection

By default when ads setting is set to true it automatically detects ad-blocker. If an ad-blocker is detected the player fires a 'adblock' event. This however does not prevent playback of content, it just notifies the publisher that a video ad-blocker has been detected.

adOnAdBlockPreventPlayback: Boolean

When enabled, this setting will prevent playback of content when a video ad-blocker is detected and present a viewer with a message: 'AdBlock detected' and 'Our website needs to show advertisement to our viewers - please allow ads on our website' (in the appropriate language for the viewer). A button will also be shown allowing the viewer to reload page after having disabled the ad-blocker. The message can be customized through the hint.ads.adBlockDetectedMessage and hint.ads.adBlockMessageMessageExtended player labels. Default: false.

Ad skipping

Offering ad skipping options to your audience is a great way to monetise your content while providing a gentle and smart advertisement experience. Radiant Media Player supports ad skipping in the following way: VAST 3+ skippable video ads. When a valid VAST 3+ tag with skippable information (e.g. skip information are held within the VAST XML response) is presented to the player, it will automatically read that information and display a skip button when appropriate in the advertisement UI. This is available for the Google IMA and our rmp-vast - no extra configuration is required.

Using Google IMA HTML5 SDK in a Ionic, Flutter, Apache Cordova, WebView or Electron application

It is to be noted that the Google IMA HTML5 SDK does not officially support being used in a Ionic, Flutter, Apache Cordova, WebView or Electron application (iOS, Android or Desktop native apps). As such the preferred solution is to use our VAST manager rmp-vast in such environments. The choice of VAST parser is made through the adParser player setting.

The following limitations should be noted when still using the Google IMA HTML5 SDK in an Ionic, Flutter, Apache Cordova, WebView or Electron application:

  • Poster rendering issues on Android (disgraceful play button as a background in ad player)
  • Click handling issues on iOS

The following limitations should be noted when using the IMA SDK in an Electron app:

  • Loading the IMA SDK in an Electron view where the FILE protocol is used will generate the following warning:
    Electron Security Warning (Insecure Resources) This renderer process loads resources using insecure protocols. This exposes users of this app to unnecessary security risks. Consider loading the following resources over HTTPS or FTPS. - http://imasdk.googleapis.com/js/core/bridge3.214.1_en.html#goog_1479432718.
    => As a workaround you may consider loading your player in a HTTPS-based <webview> tag or BrowserView.

CCPA Preparation

Information on how to properly comply with the California Consumer Privacy Act (CCPA) in conjunction to using Googe IMA can be found here.

Requesting Consent from European Users (GDPR)

Information on how to properly request consent from european users in conjunction to using Googe IMA can be found here.

Except as otherwise noted, the content of this page is licensed under the Creative Commons Attribution 3.0 License.

©2015-2025 Radiant Media Player. All Rights Reserved.