Radiant Media Player

Video ads documentation



Last updated on May 6, 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, 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, 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: 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 support

Radiant Media Player provides support for autoplay of pre-roll video ads with live, DVR & on-demand streaming. Autoplay of outstream video ads is also supported. General information and player settings for autoplay can be found here.

Here is our scope of support:

  • Desktop: full autoplay support
  • Mobile: muted autoplay of linear video ads support

An example of implementation can be found here.

With the release of iOS 10 and Chrome 53 on Android muted autoplay of HTML5 video has been introduced on mobile devices. Previously it was not possible to autoplay video content on iOS & Android even muted. Radiant Media Player has supported muted autoplay for content since the release of iOS 10 and Chrome 53 for Android. With the release of Google IMA SDK 3.164.0 we have also added muted autoplay support for video ads (version 4.0.19) on mobile devices. Autoplay with sound (e.g. not muted) is still not possible on iOS or Android as of March 2017 and we do not expect this to change in the near future.

We have built a specific feature-detection script within the player to detect autoplay support to help you provide a better user-experience and save bandwidth. Indeed it is not enough to have an eligible device that supports autoplay of video/ad. Changing device conditions and users settings can block autoplay on mobile or desktop devices. As such Radiant Media Player, by default, detects not only support for autoplay but also insures that the device is actually capable to do so at player runtime.

Our testing shows that muted autoplay of preroll inline video ads or video content works well on latest Safari & Chrome for iOS 10+ and latest Chrome & Firefox for Android. Browsers like Samsung Internet or Opera for Android do not seem to provide direct support for muted autoplay and as such those browsers are unlikely to support this feature.


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.

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.

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.

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.

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.
Setting added with version 4.0.23

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.
Setting added with version 4.0.23

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.

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.

adUseStyledLinearAds: Boolean

Render linear ads with full ad 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

Where the full ad UI styling is used (by default on mobile devices or on desktop with the adUseStyledLinearAds setting set to true) and when the control bar is not visible (idle) the player will display a watermark countdown and message for the currently playing linear video ad. Default: true. If set to true this setting will cause the adCountDown and labels.ads.controlBarCustomMessage information to not be visible within the control bar where the full ad UI styling is used to avoid redundancy.

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.

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

adPpid: String

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

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.