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.
<!-- 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' }; // Your player settings const settings = { licenseKey: 'your-license-key', src, width: 640, height: 360, ads: true, // This is a demo VAST tag - use your own 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>
The below events are presented in alphabetical order.
adadsmanagerloaded
Fires when the ads have been loaded and an AdsManager is available
adalladscompleted
Fires 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
Fires when the ad completes playing
adcontentpauserequested
Fires when content should be paused - this usually happens right before an ad is about to cover the content
adcontentresumerequested
Fires when content should be resumed. This usually happens when an ad finishes or collapses.
addurationchange
Fires when the ad duration changes
adfirstquartile
Fires when the ad playhead crosses first quartile
adimpression
Fires when the impression URL has been pinged
adinteraction
Fires when an ad triggers the interaction callback (VPAID AdInteraction event).
adlinearchanged
Fires when the displayed ad changes from linear to nonlinear, or vice versa
adloaded
Fires when ad data (e.g. creative) is available
admetadata
Fires when an ads list is loaded
admidpoint
The ad has reached 50% of its duration
adpaused
Fires when the ad is paused
adresumed
Fires when the ad is resumed
adskippablestatechanged
Fires when the displayed ads skippable state is changed
adskipped
Fires when the ad is skipped by the user
adstarted
Fires when the ad starts playing
adthirdquartile
The ad has reached 75% of its duration
aduserclose
Fires when the ad is closed by the user
adclientsidewaterfallrequested
Fires when the player tries to load a new VAST tag with the adTagWaterfall
setting
advolumechanged
Fires when the ad volume has changed
advolumemuted
Fires when the ad volume has been muted
adblock
Fires when an ad-blocker has been detected on the page
adprogress
Fires when there is an update to the current ad's progress
adbuffering
Fires when the ad has stalled playback to buffer
A successful display of a single inline linear video ad will generate the following chain of events (in that specific order): adloaded, adcontentpauserequested, adimpression, adstarted, adfirstquartile, admidpoint, adthirdquartile, adcomplete, adcontentresumerequested, adalladscompleted.
Advertisement API methods should only be called after the
player init
method has resolved or when ready
event has fired.
Some advertisement API methods may only return valid values
for the current advertisement upon adstarted
event - you need to wait for that event before
getting details about the selected creative
currentAdTagUrl
getter (String)
rmp.currentAdTagUrl;
This getter returns the current adTag URL provided to the player.
loadAds(adTag, adTagWaterfall)
Promise.<|WarningData>
rmp.loadAds(adTag, adTagWaterfall).then(() => {
console.log('loadAds was successful');
}).catch(warning => {
// something went wrong and the loadAds request was not successful
console.warn(warning);
});
This method tells the player to load a new VAST advertisement at the input adTag
URI
parameter. Returns a Promise that resolves if loadAds
request was successful or rejects to a
WarningData Object. This method also accepts a String[] adTagWaterfall
parameter to
enable client-side waterfalling when loadAds
is called. Note that advertisement will
immediately be played once loaded. Proper disposal of previously running ads is automatically managed
internally.
If you want to use the
loadAds
method to load a VMAP tag after having changed the player content
source (e.g. with the setSrc
method) you must call loadAds
when the
srcchanged
event fires.
stopAds()
Promise.<|WarningData>
rmp.stopAds().then(() => {
console.log('stopAds was successful');
}).catch(warning => {
// something went wrong and the stopAds request was not successful
console.warn(warning);
});
This method orders the player to stop playing the current advertisement (and to resume
content for a linear ad). Returns a Promise that resolves if stopAds
request was successful or
rejects to a WarningData Object.
skipAd()
Promise.<|WarningData>
rmp.skipAd().then(() => {
console.log('skipAd was successful');
}).catch(warning => {
// something went wrong and the skipAd request was not successful
console.warn(warning);
});
This method orders the player to skip the current advertisement (and to resume content). This method only has
effects if the advertisement is a skippable linear advertisement and is in a state where it can be skipped.
Returns a Promise that resolves if skipAd
request was successful or rejects to a WarningData
Object. You may query the adSkippableState
getter to know if an advertisement is skippable.
adSkippableState
getter (Boolean)
rmp.adSkippableState;
This getter returns a
Boolean
stating if the advertisement on stage can be skipped (true
) or not
(false
).
adPaused
getter (Boolean)
rmp.adPaused;
This getter returns a Boolean
representing the play state of the currently
playing linear advertisement.
true
means the advertisement on stage is paused.
pause()
rmp.pause();
This method orders the player to pause the currently playing content or linear advertisement.
play()
Promise.<|WarningData>
try {
await rmp.play();
console.log('play was successful');
} catch (warning) {
// something went wrong and the play request was not successful
console.warn(warning);
};
This method orders the player to play the currently paused content or linear advertisement. Returns a Promise
that resolves if play
request was successful or rejects to a WarningData Object.
volume
getter|setter (Number)
const volume = rmp.volume;
rmp.volume = 0.5;
get|set the current advertisement volume (between 0 and 1) when an advertisement is on stage. For
volume
getter, -1
is returned if current advertisement volume is not available.
adsManager
getter (Object)
rmp.adsManager;
This getter returns an
Object
, the ads manager provided by Google IMA. This method
should be querried when
adadsmanagerloaded
API event has fired. Example:
rmp.on('adadsmanagerloaded', () => { const adsManager = rmp.adsManager; const ima = window.google.ima; });
Note that the player internally manages Google IMA AdsManager, so this method should only be used as a supplement for custom use-cases (example: integration with 3rd-party viewability or verification service)
adLinear
getter (Boolean)
rmp.adLinear;
This getter returns a Boolean
stating if the current advertisement on stage is linear (true) or
non-linear (false).
adOnStage
getter (Boolean)
rmp.adOnStage;
This method returns a
Boolean
representing whether or not an advertisement is present on stage.
adUI
getter|setter (Boolean)
const adUI = rmp.adUI;
rmp.adUI = true;
get|set player advertisement UI.
For adUI
getter: true
means the advertisement UI is visible.
adCurrentTime
getter (Number)
rmp.adCurrentTime;
This getter returns a Number
representing the current time within the currently
playing linear advertisement in milliseconds. -1
is returned in case this value is not available.
adDuration
getter (Number)
rmp.adDuration;
This getter returns a Number
representing the duration of the currently playing
linear advertisement in milliseconds.
-1
is returned in case this value is not available.
adParserConfiguration
getter (String)
rmp.adParserConfiguration;
This getter returns a
String
representing the ad parser being used. Possible
values are 'ima'
or 'rmp-vast'
.
adTitle
getter (String)
rmp.adTitle;
This method returns a String
representing the title of the advertisement from the advertisement
response.
adDescription
getter (String)
rmp.adDescription;
This method returns a
String
representing the description of the advertisement from the advertisement response.
adSystem
getter (String)
rmp.adSystem;
This getter returns a String
representing the source advertisement server information
included in the advertisement response.
adMediaHeight
getter (Number)
rmp.adMediaHeight;
This method returns a
Number
representing the current height in pixels of the
displayed advertisement. null
is returned in case this method is not available.
adMediaWidth
getter (Number)
rmp.adMediaWidth;
This method returns a
Number
representing the current width in pixels of the
displayed advertisement. null
is returned in case this method is not available.
adSkipTimeOffset
getter (Number)
rmp.adSkipTimeOffset;
This getter returns Number
, the offset in seconds, or -1.
The number of seconds of playback before the advertisement becomes skippable.
-1 is returned if this method is unavailable.
adUniversalAdIds
getter (Object[])
rmp.adUniversalAdIds;
This getter returns an Object[], the list of universal ad ID information that applies for this advertisement. Each object in the returned array has the following properties:
{ idRegistry: String, value: String }
adMediaUrl
getter (String)
rmp.adMediaUrl;
This getter returns a String
representing the URL of the media file chosen from
the advertisement based on the media selection settings currently in use.
adApiFramework
getter (String)
rmp.adApiFramework;
This getter returns a
String
representing the needed API framework for the advertisement
(this corresponds to the apiFramework specified in VAST). This is the recommended way to determine if a loaded
ad is a VPAID creative or not.
adContentType
getter (String)
rmp.adContentType;
This getter returns a
String
representing the mime type for the current creative.
adPodInfo
getter (Object)
rmp.adPodInfo;
This getter returns an
Object
representing the current advertisement pod information. This Object
has the
following methods available: getAdPosition, getIsBumper, getMaxDuration, getPodIndex, getTimeOffset,
getTotalAds. This
is as per the HTML5 Google IMA SDK
Interface
google.ima.AdPodInfo.
Usage example:
// rmp is a reference to the player instance rmp.on('adstarted', () => { // We query adPodInfo when adstarted event fires const adPodInfo = rmp.adPodInfo; if (adPodInfo.getAdPosition) { // See https://developers.google.com/interactive-media-ads/docs/sdks/html5/client-side/reference/js/google.ima.AdPodInfo for more info console.log(adPodInfo.getAdPosition()); } });
Ad pod information shall be returned for each successfully started ad (VMAP or not) but those information are generally used with VMAP adTag.
adCreativeAdId
getter (String)
rmp.adCreativeAdId;
This getter returns a String
representing the ISCI (Industry Standard Commercial
Identifier) code for an advertisement, or empty string if the code is
not found. This is the Ad-ID of the creative in the VAST response.
adCreativeId
getter (String)
rmp.adCreativeId;
This getter returns a String
representing the ID of the selected creative for the
advertisement.
adDealId
getter (String)
rmp.adDealId;
This getter returns a
String
representing the first deal ID present in the
wrapper chain for the
current advertisement, starting from the top.
adID
getter (String)
rmp.adID;
This getter returns a String
, the ID of the advertisement, or an empty string if ID of the
advertisement is not found.
adSurveyUrl
getter (String)
rmp.adSurveyUrl;
This getter returns a String
, the URL associated with the survey for the given
advertisement.
adTraffickingParameters
getter (Object)
rmp.adTraffickingParameters;
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 advertisement at the time of advertisement trafficking).
adTraffickingParametersString
getter (String)
rmp.adTraffickingParametersString;
This getter returns a
String
representing trafficking parameters (gets custom
parameters associated
with the advertisement at the time of advertisement trafficking
- returns a raw string version of the parsed parameters from adTraffickingParameters
getter).
This method will return
an empty string when no trafficking parameters are found.
advertiserName
getter (String)
rmp.advertiserName;
This getter returns a
String
representing the advertiser name as defined by the
serving party.
adWrapperAdIds
getter (String[])
rmp.adWrapperAdIds;
This method returns String[] representing the IDs of the advertisement, starting with the first wrapper advertisement or an empty array if there are no wrapper advertisement (Ad IDs used for wrapper ads - the ids returned begin with the first wrapper ad and continue to each wrapped ad recursively).
adWrapperAdSystems
getter (String[])
rmp.adWrapperAdSystems;
This getter returns String[] representing the advertisement 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).
adWrapperCreativeIds
getter (String[])
rmp.adWrapperCreativeIds;
This getter returns String[] representing the IDs of the ads' creatives, starting at the inline advertisement, or an empty array if there are no wrapper advertisement.
getCompanionAds(companionAdSlotWidth, companionAdSlotHeight,
companionAdsOptions)
rmp.getCompanionAds(companionAdSlotWidth, companionAdSlotHeight, companionAdsOptions);
See our companion ads documentation page for examples and further documentation on companion ads.
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.
aderror
Fires when the player has detected an error while trying to load or play the advertisement.
adlog
Fires 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.
adErrorType
getter (String)
rmp.adErrorType;
This getter returns a String
, the type of ad 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 ...adErrorCode
getter (Number)
const adErrorCode = rmp.adErrorCode;
Returns a Number
or -1
if
not available. The detected error code.
adErrorMessage
getter (String)
const adErrorMessage = rmp.adErrorMessage;
This getter returns a String
, the message for the current ad error.
adVastErrorCode
getter (Number)
const adVastErrorCode = rmp.adVastErrorCode;
Returns a Number
or -1
if
not available. The VAST error code.
See
here for more
information.
<!-- 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, 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.adErrorCode); 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>
You can detect potential ad-blocker installed by the viewer with our adblock API
adblock
Fires when an ad-blocker is detected on page (requires ads: true setting to be set).
getAdBlock()
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.
©2015-2025 Radiant Media Player. All Rights Reserved. ✝