Documentation

Video Ads With rmp-vast

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 Google IMA SDK. The main purpose of rmp-vast is to offer a VAST 2, 3 and 4 compliant solution to display video ads in web-based mobile/OTT applications as Google HTML5 IMA SDK may not officially be compatible with those environments. rmp-vast can also be used in environments like desktop or mobile browsers.

Supported features with rmp-vast

rmp-vast supports the following VAST 4.2 features:

  • Inline and Wrapper Ads
  • Linear Ads
  • Skippable Linear Ads
  • Linear creatives in MP4/WebM progressive download
  • Linear creatives in HLS format on all supported devices (with hls.js) BETA
  • Non Linear Ads (image/iframe/HTML)
  • Companion Ads (image/iframe/HTML)
  • Tracking Events (tracking URLs must return an image - typically a 1px GIF/PNG/JPG)
  • Error Reporting
  • Industry Icons (image/iframe/HTML)
  • VAST 4.2 Macros
  • VPAID 1 and 2 JavaScript
  • Outstream ads
  • Ad Pods
  • Audio Ads (MP3/M4A/OGG/HLS where natively supported) in HTML5 video
  • ViewableImpression, Universal Ad ID, AdServingId, Survey and Ad Categories
  • AdVerifications OM Web SDK (only Creative Access Mode - e.g. full)

Note that VMAP and SIMID support with rmp-vast is not currently available. Radiant Media Player supports those features through Google IMA SDK.

Supported environments with rmp-vast

Browsers

  • Chrome, Firefox, Opera, Samsung Internet for Android 5+
  • Chrome, Firefox, Opera for Desktop
  • Safari 11+ for macOS
  • Safari for iOS 10+
  • MS Edge Legacy for Desktop
  • MS Edge 79+ for Desktop
  • Latest Amazon Silk for fireOS 6+

WebViews

  • Android 5+
  • iOS 10+

Smart TV & OTT

  • Samsung Tizen 3+ apps
  • LG webOS 3+ apps
  • Electron 6+ apps
  • Xbox One, Xbox Series S, Xbox Series X - UWP apps
  • Fire TV apps with fireOS 6+

Video ads from Google Ads network and rmp-vast

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

ADX & AdSense for Video ads may not render with rmp-vast. Google Ad Manager ads may render with rmp-vast but we cannot guarentee support for all Google Ad features. The choice of VAST parser is made through the adParser player setting.

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.

Here is a complete example:

<!-- Include Radiant Media Player JavaScript file in your <body> or <head> -->
<script src="https://cdn.radiantmediatechs.com/rmp/9.3.0/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'
  };
  // Player settings
  const settings = {
    licenseKey: 'your-license-key',
    src: src,
    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 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');
  rmp.init(settings);
</script>
<!-- Player container element -->
<div id="rmp"></div>
<!-- Set up async player configuration options -->
<script>
  // Streaming source - HLS in this example
  const src = {
    hls: 'https://your-hls-url.m3u8'
  };
  // Player settings
  const settings = {
    licenseKey: 'your-license-key',
    src: src,
    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 will attempt to load it upon startup
    adTagUrl: 'https://your-ad-tag-url',
    contentMetadata: {
      poster: [
        'https://your-poster-url.jpg'
      ]
    },
    // Here we pass the ID of the player container so that the core library may automatically initialize player when it finishes loading
    asyncElementID: 'rmp'
  };
  // We push the player settings to a global rmpAsyncPlayers variable
  if (typeof window.rmpAsyncPlayers === 'undefined') {
    window.rmpAsyncPlayers = [];
  }
  window.rmpAsyncPlayers.push(settings);
</script>
<script async src="https://cdn.radiantmediatechs.com/rmp/9.3.0/js/rmp.min.js"></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

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.

adParser: String

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

adForceNativeFullscreenOnIosForAds: Boolean

Forces native fullscreen on iOS when video ads are enabled in the player. By default the player uses an emulated - full window - mode to allow for skippable ads to be played on iOS. Setting adForceNativeFullscreenOnIosForAds to true should only be used if you are sure that your inventory for mobile devices is not dominated by skippable video ads. Default: false.

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

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: 12000 which represents a 12 seconds timeout.

adAjaxWithCredentials: Boolean

AJAX request to load VAST tag from ad server should or should not be made with credentials. 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.

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.

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.

adCountDown: Boolean

A countdown to be displayed within the player control bar. It shows the remaining time for the video ads. 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.

OMID support (OM Web SDK)

We support OMID (OM Web SDK) with rmp-vast. This feature needs to be enabled as follows:

First adds the following libraries to your web page - those are required to enable OMID support in rmp-vast and are not bundled or automatically with the player:

<script src="https://cdn.radiantmediatechs.com/rmp/9.1.0/rmp-vast/omweb-js-1.4.2/Service/omweb-v1.js"></script>
<script src="https://cdn.radiantmediatechs.com/rmp/9.1.0/rmp-vast/omweb-js-1.4.2/Session-Client/omid-session-client-v1.js"></script>

Then enables OMID support in rmp-vast with setting adOmidSupport to true.

Note that we currently only support Creative Access Mode (e.g. full).

adOmidSupport: Boolean

Enables OMID support in rmp-vast. Default: false.

omidAllowedVendors: Array

List of allowed vendors for ad verification. Vendors not listed will be rejected. Example: ['com.vendor.aaa', 'com.vendor.bbb']. Default: [].

HLS creative support

This feature is a BETA feature - feedback is welcome!

We support displaying HLS creatives with rmp-vast and Radiant Media Player. This feature needs to be explicitly enabled with the adSupportHlsCreatives setting. First you need to add hls.js library to your page.

<script src="https://cdn.radiantmediatechs.com/rmp/9.1.0/hls/hls.min.js"></script>

Then set adSupportHlsCreatives setting to true.

adSupportHlsCreatives: Boolean

Enables display of HLS creatives with rmp-vast and Radiant Media Player. Default: false.

Player labels for rmp-vast

See our documentation about player labels here. 

const labels = {
  ads: {
    controlBarCustomMessage: 'Ad',
    skipMessage: 'Skip ad',
    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.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'

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 waterfalling through the adTagWaterfall setting with rmp-vast. See our ad waterfalling documentation for more information.

Companion ads

See the companion ads documentation for more information on how to retrieve companion ads information with rmp-vast.

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.

Radiant Media Player

Support

Company

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