Radiant Media Player

Video ads documentation



Last updated on March 14, 2017.


Documentation sections:


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/v4/latest/js/rmp.min.js"></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.


Google IMA SDK

Radiant Media Player ads implementation is based on the HTML5 Google IMA SDK v3. This allows us to support the latest IAB standards and to provide a rich video ads experience following best practices in the industry.


Supported ad-servers

You can make video ad requests to any VAST-compliant ad server with Radiant Media Player. Our customers have successfully used our player with DoubleClick for Publishers (DFP), the Google AdSense Network, SmartAdServer, StickyADS and more.


Supported IAB Video Suite


VAST/VMAP/VPAID support

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

Take a moment to read our deprecating Flash support article as Google has announced end of support for Flash in the IMA SDK and as Flash becomes rapidly deprecated in the industry.


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 for Android 4+, Safari for iOS 9+, MS Edge for Windows 10+ mobile

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, video/x-flv ...
  • Non-linear creatives: image/png, image/jpeg ...
  • VPAID creatives: application/javascript, application/x-shockwave-flash ...

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: imasdk.googleapis.com. More information on the subject can be obtained here.

Example of properly set HTTP CORS headers:

access-control-allow-credentials:true
access-control-allow-headers:Origin, X-Requested-With, Content-Type, Accept, Range
access-control-allow-origin:http://imasdk.googleapis.com

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

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

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

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 solve a specific problem. 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 custom ad scheduler or the adTagWaterfall setting but the loadAds API method can also accept a string representing the VAST XML response.

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.

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.

adUseStyledLinearAds: Boolean

Render linear ads with full UI styling on Desktop. This setting does not apply to AdSense/AdX ads. Ads played in a mobile context already use full UI styling by default (required for touch-compatibility). Default: false.

adUseStyledNonLinearAds: Boolean

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

adUseWatermarkCountdownAndMessage: Boolean

When the control bar is not visible (idle) the player will still display a watermark countdown and message for the currently playing linear video ad. Default: true.

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.

adSkipButton: Boolean

A skip button to be displayed when a linear creative is playing. Default: false.
Do not use this setting with VAST 3 skippable tags otherwise 2 skip buttons may appear on screen. This setting is for VAST tag that do not carry skip information within their body.
Do not use this setting with AdSense or Ad Exchange as most tags coming from those providers already include VAST 3 skip information.

adDelayBeforeSkip: Number

An offset expressed in seconds that represent the time before the custom skip button should be displayed. Default: 0.

adAutoplayOnlyPreroll: Boolean

When set to true this setting will cause the preroll linear ad fed to the player to autoplay on Desktop. 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 mobile devices ad cannot be autoplayed so this setting has no effect. However on iOS ad can be muted autoplayed. This setting is thus compatible with the mutedAutoplayOnMobile setting on iOS (Android support will come at a later stage). Default: false.

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.

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: -1 which represents a 15000 milliseconds (15 seconds) timeout.

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.

adLinearHideControls: Boolean

Setting adLinearHideControls to true causes the player UI to be hidden when a linear video ad is played. Note that for VPAID ads the control bar is always hidden (it is up to the VPAID ad to provide controls or not). Default: false.

adPlayAdsAfterTime: Number

For VMAP and ad rules playlists, only play ad breaks scheduled after this time (in seconds). This setting is strictly after - e.g. setting adPlayAdsAfterTime to 15 will cause the player to ignore an ad break scheduled to play at 15s. Default: 0.

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.

adDisableFlashAds: Boolean

Sets whether flash ads (VPAID) should be disabled in HTML5 player. Default: false.

adPpid: String

Sets the publisher provided id. This setting should only be used by the DFP audience. Default: ''.

adCompanionBackfill: String

Sets the companion backfill mode. Please see the various modes available here. Default: 'ALWAYS'. Other possible value is 'ON_MASTER_AD'. Must be passed in uppercase.

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.