Documentation

Advertisement API with Google IMA

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.

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'
  };
  // 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>

Events

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.

Methods

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.

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.

Ad error API events

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.

Ad error API methods

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.

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,
    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>

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()

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.

Implementation examples

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. ✝