Radiant Media Player

Video ads API



Last updated on January 4, 2017.

Features

Works with HTML5 and Flash video ads

Listen to up to ad-related events with JavaScript

Control video ads with JavaScript methods


Implementation example

Demo Source code


Documentation

HTML5 Flash

Using the video ads API

The video ads API is used like the player API by registering API events and calling API methods.

When tuning the player CSS you must self-host the player files or use a specific version of the cloud player - example for current version:

https://cdn.radiantmediatechs.com/rmp/3.10.14/js/rmp.min.js

Example:

<!-- Include Radiant Media Player JavaScript file in your <body> or <head> -->
<script src="https://cdn.radiantmediatechs.com/rmp/3.10.14/js/rmp.min.js"></script>
<!-- Set up your wrapper div with its unique id -->
<div id="rmpPlayer"></div>
<!-- Set up player configuration options -->
<script>
// First we specify bitrates to feed to the player
var bitrates = {
  hls: 'https://streamingrmp-1479.kxcdn.com/vod/smil:bbb.smil/playlist.m3u8'
};
// Then we set our player settings
var settings = {
  licenseKey: 'your-license-key',
  bitrates: bitrates,  
  delayToFade: 3000,
  width: 640,
  height: 360,
  ads: true,
  adTagUrl: 'https://www.radiantmediaplayer.com/vast/tags/inline.xml',
  poster: 'https://www.radiantmediaplayer.com/images/poster-rmp-showcase.jpg'
};
// Reference to the player container
var elementID = 'rmpPlayer';
var rmpContainer = document.getElementById('rmpPlayer');
// Create an object based on RadiantMP constructor
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 ... test your page and done!
rmp.init(settings);
</script>

Only call the init player method after your events are registered.

The chain of events may change depending on the ad type being delivered (i.e. linear vs non-linear ...)

Events

The below events are presented in alphabetical order.
The following events have been added with version 3.8.8: addurationchange, adimpression, adlinearchanged, adskippablestatechanged, advolumechanged, advolumemuted, admetadata

adalladscompleted

Fired when the ads manager is done playing all the ads

adclick

The ad has been clicked. Note that when a linear or non-linear ad is clicked the ad/content is automatically paused. This does not apply to VPAID ads which are not paused (it is up to the VPAID ad to define what should be the behaviour on click).

adcomplete

Fired when the ad completes playing

adcontentpauserequested

Fired when content should be paused - this usually happens right before an ad is about to cover the content

adcontentresumerequested

Fired when content should be resumed. This usually happens when an ad finishes or collapses.

addurationchange

Fired when the ad's duration changes

aderror

The player has detected an error loading or playing the ad

adfirstquartile

Fired when the ad playhead crosses first quartile

adimpression

Fired when the impression URL has been pinged

adlinearchanged

Fired when the displayed ad changes from linear to nonlinear, or vice versa

adloaded

Fired when ad data is available

adloadererror

The player could not retrieve the required IMA SDK JavaScript file to display the ads (this file is hosted by Google). This shall happen mainly in two case scenarios: there was a network issue preventing the download of the file or the viewer is using an ad-blocker system that is blocking the delivery of this file.

admanagerloaded

The adsManager has successfully been loaded into the player (after init or loadAds)

admetadata

Fired when an ads list is loaded

admidpoint

The ad has reached 50% of its duration

adpaused

Fired when the ad is paused

adresumed

Fired when the ad is resumed

adskippablestatechanged

Fired when the displayed ads skippable state is changed

adskipped

Fired when the ad is skipped by the user

adstarted

Fired when the ad starts playing

adthirdquartile

The ad has reached 75% of its duration

aduserclose

Fired when the ad is closed by the user

advolumechanged

Fired when the ad volume has changed

advolumemuted

Fired when the ad volume has been muted

Not all events are fired for a given type of ad (i.e. linear vs. non-linear ...)

The order in which events are fired may depend on the type of ad being played (VPAID, VMAP, overlays ...)

A successful display of a single inline linear video ad will generally generate the following chain of events (in that order): admanagerloaded, adloaded, adcontentpauserequested, adimpression, adstarted, adfirstquartile, admidpoint, adthirdquartile, adcomplete, adcontentresumerequested, adalladscompleted.

Methods

Video ads API methods should be invoked only after the player ready event has fired.

getAdApiFramework()
rmp.getAdApiFramework();

This method returns a String representing the needed API framework for the ad (this corresponds to the apiFramework specified in VAST), or null if this information is unavailable.
This method has been added with version 3.8.8

getAdContentType()
rmp.getAdContentType();

This method returns a String representing the mime type for the current creative. This value will only be available after the adstarted event. Null is returned in case this value is not available. For example Flash VPAID could return 'application/x-shockwave-flash' and JS VPAID could return 'application/javascript'.

getAdCurrentTime()
rmp.getAdCurrentTime();

This method returns a Number representing the current time within the currently playing linear ad in milliseconds. The getAdCurrentTime method should be queried after the adstarted event has fired. -1 is returned in case this value is not available.
This method has been added with version 3.8.7

getAdDescription()
rmp.getAdDescription();

This method returns a String representing the description of the ad from the ad response. This value will only be available after the adstarted event. Null is returned in case this value is not available.

getAdDuration()
rmp.getAdDuration();

This method returns a Number representing the duration of the currently playing linear ad in milliseconds. The duration of the ad will only be available when the adstarted event fires. -1 is returned in case this value is not available.

getAdID()
rmp.getAdID();

This method returns a String, the ID of the ad, or an empty string if this information is unavailable.
This method has been added with version 3.8.8

getAdLinear()
rmp.getAdLinear();

This method returns a String representing the current video ads type being played ('linear' or 'nonlinear'). Null is returned in case this value is not available.

getAdMediaHeight()
rmp.getAdMediaHeight();

This method returns a Number representing the current height in pixels of the displayed ad. Null is returned in case this value is not available.
This method has been added with version 3.8.8

getAdMediaWidth()
rmp.getAdMediaWidth();

This method returns a Number representing the current width in pixels of the displayed ad. Null is returned in case this value is not available.
This method has been added with version 3.8.8

getAdOnStage()
rmp.getAdOnStage();

This method returns a Boolean representing whether or not an ad (be it linear or non linear) is present on stage.

getAdPaused()
rmp.getAdPaused();

This method returns a Boolean representing the play state of the currently playing linear ad. true means the ad on stage is currently paused. Null is returned in case this value is not available.

getAdSystem()
rmp.getAdSystem();

This method returns a String representing the source ad server information included in the ad response. This value will only be available after the adstarted event. Null is returned in case this value is not available.

getAdTagUrl()
rmp.getAdTagUrl();

Returns the current adTag for the player. Works when adTagWaterfall and adSchedule are in use as well.
This method has been added with version 3.8.5

getAdTitle()
rmp.getAdTitle();

This method returns a String representing the title of the ad from the ad response. This value will only be available after the adstarted event. Null is returned in case this value is not available.

getAdTraffickingParameters()
rmp.getAdTraffickingParameters();

This method returns an Object representing a mapping of trafficking keys to their values, or the empty Object if this information is not available (gets custom parameters associated with the ad at the time of ad trafficking).
This method has been added with version 3.8.8

getAdTraffickingParametersString()
rmp.getAdTraffickingParametersString();

This method returns a String representing trafficking parameters, or the empty string if this information is not available (gets custom parameters associated with the ad at the time of ad trafficking - returns a raw string version of the parsed parameters from getAdTraffickingParameters).
This method has been added with version 3.8.8

getAdWrapperAdIds()
rmp.getAdWrapperAdIds();

This method returns an Array of String representing the IDs of the ads, starting with the first wrapper ad or an empty array if there are no wrapper ads (Ad IDs used for wrapper ads - the ids returned begin with the first wrapper ad and continue to each wrapped ad recursively).
This method has been added with version 3.8.8

getAdWrapperAdSystems()
rmp.getAdWrapperAdSystems();

This method returns an Array of String representing the ad system of the ads, starting with the first wrapper ad or an empty array if there are no wrapper ads (Ad systems used for wrapper ads - the ad systems returned begin with the first wrapper ad and continue to each wrapper ad recursively).
This method has been added with version 3.8.8

getCompanionAds(companionAdSlotWidth, companionAdSlotHeight, companionAdsOptions)
rmp.getCompanionAds(companionAdSlotWidth, companionAdSlotHeight, companionAdsOptions);

See our companion ads documentation page for examples and further documentation on this method.
This method has been added with version 3.6.4

getMute()
rmp.getMute();

This method returns a Boolean stating if the player is currently in mute mode or not.

getVolume()
rmp.getVolume();

This method returns a Number representing the current volume of the ad (between 0 and 1) when a linear ad is playing. -1 is returned in case this value is not available.

loadAds(adTag)
rmp.loadAds(adTag);

This method tells the player to load a new video ad at URL adTag. The ad will immediately be displayed and played once loaded. Proper disposal of previously running video ads is automatically done through this method.

Do NOT use the loadAds method to dynamically load VMAP adTag. VMAP is not intended to be used as such.

pause()
rmp.pause();

This method orders the player to pause the currently playing linear ad.

play()
rmp.play();

This method orders the player to play the currently paused linear ad.

setMute(muted)
rmp.setMute(true);

When invoked, this method will cause the player to enter or exit mute mode based on the input parameter. muted parameter should be a Boolean with true meaning the mute mode should be engaged and false the mute mode should be disengaged.

setVolume(newVolume)
rmp.setVolume(0.5);

This method sets the volume of the currently playing linear ad. Input value must be a Number between 0 and 1.

stopAds()
rmp.stopAds();

This method orders the player to stop playing the currently displayed video ads (and to resume content for a linear ad).

In Flash for an adPod within a VMAP adTag all ads from the pod will be skipped when calling the stopAds method.

Error management

When a fatal error is detected within the player while attempting to play a video 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, VMAP ad pods ...) or resume content. You can obtain details about the error with the following methods. Those methods work in HTML5 and Flash.

getAdErrorType()
rmp.getAdErrorType();

Returns a String or null if not available. 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 ...
getAdErrorCode()
rmp.getAdErrorCode();

Returns a Number or null if not available. The detected error code.

getAdErrorMessage()
rmp.getAdErrorMessage();

Returns a String or null if not available. The message for this error.

getAdVastErrorCode()
rmp.getAdVastErrorCode();

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

Except as otherwise noted, the content of this page is licensed under the Creative Commons Attribution 3.0 License.