Radiant Media Player

Video ads with Google IMA SDK



Last updated on July 21, 2017.


Documentation sections:

This documentation page applies when using the Google IMA 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.4.4/js/rmp.min.js" 
  integrity="sha384-KfgOHL+uRs3rPCnZledCYzAuPc3+eu4j6DQzjQH8370JtLm2QhZzZSlZ4r9OfCtK"
  crossorigin="anonymous"></script>
<!-- Set up your wrapper div with its unique id -->
<div id="rmpPlayer"></div>
<script>
// 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,  
  delayToFade: 3000,
  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);
rmp.init(settings);
</script>

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 Google IMA 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:


Supported IAB Video Suite


VAST/VMAP/VPAID support

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

  • Desktop: Chrome, Firefox, Safari 9+, Internet Explorer 11, MS Edge & Opera/Vivaldi
  • Mobile: Chrome, Firefox & Samsung Internet for Android 4.4+, Safari & Chrome for iOS 9+

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 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.


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
Radiant Media Player video ads implementation is based on Google IMA SDK. Hence the value for Access-Control-Allow-Origin should include: http://imasdk.googleapis.com or https://imasdk.googleapis.com based on the environment serving requesting the ad. More information on the subject can be obtained here.

Example of properly set response headers:

Access-Control-Allow-Credentials:true
Access-Control-Allow-Headers:Origin, X-Requested-With, Content-Type, Accept, Range
Access-Control-Allow-Origin:https://imasdk.googleapis.com

In Apache 2.4.* this can be achieved as follows:

SetEnvIfNoCase Origin "^https?:\/\/imasdk\.googleapis\.com$" ACAO=$0
Header set Access-Control-Allow-Origin %{ACAO}e env=ACAO
Header set Access-Control-Allow-Credentials true

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: ''.
You need to use fully qualified URL for your adTagUrl

adLocale: String

The targeted language for the ads UI provided by the IMA 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

A 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 may render in fullscreen mode. More information here. Default: true.

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.

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: 8000, which represents a 8 seconds timeout.

adLoadMediaTimeout: Number

Timeout (in milliseconds) when loading a ad media file. 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.

adAutoplayOnlyPreroll: Boolean

When set to true this setting will cause the preroll linear ad fed to the player to autoplay. Once the ad has finised it will not automatically resume content but instead it will display the player as if it was never started (e.g. at time 0, with poster and in a pause state). On modern mobile devices muted autoplay support is provided. If a non-linear ad is returned from the server this setting will cause content to autoplay to avoid discarding the ad. Default: false.

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.

adsResponse: String

Specifies a VAST document to be used as the ads response instead of making a request via adTagUrl. Using the adTagUrl setting is the recommended way to load ads with the player - only use adsResponse if you are trying to support a specific use-case or for testing purposes. adsResponse should be a string representing the VAST XML response. It must start with <?xml ... as with any XML compliant document. Default: ''.
This is not supported with the ad scheduler or the adTagWaterfall setting but the loadAds API method can also accept a string representing the VAST XML response.

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: ''.


AdTag Targeting Macros

DFP macros

Radiant Media Player is built on top of Google IMA SDK. As such all tag variables produced by the DFP server are supported.

Example of passing macros to the IMA SDK. Value for those macros will be replaced at runtime by the IMA SDK.

https://my-ad-server.com/vast.xml?sz=640x360&url=[referrer_url]&correlator=[timestamp]

VAST 3 macros

Sometimes ad servers would like to collect metadata from the player when tracking event URIs are accessed. This data cannot be built into the URI at the time the VAST response is built and served.

The following macros enable the player to provide certain details to the ad server at the time tracking URIs are accessed and are supported with Radiant Media Player:

  • [CACHEBUSTING]
  • [ERRORCODE]
  • [ASSETURI]

Currently not supported: [CONTENTPLAYHEAD]

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