Companion Ads

Back to v9 documentation index

Scope of support for companion ads

While displaying a video ad within Radiant Media Player some ad-service provider can offer the possibility to display companion ads. Those companion ads help to give context to a video ad and can increase viewer engagement.

Radiant Media Player provides three ways to include companions ads on a web page when a VAST response include valid companions ads data:

• Using Google Publisher Tag (Google IMA)
• Using the player Ads API (Google IMA)
• Companion ads with rmp-vast

Using Google Publisher Tag (Google IMA)

Google Publisher Tag automates the displaying of HTML companion ads on your site.

For HTML5 video ads please refer to this Google article.

Using the player Ads API (Google IMA)

When the player fires the adstarted event through our ads API you can query the getCompanionAds method to obtain companion ads data and display them on your page.

rmp.getCompanionAds(companionAdSlotWidth, companionAdSlotHeight, companionAdsOptions)

This method returns an Array of Object containing companion ads data. Parameters companionAdSlotWidth and companionAdSlotHeight are required and must be expressed in pixels. companionAdsOptions is an optional Object representing filtering options for the companion ad to be returned. For complete documentation on companionAdsOptions see this Google documentation page.

Player code example

<script src="https://cdn.radiantmediatechs.com/rmp/9.16.7/js/rmp.min.js"></script>
<div id="rmp"></div>
<br><br>
<!-- here is where the companion ad will be displayed -->
<div id="companion-ad-300-250" style="width: 300px; height: 250px;"></div>
<script>
  const src = {
    hls: 'https://your-hls-url.m3u8'
  };
  const settings = {
    licenseKey: 'your-license-key',
    src: src,
    width: 640,
    height: 360,
    contentMetadata: {
      poster: [
        'https://your-poster-url.jpg'
      ]
    },
    ads: true,
    adTagUrl: 'https://your-ad-tag-url'
  };
  const elementID = 'rmp';
  const rmp = new RadiantMP(elementID);
  // we wait for the adstarted event
  rmp.on('adstarted', () => {
    // we get our companion ads
    // the following settings are optional
    /*const companionAdsOptions = new google.ima.CompanionAdSelectionSettings();
    companionAdsOptions.resourceType = google.ima.CompanionAdSelectionSettings.ResourceType.STATIC;
    companionAdsOptions.creativeType = google.ima.CompanionAdSelectionSettings.CreativeType.IMAGE;
    companionAdsOptions.sizeCriteria = google.ima.CompanionAdSelectionSettings.SizeCriteria.IGNORE;
    companionAdsOptions.sizeCriteria = google.ima.CompanionAdSelectionSettings.SizeCriteria.SELECT_FLUID;*/
    const companionAds = rmp.getCompanionAds(300, 250);
    // or const companionAds = rmp.getCompanionAds(300, 250, companionAdsOptions);
    // if any companion ad we display them
      const companionAd = companionAds[0];
      // Get HTML content from the companion ad
      if (companionAd.getContent) {
        const companionAdContent = companionAd.getContent();
        // Write the content to the companion ad slot
        const companionAdDiv = document.getElementById('companion-ad-300-250');
        companionAdDiv.innerHTML = companionAdContent;
      } 
  });
  rmp.init(settings);
</script>

Companion ads with rmp-vast

Using companion ads with rmp-vast slightly differs from using companion ads with Google IMA so make sure to check the example below before usage.

When the player fires the adstarted event through our API you can query the getCompanionAds method to obtain an Array of Object representing available companion ads based on input parameter. Each Object in the Array represents a companion ad

rmp.getCompanionAds(companionAdSlotWidth, companionAdSlotHeight)

This method returns an Array of Object. Input companionAdSlotWidth and companionAdSlotHeight parameters are used to select companion ads based on available width and height for display. If no companion ad is available null is returned. Parameters companionAdSlotWidth and companionAdSlotHeight are required and must be expressed in pixels. Each companion ad Object is represented as:

{
  adSlotId: "RMPSLOTID-1"
  altText: "Radiant Media Player logo"
  companionClickThroughUrl: "https://www.radiantmediaplayer.com"
  companionClickTrackingUrl: "https://www.radiantmediaplayer.com/vast/tags/ping.gif?creativeType=companion&type=companionClickTracking"
  height: 250
  imageUrl: "https://www.radiantmediaplayer.com/vast/mp4s/companion.jpg"
  trackingEventsUri: [
    "https://www.radiantmediaplayer.com/vast/tags/ping.gif?creativeType=companion&type=creativeView", 
    "https://www.radiantmediaplayer.com/vast/tags/ping.gif?creativeType=companion&type=creativeViewTwo"
  ]
  width: 300
}

rmp.getCompanionAd(index)

return HTMLElement image representing the companion ad. It takes a Number index parameter which represents the index of the wanted companion ad in the Array returned from getCompanionAdsList method. This method automates the required pinging for companion ads.

Player code example

<script src="https://cdn.radiantmediatechs.com/rmp/9.16.7/js/rmp.min.js"></script>
<div id="rmp"></div>
<br><br>
<!-- here is where the companion ad will be displayed -->
<div id="companionId" style="width: 300px; height: 250px;"></div>
<script>
  const src = {
    hls: 'https://your-hls-url.m3u8'
  };
  const settings = {
    licenseKey: 'your-license-key',
    src: src,
    width: 640,
    height: 360,
    contentMetadata: {
      poster: [
        'https://your-poster-url.jpg'
      ]
    },
    ads: true,
    adParser: 'rmp-vast',
    adTagUrl: 'https://your-ad-tag-url'
  };
  const rmp = new RadiantMP('rmp');
  // we wait for the adstarted event
  rmp.on('adstarted', () => {
    // we need to call getCompanionAds BEFORE calling getCompanionAd so that 
    // rmp-vast can first create a collection of available companion ads based on getCompanionAds 
    // input parameters
    const list = rmp.getCompanionAds(900, 750);
    if (list.length === 3) {
      const img = rmp.getCompanionAd(2);
      if (img instanceof HTMLElement) {
        // we get our companion ad image and we can append it to DOM now
        // VAST trackers will be called automatically when needed
        const companionId = document.getElementById('companionId');
        companionId.appendChild(img);
      }
    }
  });
  rmp.init(settings);
</script>