Ad API with rmp-vast

Documentation sections

Introduction
Usage example
Events
Methods
Error management

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.2.1/js/rmp-vast.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.2.1/js/rmp-vast.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
skipAd
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
getAdSkippableState

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.2.1/js/rmp-vast.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.

Player

Streaming

Styling and branding

Live and DVR

Playlist & related content

Analytics

Social media

OTT

Ads

Outstream video ads

Server side ad insertion (SSAI)

Mobile applications

DRM & HLSe

360 video

Offline

HEVC, AV1, AC-3 & 4K video

HTML5 audio

Peer-to-peer streaming

Guides

Helpers