Documentation

360° video

Offline storage & playback

Video Ads API With Google IMA HTML5 SDK

Sections

Introduction
Usage example
Events
Methods
Error management
Implementation examples

Introduction

In order to create a custom ad experience and maximise 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.

Usage example

<!-- Include Radiant Media Player JavaScript file in your <body> or <head> -->
<script src="https://cdn.radiantmediatechs.com/rmp/9.1.1/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: src,
  width: 640,
  height: 360,
  ads: true,
  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'
  };
  // Your player settings
  const settings = {
    licenseKey: 'your-license-key',
    src: src,
    width: 640,
    height: 360,
    ads: true,
    adTagUrl: 'https://www.radiantmediaplayer.com/vast/tags/inline-linear.xml',    
    contentMetadata: {
      poster: [
        'https://your-poster-url.jpg'
      ]
    },
    asyncElementID: 'rmp'
  };
  // We push the 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.1.1/js/rmp.min.js"></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

adparserloaderror

Fires when the Google IMA SDK 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.

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.

loadAds(adTag)

rmp.loadAds(adTag);

This method tells the player to load a new ad at the input adTag URL parameter. We recommend using fully qualified URLs over relative/absolute path. The ad will immediately be played once loaded. Proper disposal of previously running ads is automatically done through this method when needed.

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

skipAd()

rmp.skipAd();

This method orders the player to skip the currently displayed ad (and to resume content). This method only has effects if the ad is a skippable ad and is in a state where it can be skipped. Once may query the getAdSkippableState API method to know if an ad can be skipped or not.

getAdSkippableState()

rmp.getAdSkippableState();

This method returns a Boolean stating if the ad on stage can be skipped (returns true) or not (returns false).

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

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.

getAdsManager()

rmp.getAdsManager();

This method 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.getAdsManager();
  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)

getAdLinear()

rmp.getAdLinear();

This method returns a Boolean stating if the current ad on stage is linear (true) or non-linear (false).

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

getAdParser()

rmp.getAdParser();

This method returns a String representing the ad parser being used. Possible values are 'ima' (default) or 'rmp-vast'.

getAdParserBlocked()

rmp.getAdParserBlocked();

This method returns a Boolean stating if the VAST parser (IMA or rmp-vast) has been blocked. Most of the time this is due to an ad-blocker but in less frequent case scenario this could also be due to network error/timeout. This method should be queried when the ready event fires.

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 API event.

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 API event.

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.

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.

getAdSkipTimeOffset()

rmp.getAdSkipTimeOffset();

Returns Number, the offset in seconds, or -1. The number of seconds of playback before the ad becomes skippable. -1 is returned for non skippable ads or if this is unavailable.

getAdUniversalAdIds()

rmp.getAdUniversalAdIds();

Returns Array of Object, the list of universal ad ID information that applies for this ad. Each object in the array is

{
  idRegistry: String,
  value: String
}

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.

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. This is the recommended way to determine if a loaded ad is a VPAID creative or not.

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.

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.
Usage example:

// rmp is a reference to the player instance
rmp.on('adstarted', () => {
  // We query getAdPodInfo when adstarted event fires
  const adPodInfo = rmp.getAdPodInfo();
  if (adPodInfo.getAdPosition) {
    // See https://developers.google.com/interactive-media-ads/docs/sdks/html5/v3/apis#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.

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.

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.

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.

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.

getAdSurveyUrl()

rmp.getAdSurveyUrl();

This method returns a String, the URL associated with the survey for the given ad. This value will only be available after the adstarted event.

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.

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.

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.

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.

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.

getAdWrapperCreativeIds()

rmp.getAdWrapperCreativeIds();

This method returns an Array of String representing the IDs of the ads' creatives, starting at the inline ad, or an empty array if there are no wrapper ads. This value will only be available after the adstarted event.

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 API 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 events and methods.

Ad error API events

aderror

Fires when the player has detected an error while trying to load or play the ad.

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

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

getAdErrorCode()

rmp.getAdErrorCode();

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

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.1.1/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,
    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.getAdErrorCode());
    console.log(rmp.getAdErrorMessage());
    console.log(rmp.getAdVastErrorCode());
  });
  rmp.init(settings);
</script>

Implementation examples

Complete demo with source code

Sections
Introduction
Usage example
Events
Methods
Error management
Implementation examples

Documentation

Video Ads API With Google IMA HTML5 SDK

Sections

Introduction

Usage example

Events

Methods

Error management

Ad error API events

Ad error API methods

Ad error API example

Implementation examples

Sections

Radiant Media Player

Support

Company

Documentation

Player

Accessibility

Streaming protocols

Live & DVR

Styling & branding

Related & playlist

Video Analytics

Mobile apps

OTT apps

eCDN (WebRTC-assisted streaming)

Video advertisement

DRM & HLSe

360° video

Google Cast & AirPlay

Offline

HTML5 audio

Guides & helpers

Video Ads API With Google IMA HTML5 SDK

Sections

Introduction

Usage example

Events

Methods

Error management

Ad error API events

Ad error API methods

Ad error API example

Implementation examples

Sections

Radiant Media Player

Support

Company