Radiant Media Player

Video ads with rmp-vast



rmp-vast documentation sections


Introduction to rmp-vast

rmp-vast is a lightweight open-source client-side JavaScript solution to load, parse and display VAST resources. It is maintained by Radiant Media Player team and is offered as an alternative to the Google IMA SDK. The main purpose of rmp-vast is to offer a VAST 3 compliant solution to display video ads in web-based mobile applications for iOS and Android (WebView, Ionic, PhoneGap, Cordova ...) as the Google HTML5 IMA SDK is not officially compatible with those environments. rmp-vast can also be used in environments like desktop or mobile browsers.

When delivering Google video ads (DoubleClick for Publishers, AdSense for Video or DoubleClick Ad Exchange) we recommend using the Google IMA SDK with Radiant Media Player whenever possible.


Supported features with rmp-vast

rmp-vast supports the following VAST 3 features:

  • Inline and Wrapper Ads
  • Linear Ads (MP4/WebM or HLS where natively supported)
  • Skippable Linear Ads (MP4/WebM or HLS where natively supported)
  • Non Linear Ads (Images)
  • Tracking Events
  • Error Reporting
  • Industry Icons
  • VAST 3 Macros
  • VPAID 1 and 2 JavaScript BETA

VAST 2 resources are also compatible with rmp-vast.

Additional supported features include a mobile friendly UI and autoplay support (muted autoplay on mobiles).

The following VAST/player features are currently not supported with rmp-vast: Ad Pods, Companion Ads, VMAP, Audio ads, outstream ads. Radiant Media Player supports those features through the Google IMA SDK.


Supported environments with rmp-vast

Browsers:

  • Chrome for Android 5+
  • Chrome for Desktop
  • Firefox for Android 5+
  • Firefox for Desktop
  • Safari 10+ for macOS
  • Safari for iOS 10+
  • MS Edge for Desktop
  • Internet Explorer 11+ for Desktop
  • Opera for Desktop
  • Vivaldi for Desktop

Specifically we support the latest stable release for each browser.

WebViews:

  • Android 5+
  • iOS 10+

It is fairly possible that rmp-vast would work in other environments but they are not officially supported.


CORS requirements

rmp-vast uses JavaScript XMLHttpRequests to load VAST tags. Hence proper CORS configuration is required on your ad-server in order for rmp-vast to be able to retrieve VAST tags. Refer to this Google documentation for more information.


Usage example

Player settings for using rmp-vast are very similar to using Google IMA SDK. The only difference resides in specifying the VAST parser which you want to use through the adParser setting.

<!-- Include Radiant Media Player JavaScript file in your <body> or <head> -->
<script src="https://cdn.radiantmediatechs.com/rmp/4.6.11/js/rmp.min.js" 
  integrity="sha384-9iFjOzbzaBqrr5wIQcHNGTcOU9sD/6mtFwlc8RIZS2yh8+dAD3Qobk3VxloK+us8"
  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,
  width: 640,
  height: 360,
  ads: true,
  // We tell the player to use rmp-vast to load and parse VAST resources
  adParser: 'rmp-vast',
  // We pass our adTag here - the player knows what to do with it
  adTagUrl: 'https://www.radiantmediaplayer.com/vast/tags/inline-linear-5.xml',
  poster: 'https://www.radiantmediaplayer.com/images/poster-rmp-showcase.jpg'
};
var elementID = 'rmpPlayer';
var rmp = new RadiantMP(elementID);
rmp.init(settings);
</script>

Player 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

adParser: String

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

adLoadVastTimeout: Number

Represents the Ajax timeout in milliseconds for each VAST request (or VAST wrapper). When timeout is reached without a valid server response the VAST loading process is aborted. Default: 7000.

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 content resumes. Default: 10000 which represents a 10 seconds timeout.

adAjaxWithCredentials: Boolean

AJAX request to load VAST tag from ad server should or should not be made with credentials. Default: false.

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.

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. On some devices the browser may still decide to pause a video asset when a new window opens.

adCountDown: Boolean

A countdwon to be displayed within the player control bar. It shows the remaining time for the video ads. Default: false.


Player labels for rmp-vast

See our documentation about player labels here.

var labels = {
  ads: {
    controlBarCustomMessage: 'Ad',
    skipMessage: 'Skip ad',
    skipWaitingMessage: 'Skip ad in',
    textForClickUIOnMobile: 'Learn more'
  }
};

labels.ads.skipMessage: the skip message to show on player when a skippable ad is detected and the ad is in a state where it can be skipped. Default: 'Skip ad'

labels.ads.skipWaitingMessage: the skip message to show on player when a skippable ad is detected and the ad is in a state where it cannot be skipped. Default: 'Skip ad in'. This will be completed by the number of seconds remaining before the ad state changes to a state where it can be skipped.

labels.ads.textForClickUIOnMobile: on mobile devices the click-through URL for a linear ad is provided in a box located at the top right corner of the player. This setting set the text for this box. Default: 'Learn more'.


rmp-vast API events

Events are registered as explained in our Ads API documentation. Available events when using rmp-vast are:

  • adtagstartloading
  • adtagloaded
  • adfollowingredirect
  • addurationchange
  • adloaded
  • adimpression
  • adstarted
  • adpaused
  • adresumed
  • adskipped
  • adskippablestatechanged
  • adfirstquartile
  • admidpoint
  • adthirdquartile
  • adcomplete
  • adclick
  • adclosed
  • advolumemuted
  • advolumechanged
  • aderror
  • addestroyed
  • adloadererror: the player could not retrieve the required rmp-vast library to display ads (this is either cloud-hosted on our servers or self-hosted on yours). Contrary to the IMA SDK which is well-known by ad-blockers, the rmp-vast library is not blocked by ad-blockers. So this event is very less likely to occur when using rmp-vast. This can also happen when a network error occurred while trying to get the rmp-vast library or while the player is used in an offline/local context.
  • adblockerdetected: this event fires when an ad-blocker has been detected. See our Ad-blocker detection docs for more info.

Assuming an Inline Linear video ad the chain of events should look like: adtagstartloading, adtagloaded, addurationchange, adloaded, adimpression, adstarted, adfirstquartile, admidpoint, adthirdquartile, adcomplete, addestroyed.


rmp-vast API methods

Ads API methods are described and queried as explained in Ads API documentation. Available methods when using rmp-vast are:

  • getAdLinear
  • getAdSystem
  • getAdContentType
  • getAdTitle
  • getAdDescription
  • getAdDuration
  • getAdMediaUrl
  • getAdMediaHeight
  • getAdMediaWidth
  • getAdCurrentTime
  • getAdOnStage
  • getAdPaused
  • getAdTagUrl
  • getAdParser
  • loadAds
  • stopAds
  • getAdUI
  • setAdUI
  • getAdErrorMessage
  • getAdVastErrorCode
  • play
  • pause
  • getVolume
  • setVolume
  • getMute
  • setMute
  • getAdBlockerDetected

Other general player API methods and events are also available.


Autoplay support

As when using the Google IMA SDK, autoplay of pre-roll linear video ads on desktop and muted autoplay on mobile devices are supported. Refer to our documentation about autoplay support for more information.


Ad scheduling

Since Radiant Media Player 4.5.1 we support ad scheduling with rmp-vast through our ad scheduler.


Ad waterfalling

VAST redirect / VAST Wrapper have always been supported with rmp-vast since it was made publicly available. Since Radiant Media Player 4.5.2 we also support ad wtaefalling through the adTagWaterfall setting with rmp-vast. See our ad waterfalling documentation for more information.


Ad Tag Variables & Macros

See the ad tag variables & macros documentation page.

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