Radiant Media Player

Ads API



Last updated on July 21, 2017.


Introduction

In order to create a custom ad experience and maximise revenue with our player we provide a dedicated JavaScript ad API. It consists of events & methods to control the player while it renders video or audio ads.

This documentation page applies when using the Google IMA SDK with Radiant Media Player. For API methods and events when using rmp-vast go here.


Implementation example

Demo


Documentation


Using the ads API

This ad API comes as a complement to our player API.

Example:

<!-- Include Radiant Media Player JavaScript file in your <body> or <head> -->
<script src="https://cdn.radiantmediatechs.com/rmp/4.4.4/js/rmp.min.js" 
  integrity="sha384-KfgOHL+uRs3rPCnZledCYzAuPc3+eu4j6DQzjQH8370JtLm2QhZzZSlZ4r9OfCtK"
  crossorigin="anonymous"></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://dqwp3xzzbfhtw.cloudfront.net/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-linear.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.


Events

The below events are presented in alphabetical order.

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. Refer to the error management section to get more information about the error.

adfirstquartile

Fired when the ad playhead crosses first quartile

adimpression

Fired when the impression URL has been pinged

adinteraction

Fired when an ad triggers the interaction callback (VPAID AdInteraction event).

adlinearchanged

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

adloaded

Fired when ad data (e.g. creative) 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.

adlog

Fired when a non-fatal error is encountered. The user need not take any action since the player will continue with the same or next ad playback depending on the error situation. Refer to the error management section to get more information about the non-fatal error.

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): adloaded, adcontentpauserequested, adimpression, adstarted, adfirstquartile, admidpoint, adthirdquartile, adcomplete, adcontentresumerequested, adalladscompleted.


Methods

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

getAdTagUrl()
rmp.getAdTagUrl();

Returns the current adTag URL provided to the player. Works when adTagWaterfall and adSchedule are in use as well. null is returned in case this method is not available.

loadAds(adTag)
rmp.loadAds(adTag);

This method tells the player to load a new ad at the input URL parameter (must be a fully qualified URL). The ad will immediately be played once loaded. Proper disposal of previously running ads is automatically done through this method.

If you want to use the loadAds method to load a VMAP adTag after having changed the player content source (e.g. with the setSrc method) you must call loadAds when the srcchanged event fires. For other use-cases the loadAds should not be used to dynamically load VMAP adTag.

stopAds()
rmp.stopAds();

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

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 method is not available.

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.

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.

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.

getAdLinear()
rmp.getAdLinear();

This method returns a String representing the current ad type being played (possible values are 'linear' or 'nonlinear'). This value will only be available after the adloaded event. null is returned in case this method is not available.

getAdOnStage()
rmp.getAdOnStage();

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

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.

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.

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 method is not available.

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 method 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 method is not available.

getAdMediaHeight()
rmp.getAdMediaHeight();

This method returns a Number representing the current height in pixels of the displayed ad. This value will only be available after the adstarted event. null is returned in case this method is not available.

getAdMediaWidth()
rmp.getAdMediaWidth();

This method returns a Number representing the current width in pixels of the displayed ad. This value will only be available after the adstarted event. null is returned in case this method is not available.

getAdMediaUrl()
rmp.getAdMediaUrl();

This method returns a String representing the URL of the media file chosen from the ad based on the media selection settings currently in use. This value will only be available after the adstarted event. null is returned in case this value is not available.

getAdApiFramework()
rmp.getAdApiFramework();

This method returns a String representing the needed API framework for the ad (this corresponds to the apiFramework specified in VAST). This value will only be available after the adstarted event. null is returned in case this method is not available.

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 method is not available. For example JavaScript VPAID could return 'application/javascript'.

getAdPodInfo()
rmp.getAdPodInfo();

This method returns an Object representing the current ad's pod information. This is as per the HTML5 Google IMA SDK Interface google.ima.AdPodInfo. This value will only be available after the adstarted event. null is returned in case this method is not available.
Usage example:

// rmpContainer is a reference to the player container
rmpContainer.addEventListener('adstarted', function () {
  // We query getAdPodInfo when adstarted event fires
  var adPodInfo = rmp.getAdPodInfo();
  if (adPodInfo) {
    // adPodInfo is not null we can query its internal methods
    // See https://developers.google.com/interactive-media-ads/docs/sdks/html5/v3/apis#ima.AdPodInfo for more info
    console.log(adPodInfo.getAdPosition());
    console.log(adPodInfo.getIsBumper());
    console.log(adPodInfo.getMaxDuration());
    console.log(adPodInfo.getPodIndex());
    console.log(adPodInfo.getTimeOffset());
    console.log(adPodInfo.getTotalAds());
  }
});

Ad pod information shall be returned for each successfully started ad (VMAP or not) but those information are generally used with VMAP adTag.
Method added with version 4.0.10

getAdCreativeAdId()
rmp.getAdCreativeAdId();

This method returns a String representing the ISCI (Industry Standard Commercial Identifier) code for an ad, or empty string if the code is not found. This is the Ad-ID of the creative in the VAST response. This value will only be available after the adstarted event. null is returned in case this method is not available.

getAdCreativeId()
rmp.getAdCreativeId();

This method returns a String representing the ID of the selected creative for the ad. This value will only be available after the adstarted event. null is returned in case this method is not available.

getAdDealId()
rmp.getAdDealId();

This method returns a String representing the first deal ID present in the wrapper chain for the current ad, starting from the top. This value will only be available after the adstarted event. null is returned in case this method is not available.

getAdID()
rmp.getAdID();

This method returns a String, the ID of the ad, or an empty string if ID of the ad is not found. This value will only be available after the adstarted event. null is returned in case this method 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 value will only be available after the adstarted event. null is returned in case this method is not available.

getAdTraffickingParametersString()
rmp.getAdTraffickingParametersString();

This method returns a String representing trafficking parameters (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 will return an empty string when no trafficking parameters are found. This value will only be available after the adstarted event. null is returned in case this method is not available.

getAdUniversalAdIdRegistry()
rmp.getAdUniversalAdIdRegistry();

This method returns a String representing the registry associated with cataloging the UniversalAdId of the selected creative for the ad. 'unknown' is returned if this value is not found. This value will only be available after the adstarted event. null is returned in case this method is not available.

getUniversalAdIdValue()
rmp.getUniversalAdIdValue();

This method returns a String representing the UniversalAdId of the selected creative for the ad. 'unknown' is returned if this value is not found. This value will only be available after the adstarted event. null is returned in case this method is not available.

getAdvertiserName()
rmp.getAdvertiserName();

This method returns a String representing the advertiser name as defined by the serving party. This value will only be available after the adstarted event. null is returned in case this method is not available.

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 value will only be available after the adstarted event. null is returned in case this method is not available

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 value will only be available after the adstarted event. null is returned in case this method is not available

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

See our companion ads documentation page for examples and further documentation on companion ads.


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, VMAP ad pods ...) or resume content. You can obtain details about the error with the following methods.

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.