Ads with the HTML5 Google IMA DAI SDK

Documentation sections:

Introduction
Supported environments for the DAI IMA HTML5 SDK
Player code example
Player settings
API events
API methods
Companion ads
Ad pods
iOS specific considerations

Introduction

With the release of Radiant Media Player 5.0.5, we support the HTML5 Google IMA DAI SDK (dynamic ad insertion). The Google IMA DAI SDK for HTML5 V3 allows publishers to request and track DAI streams in a HTML5 video environment with a server-side ad insertion angle (SSAI). We support both live and on-demand video streaming with the HTML5 Google IMA DAI SDK through HLS (hls.js based implementation).

Using the Google's dynamic ad insertion requires publishers to have an Ad Manager 360 account and an account manager.

You can test your DAI stream in our tester here.

Supported environments for the DAI IMA HTML5 SDK

Desktop: Chrome, Firefox, Safari 8+, Internet Explorer 11
Mobile: Chrome for Android 4.4+, Safari for iOS 9+

DAI streams may work in other environments with Radiant Media Player but they are not officially supported.

When version for a browser is not specified we support the latest version of this browser.

Player code example

DAI HLS VOD stream

<!-- Include Radiant Media Player JavaScript file in your <body> or <head> -->
<script src="https://cdn.radiantmediatechs.com/rmp/5.3.0/js/rmp.min.js"></script>
<!-- Player container element -->
<div id="rmpPlayer"></div>
<script>
  // Streaming source - in this case we specify a HLS source but we input a dummy URI
  var src = {
    hls: 'ima-dai'
  };
  // Player settings
  var settings = {
    licenseKey: 'your-license-key',
    src: src,
    width: 640,
    height: 360,
    ads: true,
    // enables IMA DAI support in Radiant Media Player
    adImaDai: true,
    // DAI VOD content source and video IDs
    adImaDaiVodContentSourceId: 'content-source-id',
    adImaDaiVodVideoId: 'video-id',
    // Backup HLS stream in case the DAI stream is not available when requested
    // Note that this is also the HLS stream that will be used on iOS since hls.js does not work on iOS
    adImaDaiBackupStream: 'https://backup-hls-stream.m3u8',
    // In macOS Safari we force hls.js usage to enable IMA DAI support
    forceHlsJSOnMacOSSafari: true,
    // ad label that can be displayed within player UI when an ad is on stage
    labels: {
      ads: {
        controlBarCustomMessage: 'Ads'
      }
    },
    poster: 'https://your-poster-url.jpg'
  };
  var elementID = 'rmpPlayer';
  var rmp = new RadiantMP(elementID);
  rmp.init(settings);
</script>

<!-- Player container element -->
<div id="rmpPlayer"></div>
<!-- Set up async player configuration options -->
<script>
  // Streaming source - HLS in this example
  var src = {
    hls: 'https://your-hls-url.m3u8'
  };
  // Player settings
  var settings = {
    licenseKey: 'your-license-key',
    src: src,
    width: 640,
    height: 360,
    ads: true,
    // enables IMA DAI support in Radiant Media Player
    adImaDai: true,
    // DAI VOD content source and video IDs
    adImaDaiVodContentSourceId: 'content-source-id',
    adImaDaiVodVideoId: 'video-id',
    // Backup HLS stream in case the DAI stream is not available when requested
    // Note that this is also the HLS stream that will be used on iOS since hls.js does not work on iOS
    adImaDaiBackupStream: 'https://backup-hls-stream.m3u8',
    // In macOS Safari we force hls.js usage to enable IMA DAI support
    forceHlsJSOnMacOSSafari: true,
    // ad label that can be displayed within player UI when an ad is on stage
    labels: {
      ads: {
        controlBarCustomMessage: 'Ads'
      }
    },
    poster: 'https://your-poster-url.jpg',
    // Here we pass the ID of the player container so that the core library may automatically initialise player when it finishes loading
    asyncElementID: 'rmpPlayer'
  };
  // We push the player settings to a global rmpAsyncPlayers variable
  if (typeof window.rmpAsyncPlayers === 'undefined') {
    window.rmpAsyncPlayers = [];
  }
  window.rmpAsyncPlayers.push(settings);
</script>
<script async src="https://cdn.radiantmediatechs.com/rmp/5.3.0/js/rmp.min.js"></script>

DAI HLS live stream

<!-- Include Radiant Media Player JavaScript file in your <body> or <head> -->
<script src="https://cdn.radiantmediatechs.com/rmp/5.3.0/js/rmp.min.js"></script>
<!-- Player container element -->
<div id="rmpPlayer"></div>
<script>
  // Streaming source - in this case we specify a HLS source but we input a dummy URI
  var src = {
    hls: 'ima-dai'
  };
  // Player settings
  var settings = {
    licenseKey: 'your-license-key',
    src: src,
    width: 640,
    height: 360,
    // enables live UI and optimisations
    isLive: true,
    ads: true,
    // enables IMA DAI support in Radiant Media Player
    adImaDai: true,
    // DAI Live stream asset key
    adImaDaiLiveAssetKey: 'live-asset-key',
    // Backup HLS stream in case the DAI stream is not available when requested
    // Note that this is also the HLS stream that will be used on iOS since hls.js does not work on iOS
    adImaDaiBackupStream: 'https://backup-hls-stream.m3u8',
    // In macOS Safari we force hls.js usage to enable IMA DAI support
    forceHlsJSOnMacOSSafari: true,
    // ad label that can be displayed within player UI when an ad is on stage
    labels: {
      ads: {
        controlBarCustomMessage: 'Ads'
      }
    },
    poster: 'https://your-poster-url.jpg'
  };
  var elementID = 'rmpPlayer';
  var rmp = new RadiantMP(elementID);
  rmp.init(settings);
</script>

Player settings

ads: Boolean

Activate or not ads within the player. Default: false.

adImaDai: Boolean

Enables HTML5 Google IMA DAI SDK support in Radiant Media Player. Default: false.

adImaDaiVodContentSourceId: String

DAI VOD content source id. Default: ''.

adImaDaiVodVideoId: String

DAI VOD video id. Default: ''.

adImaDaiLiveAssetKey: String

DAI live stream asset key. Default: ''.

adImaDaiApiKey: String

The DAI stream request API key. It's configured through the DFP Admin UI and provided to the publisher to unlock their content. It verifies the applications that are attempting to access the content. Default: ''.

adImaDaiBackupStream: String

Backup HLS stream in case the DAI stream is not available when requested. Where hls.js is not available (iOS) this will be used as default HLS stream. Default: ''.

adImaDaiAdTagParameters: Object

You can override a limited set of ad tag parameters on your DAI stream request. See here for more information. Default: {}.

adImaDaiStreamActivityMonitorId: String

The ID to be used to debug the stream with the stream activity monitor. This is used to provide a convenient way to allow publishers to find a stream log in the stream activity monitor tool. Default: ''.

Other generic ad-related settings may also work with our IMA DAI implementation, including: adCountDown, autoplay, labels, labels, adPauseOnClick, adBlockerDetection

API events

adstreaminitialized: Fires when the DAI stream is initialized.
adloaded: Fires when the DAI stream manifest is available.
aderror: Fires when the DAI stream fails to load - if a backup stream is provided it will be loaded.
adbreakstarted: Fires when an ad break starts.
adbreakended: Fires when an ad break ends.
adprogress: Fires when there is an update to an ad's progress.
adcuepointschanged: Dispatched for on-demand streams when the cuepoints change.
adclick: Dispatched when the click element is clicked or tapped while an ad is being played.
adstarted: Fires when an ad starts.
adfirstquartile: Fires when an ad reaches its first quartile.
admidpoint: Fires when an ad reaches its midpoint.
adthirdquartile: Fires when an ad reaches its third quartile.
adcomplete: Fires when an ad is complete.

API methods

play
pause
getVolume
setVolume
getMute
setMute
getAdOnStage
getAdPaused
getAdLinear
getAdSystem
getAdTitle
getAdDescription
getAdMediaWidth
getAdMediaHeight
getAdDuration
getAdPodInfo
getAdID
getAdvertiserName
getAdApiFramework
getAdCreativeId
getAdCreativeAdId
getAdDealId
getAdWrapperAdIds
getAdWrapperAdSystems
getAdWrapperCreativeIds
getCompanionAds
getAdParser
getAdUI
setAdUI
getAdParserBlocked

Advanced documentation for the above methods can be found here.

Companion ads

Below is an example of companion ads retrieval through our player API:

<!-- Include Radiant Media Player JavaScript file in your <body> or <head> -->
<script src="https://cdn.radiantmediatechs.com/rmp/5.3.0/js/rmp.min.js"></script>
<!-- Player container element -->
<div id="rmpPlayer"></div>
<!-- Our companion div -->
<div id="companionDiv"></div>
<script>
  // Streaming source - in this case we specify a HLS source but we input a dummy URI
  var src = {
    hls: 'ima-dai'
  };
  // Player settings
  var settings = {
    licenseKey: 'your-license-key',
    src: src,
    width: 640,
    height: 360,
    ads: true,
    // enables IMA DAI support in Radiant Media Player
    adImaDai: true,
    // DAI VOD content source and video IDs
    adImaDaiVodContentSourceId: 'content-source-id',
    adImaDaiVodVideoId: 'video-id',
    // Backup HLS stream in case the DAI stream is not available when requested
    // Note that this is also the HLS stream that will be used on iOS since hls.js does not work on iOS
    adImaDaiBackupStream: 'https://backup-hls-stream.m3u8',
    // In macOS Safari we force hls.js usage to enable IMA DAI support
    forceHlsJSOnMacOSSafari: true,
    // ad label that can be displayed within player UI when an ad is on stage
    labels: {
      ads: {
        controlBarCustomMessage: 'Ads'
      }
    },
    poster: 'https://your-poster-url.jpg'
  };
  var elementID = 'rmpPlayer';
  var rmp = new RadiantMP(elementID);
  var rmpContainer = document.getElementById(elementID);
  // Get companion ad and append it to DOM when adstarted fires (if any available)
  var companionDiv = document.getElementById('companionDiv');
  rmpContainer.addEventListener('adstarted', function () {
    var companionAds = rmp.getCompanionAds();
    for (var i = 0; i < companionAds.length; i++) {
      var companionAd = companionAds[i];
      if (companionAd.getWidth() == 300 && companionAd.getHeight() == 250) {
        companionDiv.innerHTML = companionAd.getContent();
      }
    }
    });
  rmp.init(settings);
</script>

Ad pods

Below is an example of ad pods data retrieval through our player API. See here for more information.

<!-- Include Radiant Media Player JavaScript file in your <body> or <head> -->
<script src="https://cdn.radiantmediatechs.com/rmp/5.3.0/js/rmp.min.js"></script>
<!-- Player container element -->
<div id="rmpPlayer"></div>
<script>
  // Streaming source - in this case we specify a HLS source but we input a dummy URI
  var src = {
    hls: 'ima-dai'
  };
  // Player settings
  var settings = {
    licenseKey: 'your-license-key',
    src: src,
    width: 640,
    height: 360,
    // enables live UI and optimisations
    isLive: true,
    ads: true,
    // enables IMA DAI support in Radiant Media Player
    adImaDai: true,
    // DAI Live stream asset key
    adImaDaiLiveAssetKey: 'live-asset-key',
    // Backup HLS stream in case the DAI stream is not available when requested
    // Note that this is also the HLS stream that will be used on iOS since hls.js does not work on iOS
    adImaDaiBackupStream: 'https://backup-hls-stream.m3u8',
    // In macOS Safari we force hls.js usage to enable IMA DAI support
    forceHlsJSOnMacOSSafari: true,
    // ad label that can be displayed within player UI when an ad is on stage
    labels: {
      ads: {
        controlBarCustomMessage: 'Ads'
      }
    },
    poster: 'https://your-poster-url.jpg'
  };
  var elementID = 'rmpPlayer';
  var rmp = new RadiantMP(elementID);
  var rmpContainer = document.getElementById(elementID);
  rmpContainer.addEventListener('adstarted', function () {
    var adPodInfo = rmp.getAdPodInfo();
    var adPosition = adPodInfo.getAdPosition();
    var maxDuration = adPodInfo.getMaxDuration();
    var podIndex = adPodInfo.getPodIndex();
    var timeOffset = adPodInfo.getTimeOffset();
    var totalAds = adPodInfo.getTotalAds();
  });
  rmp.init(settings);
</script>

iOS specific considerations

On iOS Safari, last major environment where Media Source Extensions are still not available in 2018, hls.js does not go. By default if a HLS stream is provided through the adImaDaiBackupStream setting, we will use this HLS source for iOS Safari. However this does not enable ads on iOS Safari. In order to do so we need to use the client-side HTML5 IMA SDK (as opposed to the DAI IMA SDK). This can be done as follows:

// We define DAI player settings for non-iOS devices ...
var daiSettings = {...};
// ... and client-side IMA player settings for iOS devices
var iosImaSettings = {...};
var elementID = 'rmpPlayer';
var rmp = new RadiantMP(elementID);
// We detect iOS and use the relevant settings to init player
var env = rmp.getEnvironment();
var ios = env.isIos[0];
if (ios) {
  rmp.init(iosImaSettings);
} else {
  rmp.init(daiSettings);
}

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

Ads with the HTML5 Google IMA DAI SDK

Player

Streaming

Styling and branding

Live and DVR

Related & playlist content

Analytics

Social media

OTT

Ads

Outstream video ads

Server side ad insertion (SSAI)

Mobile applications

DRM & HLSe

360 video

Offline

HEVC, AV1, AC-3 & 4K video

HTML5 audio

Peer-to-peer streaming

Guides

Helpers