Add companion ads support

AI-generated Key Takeaways

• This guide explains how to add companion ads to your Android IMA implementation.

• Prerequisites include an Android app with the IMA SDK integrated and an ad tag configured to return a companion ad.

• To add companion ads, create a ViewGroup in your layout, build a CompanionAdSlot object, and add it to an ArrayList which is then added to the AdsLoader.

• Fluid companion ads, which resize to match the size of the ad slot, can be displayed by setting the CompanionAdSlot.setSize() method to CompanionAdSlot.FLUID_SIZE for both parameters.

Select platform: HTML5 Android iOS

This guide is intended for publishers interested in adding companion ads to their Android IMA implementation.

Prerequisites

• Android application with the IMA SDK integrated. See the BasicExample if you don't already have an app with the SDK integrated. If you need help implementing the IMA SDK in your app, check out Set up the IMA SDK.
• An ad tag configured to return a companion ad. If you need a sample, check out our FAQ.

Add companion ads to your app

Follow along to add a companion ad slot and display companion ads in your app.

Create a ViewGroup to display your companion

Before requesting a companion, you need to create a space for it in your layout. In your layout XML, add a ViewGroup element; this example uses a LinearLayout. In a later step you'll pass a reference to this element to your AdDisplayContainer.

If you're integrating into the BasicExample app, add this to the activity_my.xml file, below the videoPlayerContainer.

activity_my.xml

<LinearLayout
  android:id="@+id/companionAdSlot"
  android:layout_width="match_parent"
  android:layout_height="250dp"
  android:layout_gravity="center_horizontal"
  android:gravity="center"
  android:orientation="vertical"
  android:textAlignment="center" />

Create a CompanionAdSlot

The next step is to build a CompanionAdSlot object, which is then added to an ArrayList<CompanionAdSlot> instance. The AdDisplayContainer interface takes a list of companion ad slots so you can display multiple companion ads at once. You need to create an instance of ImaSdkFactory class to create the CompanionAdSlot object.

ImaSdkFactory sdkFactory = ImaSdkFactory.getInstance();
ViewGroup companionViewGroup = (ViewGroup) findViewById(R.id.companionAdSlot);

CompanionAdSlot companionAdSlot = sdkFactory.createCompanionAdSlot();
companionAdSlot.setContainer(companionViewGroup);
companionAdSlot.setSize(300, 250);
ArrayList<CompanionAdSlot> companionAdSlots = new ArrayList<CompanionAdSlot>();
companionAdSlots.add(companionAdSlot);

Create a companion ad slot for each size of companion you intend to show in your app. The IMA SDK populates the companion ad slot with any companions from the VAST response that have dimensions matching the view's height and width. The IMA SDK also supports using fluid sized companions. Once you create the companionAdSlots, add them to the AdsLoader. The following examples show how to do this depending on whether you are using the Exoplayer-IMA extension, or other IMA implementations that don't use the extension.

Exoplayer-IMA extension

adsLoader = new ImaAdsLoader.Builder(this).setCompanionAdSlots(companionAdSlots).build();

Other implementations

adsLoader.getAdDisplayContainer().setCompanionSlots(companionAdSlots);

That's all there is to it! Your application is now displaying companion ads.

Display fluid companion ads

IMA supports fluid companion ads. These companions ads can resize to match the size of the ad slot. They fill 100% of the width of parent view, then resize their height to fit the companion's content. They're set by using the Fluid companion size in Ad Manager. See the following image for where to set this value.

Update Android apps for fluid companions

You can declare a fluid companion slot by updating the CompanionAdSlot.setSize() method to take CompanionAdSlot.FLUID_SIZE as both parameters.

ImaSdkFactory sdkFactory = ImaSdkFactory.getInstance();
ViewGroup companionViewGroup = (ViewGroup) findViewById(R.id.companionAdSlot);

CompanionAdSlot companionAdSlot = sdkFactory.createCompanionAdSlot();
companionAdSlot.setContainer(companionViewGroup);
companionAdSlot.setSize(CompanionAdSlot.FLUID_SIZE, CompanionAdSlot.FLUID_SIZE);
ArrayList<CompanionAdSlot> companionAdSlots = new ArrayList<CompanionAdSlot>();
companionAdSlots.add(companionAdSlot);

FAQ

I followed the guide, but I'm not seeing companion ads. What should I do?

First, check to make sure your tag really is returning companions. To do this, open the tag in a web browser and look for a <CompanionAds> tag. If you see that, check to make sure the size of the companion being returned is the same size as the dimensions you're passing into the CompanionAdSlot object.

What will my companion ad slot look like when following this guide?

The following image was created from the BasicExample and has the content video playing on top with the companion ad underneath.