Documentation

Advertisement API with rmp-vast

Introduction

To create custom video advertisement experiences and maximise revenue we provide a dedicated JavaScript advertisement API. It consists of player API events & methods to control the player while it renders advertisement. Read here for a quick start guide on using our player API.

The rmp-vast advertisement API is very similar in terms of methods and events to the Google IMA advertisement 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/10.1.4/js/rmp.min.js"></script>
<!-- Player container element -->
<div id="rmp"></div>
<!-- Set up 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,
    width: 640,
    height: 360,
    ads: true,
    // This is a demo VAST tag - use your own
    adParser: 'rmp-vast',
    adTagUrl: 'https://www.radiantmediaplayer.com/vast/tags/inline-linear.xml',
    contentMetadata: {
      poster: [
        'https://your-poster-url.jpg'
      ]
    }
  };
  const elementID = 'rmp';
  const rmp = new RadiantMP(elementID);
  // We attach our events and call our methods
  rmp.on('adloaded', () => {
    console.log('adloaded');
  });
  rmp.on('adstarted', () => {
    console.log('adstarted');
    console.log(rmp.duration);
    console.log(rmp.adTitle);
  });
  rmp.on('adclick', () => {
    console.log('adclick');
  });
  rmp.on('aderror', () => {
    console.log('aderror');
  });
  // Initialization - only after API events are registered
  // Initialization ... and done!
  async function initRmpPlayer() {
    try {
      await rmp.init(settings);
    } catch(error) {
      console.error('Radiant Media Player failed to initialize', error);
    }
  }
  initRmpPlayer();
</script>

API 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
  • 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
  • adblock: fires when an ad-blocker has been detected on the page

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
  • adprogress: fires when there is an update to the current ad's progress
  • adbuffering: fires when the ad has stalled playback to buffer

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.

API methods|getter|setter

Available API methods when using rmp-vast are:

  • adParserConfiguration
  • vpaidCreative
  • adLinear
  • adOnStage
  • linearAdOnStage
  • adSystem
  • adContentType
  • adTitle
  • adDescription
  • adMediaUrl
  • adMediaHeight
  • adMediaWidth
  • adCurrentTime
  • adDuration
  • adPaused
  • currentAdTagUrl
  • loadAds
  • stopAds
  • skipAd
  • adScheduleConfiguration
  • adSkippableState
  • adSkipTimeOffset
  • adUI
  • adPodInfo
  • adUniversalAdIds
  • advertiserName
  • adSurveyUrl
  • getCompanionAds
  • getAdBlock
  • adErrorMessage
  • adVastErrorCode
  • adErrorType
  • adErrorCode
  • adErrorMessage
  • adVastErrorCode

Error management

When an advertisement error is detected in the player, while attempting to play or load a VAST tag, the aderror API event will fire. This means that the current creative cannot be played (either due to a playback error or a network error) and the player will either attempt to load the next available advertisement (waterfall, VMAP, pods ...) or resume content. Note that this is not a fatal error to the player that can generally resume content when an advertisement error happens. You can obtain details about the error with the following events and methods.

Advertisement error API events

  • aderror: the player has detected an error while trying to load or play the advertisement.

Advertisement error API methods

adErrorType getter (String)

rmp.adErrorType;

This getter returns a String, the type of this advertisement 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 ...

adErrorMessage getter (String)

rmp.adErrorMessage;

This getter returns a String, the message for the current advertisement error.

adVastErrorCode getter (Number)

rmp.adVastErrorCode;

This getter returns a Number, the VAST error code, or -1 if not available. 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/10.1.4/js/rmp.min.js"></script>
<div id="rmp"></div>
<!-- Set up 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,
    width: 640,
    height: 360, 
    ads: true,
    // This is a demo VAST tag - use your own
    adParser: 'rmp-vast',
    adTagUrl: 'https://www.radiantmediaplayer.com/vast/tags/empty.xml',
    contentMetadata: {
      poster: [
        'https://your-poster-url.jpg'
      ]
    }
  };
  const elementID = 'rmp';
  const rmp = new RadiantMP(elementID);
  // We listen for the aderror event
  rmp.on('aderror', () => {
    // The Ad error API methods must be queried in an aderror callback
    console.log(rmp.adErrorType);
    console.log(rmp.adErrorMessage);
    console.log(rmp.adVastErrorCode);
  });
  // Initialization ... and done!
  async function initRmpPlayer() {
    try {
      await rmp.init(settings);
    } catch(error) {
      console.error('Radiant Media Player failed to initialize', error);
    }
  }
  initRmpPlayer();
</script>

Ad blocker detection API

You can detect potential ad-blocker installed by the viewer with our adblock API

Adblock API event

adblock

Fires when an ad-blocker is detected on page (requires ads: true setting to be set)

Adblock API methods

getAdBlock() Promise.<|WarningData>

try {
  const adBlockDetected = await rmp.getAdBlock();
  if (adBlockDetected) {
    console.log('ad-blocker detected - do plan B');
  } else {
    console.log('ad-blocker NOT detected - do plan A');
  }
} catch(warning) {
  // getAdBlock requested but ads setting is false and this is not a AWS Media Tailor stream
  console.warn(warning);
}

Returns Promise, resolves to Boolean indicating if an ad-blocker has been detected (true) or not (false). Rejects when getAdBlock is called but ads setting is false and this is not a AWS Media Tailor stream.

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-2025 Radiant Media Player. All Rights Reserved. ✝