Documentation

Video Ads API With rmp-vast

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/9.3.0/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: src,
  width: 640,
  height: 360,
  ads: true,
  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.getDuration());
  console.log(rmp.getAdTitle());
});
rmp.on('adclick', () => {
  console.log('adclick');
});
rmp.on('aderror', () => {
  console.log('aderror');
});
// Initialization - only after API events are registered
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,
    adParser: 'rmp-vast',
    adTagUrl: 'https://www.radiantmediaplayer.com/vast/tags/inline-linear.xml',    
    contentMetadata: {
      poster: [
        'https://your-poster-url.jpg'
      ]
    },
    asyncElementID: 'rmp'
  };
  // 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
  const rmpContainer = document.getElementById(settings.asyncElementID);
  let rmp = null;
  // To get access to the player instance we need to wait for rmpasyncplayerinstanceavailable event
  rmpContainer.addEventListener('rmpasyncplayerinstanceavailable', () => {
    // player instance is stored in a global array variable rmpAsyncPlayerInstances
    rmp = window.rmpAsyncPlayerInstances[0];
    rmp.on('adloaded', () => {
      console.log('adloaded');
    });
    rmp.on('adstarted', () => {
      console.log('adstarted');
      if (rmp !== null) {
        console.log(rmp.getDuration());
        console.log(rmp.getAdTitle());
      }
    });
    rmp.on('adclick', () => {
      console.log('adclick');
    });
    rmp.on('aderror', () => {
      console.log('aderror');
    });
  });
</script>
<script async src="https://cdn.radiantmediatechs.com/rmp/9.3.0/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
  • 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
  • adparserloaderror: fires when the rmp-vast library has failed to load. No ad will be render in such case. This would mainly be due to an ad-blocker or less often a network error.

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
  • getAdSkipTimeOffset
  • getAdvertiserName
  • getAdSurveyUrl
  • getAdUniversalAdIds

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.

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/9.3.0/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: src,
    width: 640,
    height: 360, 
    ads: true,
    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.getAdErrorType());
    console.log(rmp.getAdErrorMessage());
    console.log(rmp.getAdVastErrorCode());
  });
  rmp.init(settings);
</script>

Ad blocker detection API

You can detect potential ad-blocker installed by the viewer with our ad-block 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()

rmp.getAdBlock().then(() => {
  console.log('ad-blocker detected');
}).catch((e) => {
  console.log(e);
  console.log('no ad-blocker detected');
});

Returns Promise, resolves if ad-blocker detected, rejects otherwise.

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.