Radiant Media Player

Ad API with rmp-vast



Documentation sections


Introduction

To create a custom ad experience and maximize revenue we provide a dedicated JavaScript ad API. It consists of events & methods to control the player while it renders video or audio ads. The ad API comes as a complement to our player API and works in the same way. The rmp-vast Ad API is very similar in terms of methods and events to the IMA SDK Ad API but differs in some aspects described below.


Usage example

<!-- Include Radiant Media Player JavaScript file in your <body> or <head> -->
<script src="https://cdn.radiantmediatechs.com/rmp/5.0.7/js/rmp.min.js"></script>
<!-- Player container element -->
<div id="rmpPlayer"></div>
<!-- Set up player configuration options -->
<script>
// Streaming source - HLS in this example
var src = {
  hls: 'https://your-hls-url.m3u8'
};
// Player settings
var settings = {
  licenseKey: 'your-license-key',
  src: src,
  width: 640,
  height: 360,
  ads: true,
  adParser: 'rmp-vast',
  adTagUrl: 'https://www.radiantmediaplayer.com/vast/tags/inline-linear.xml',
  poster: 'https://your-poster-url.jpg'
};
var elementID = 'rmpPlayer';
var rmpContainer = document.getElementById('rmpPlayer');
var rmp = new RadiantMP(elementID);
// We attach our events and call our methods
rmpContainer.addEventListener('adloaded', function () {
  console.log('adloaded');
});
rmpContainer.addEventListener('adstarted', function () {
  console.log('adstarted');
  console.log(rmp.getDuration());
  console.log(rmp.getAdTitle());
});
rmpContainer.addEventListener('adclick', function () {
  console.log('adclick');
});
rmpContainer.addEventListener('aderror', function () {
  console.log('aderror');
});
// Initialization - only after API events are registered
rmp.init(settings);
</script>
<!-- Player container element -->
<div id="rmpPlayer"></div>
<!-- Set up async player configuration options -->
<script>
  // Streaming source - HLS in this example
  var src = {
    hls: 'https://your-hls-url.m3u8'
  };
  // Player settings
  var settings = {
    licenseKey: 'your-license-key',
    src: src,
    width: 640,
    height: 360,
    ads: true,
    adParser: 'rmp-vast',
    adTagUrl: 'https://www.radiantmediaplayer.com/vast/tags/inline-linear.xml',    
    poster: 'https://your-poster-url.jpg',
    asyncElementID: 'rmpPlayer'
  };
  // We push player settings to a global rmpAsyncPlayers variable
  if (typeof window.rmpAsyncPlayers === 'undefined') {
    window.rmpAsyncPlayers = [];
  }
  window.rmpAsyncPlayers.push(settings);
  // we wire our events on player container
  var rmpContainer = document.getElementById(settings.asyncElementID);
  var rmp = null;
  // To get access to the player instance we need to wait for rmpasyncplayerinstanceavailable event
  rmpContainer.addEventListener('rmpasyncplayerinstanceavailable', function () {
    // player instance is stored in a global array variable rmpAsyncPlayerInstances
    rmp = window.rmpAsyncPlayerInstances[0];
  });
  rmpContainer.addEventListener('adloaded', function () {
    console.log('adloaded');
  });
  rmpContainer.addEventListener('adstarted', function () {
    console.log('adstarted');
    if (rmp !== null) {
      console.log(rmp.getDuration());
      console.log(rmp.getAdTitle());
    }
  });
  rmpContainer.addEventListener('adclick', function () {
    console.log('adclick');
  });
  rmpContainer.addEventListener('aderror', function () {
    console.log('aderror');
  });
</script>
<script async src="https://cdn.radiantmediatechs.com/rmp/5.0.7/js/rmp.min.js"></script>

Events

Available events when using rmp-vast Ad API are:

  • adtagstartloading: VAST tag start loading
  • adtagloaded: VAST tag has loaded successfully
  • adfollowingredirect: start loading a wrapper Ad
  • addurationchange: duration change on the VAST HTML5 player
  • adloaded: creative loaded by the VAST HTML5 player
  • adimpression: fires when the impression URL has been pinged
  • adstarted: fires when the ad starts playing
  • adpaused: fires when the ad is paused
  • adresumed: fires when the ad is resumed
  • adskipped: fires when the ad is skipped by the user
  • adskippablestatechanged: fires when the displayed ads skippable state is changed
  • adfirstquartile: the ad has reached 25% of its duration
  • admidpoint: the ad has reached 50% of its duration
  • adthirdquartile: the ad has reached 75% of its duration
  • adcomplete: fires when the ad completes playing
  • adclick: the ad has been clicked. Note that when a linear or non-linear ad is clicked the ad/content is automatically paused (behavior can be set with adPauseOnClick setting). This does not apply to VPAID ads which are not paused (it is up to the VPAID ad to define what should be the behavior on click).
  • adclosed: fires when the ad is closed by the user
  • advolumemuted: fires when the ad volume has been muted
  • advolumechanged: fires when the ad volume has changed
  • addestroyed: fires when Ad instance has been cleared after it has completed or been in an aderror state
  • adinitialplayrequestsucceeded: the first play request has been successful on VAST HTML5 player
  • adinitialplayrequestfailed: the first play request has NOT been successful on VAST HTML5 player (likely due to autoplay restrictions)
  • adclientsidewaterfallrequested: fires when the player tries to load a new VAST tag with the adTagWaterfall setting
  • adpodcompleted: the current ad pod has finished playing all its Ad
  • adblockerdetected: this event fires when an ad-blocker has been detected. See our Ad-blocker detection docs for more info.

VPAID-related events

  • adlinearchange: fires when a change in linearity has been detected
  • adsizechange: fires when the VPAID ad unit resizes itself
  • adexpandedchange: fires when the VPAID ad unit expand state changes
  • adremainingtimechange: fires when the VPAID ad unit remaining time changes
  • adinteraction: fires when the VPAID ad unit is interacted with

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


Methods

See our GitHub page for more details about the below methods. Available methods when using rmp-vast are:

  • play
  • pause
  • getVolume
  • setVolume
  • getMute
  • setMute
  • loadAds
  • stopAds
  • getAdTagUrl
  • getAdOnStage
  • getAdPaused
  • getAdParser
  • getAdUI
  • setAdUI
  • getAdParserBlocked

The following methods should be queried after the adstarted event has fired for accurate data:

  • getAdMediaUrl
  • getAdLinear
  • getAdSystem
  • getAdContentType
  • getAdTitle
  • getAdDescription
  • getAdDuration
  • getAdCurrentTime
  • getAdMediaHeight
  • getAdMediaWidth
  • getAdPodInfo

Error management

When a fatal error is detected within the player while attempting to play or load an ad the aderror event will fire. This means that the current creative cannot be played (either due to a play error or a load error) and the player will either attempt to load the next available ad (waterfall, ad pods ...) or resume content. You can obtain details about the error with the following events and methods.

Ad error API events

  • aderror: the player has detected an error while trying to load or play the ad.
  • adloaderror: indicates that the error was encountered when the ad was being loaded. Possible causes: there was no response from the ad server, malformed ad response was returned ...
  • adplayerror: indicates that the error was encountered after the ad loaded, during ad play. Possible causes: ad assets could not be loaded, player received an Ad type that it was not expecting and/or cannot display ...
  • 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.

Ad error API methods

getAdErrorType()
rmp.getAdErrorType();

Returns a String, the type of this error. Possible values are:

  • adLoadError: Indicates that the error was encountered when the ad was being loaded. Possible causes: there was no response from the ad server, malformed ad response was returned or ad request parameters failed to pass validation.
  • adPlayError: Indicates that the error was encountered after the ad loaded, during ad play. Possible causes: ad assets could not be loaded ...
getAdErrorMessage()
rmp.getAdErrorMessage();

Returns a String, the message for this error.

getAdVastErrorCode()
rmp.getAdVastErrorCode();

Returns a Number or -1 if not available. The VAST error code. See here for more information.

Ad error API example

<!-- Include Radiant Media Player JavaScript file in your <body> or <head> -->
<script src="https://cdn.radiantmediatechs.com/rmp/5.0.7/js/rmp.min.js"></script>
<div id="rmpPlayer"></div>
<!-- Set up player configuration options -->
<script>
  // Streaming source - HLS in this example
  var src = {
    hls: 'https://your-hls-url.m3u8'
  };
  // Player settings
  var settings = {
    licenseKey: 'your-license-key',
    src: src,
    width: 640,
    height: 360, 
    ads: true,
    adParser: 'rmp-vast',
    adTagUrl: 'https://www.radiantmediaplayer.com/vast/tags/empty.xml',
    poster: 'https://your-poster-url.jpg'
  };
  var elementID = 'rmpPlayer';
  var rmp = new RadiantMP(elementID);
  var rmpContainer = document.getElementById(elementID);
  // We listen for the aderror event
  rmpContainer.addEventListener('aderror', function() {
    // The Ad error API methods must be queried in an aderror callback
    console.log(rmp.getAdErrorType());
    console.log(rmp.getAdErrorMessage());
    console.log(rmp.getAdVastErrorCode());
  });
  rmp.init(settings);
</script>
Except as otherwise noted, the content of this page is licensed under the Creative Commons Attribution 3.0 License.