Implementation guide

Companion ad

Companion ads

A banner that appears on the page at the same time as a video or audio ad plays in the player, forming a pair.

Ad Manager
on the page, in display spaces near the video or audio player

Learn the format Check my site

Desktop

Mobile

Understand it in 1 minute

What the companion ad is

Think of a concert: while the singer is on stage, a screen beside her shows the song name. Both tell the same story at the same time. The companion ad is like that. While the video or audio ad plays in the player, a banner of the same ad shows in an ad slot on the page, near the player.

Google explains that companion ads let you show ads in display spaces at the same time as an ad is served in a video or audio player. They always depend on the main ad, called the master: without a master, there is no companion. It is like the concert screen, which only makes sense if someone is singing. A VAST ad can carry up to 6 companion display ads.

How does the site do this? The display slots next to the player are created with GPT, the Google Publisher Tag, which is Google's code for ad slots. GPT has three pieces for this. The first, companionAds, says that the slot can receive a companion when a VAST ad is playing in a player on the same page. The second, setRefreshUnfilledSlots, asks to fill the slots that stayed empty later. The third, enableVideoAds, makes GPT and the IMA SDK use the same correlator, a number that is the same in all ad requests of the same page view. On the player side, IMA sends the companion sizes in the ciu_szs parameter of the tag.

When is it worth it? When you have video or audio ads and want the ad to also show on the page. For video players that can receive audio ads, Google strongly recommends using companion banners, so the player does not stay blank while the audio plays. A few cautions: the slot must have the same size as the companion, responsive ads are not supported as video companions and, if the player is inside an iframe, you need a GPT proxy script.

Step by step

How to implement

Enter the sizes in the line itemWhen creating the video and audio line item, enter the expected size of the master creative and the sizes of the companions.
Add the companion creativesUse one of the accepted types: Image, Campaign Manager 360, Third-party, Custom, Native format (Beta) or standard or custom creative templates.
Load GPT on the main pageIMA for HTML5 only recognizes GPT spaces when GPT loads on the main page. If the player is in an iframe, include the GPT proxy script.
Create the companion spaceDefine the space with companionAds and pubads, turn on filling of empty spaces, enable video ads and display the space. Define the spaces before the player shows the ads.
Send the sizes in the player tagIn the IMA tag, use the ciu_szs parameter with the companion sizes separated by commas, such as 728x90,300x250.
Avoid flashing on autoplayIf the video or audio plays on its own, GPT can use disableInitialLoad so it does not show a regular banner for a moment before the companion arrives.

Implemented example

The code and how it looks on screen

GPT goes in the head of the same page as the player, and the companion box goes near the player, with the same size as the companion ad.

<!-- No head: GPT com um espaço que aceita complementar -->
<script async
  src="https://securepubads.g.doubleclick.net/tag/js/gpt.js"></script>
<script>
  window.googletag = window.googletag || { cmd: [] };
  googletag.cmd.push(function () {
    googletag
        .defineSlot('/1234567/exemplo', [728, 90], 'companionDiv')
        .addService(googletag.companionAds())
        .addService(googletag.pubads());
    googletag.companionAds().setRefreshUnfilledSlots(true);
    googletag.pubads().enableVideoAds();
    googletag.enableServices();
  });
</script>

<!-- No body: a caixa do complementar, do mesmo tamanho -->
<div id="companionDiv" style="width:728px; height:90px;">
  <script>
    googletag.cmd.push(function () { googletag.display('companionDiv'); });
  </script>
</div>

<!-- Na tag do IMA, os tamanhos dos complementares vão em ciu_szs:
     ...&ciu_szs=728x90&... -->

On desktopWhile the ad plays in the player, a banner of the same ad shows in a display slot on the page.

On mobileThe companion banner appears in a display space on the page while the ad plays in the player. At fluid size, it takes up the same percentage of space on any screen.

What Google recommends

Do and don't

Allowed

Show up to 6 companion ads for each VAST ad.
Use companions of the type Image, Campaign Manager 360, Third-party, Custom, Native format (Beta) or creative templates.
Ask for empty companion spaces to be filled later with another ad from your network.
Use companions of fluid size, which take up the same percentage of space on any screen.
Using companion banners in video players that can receive audio ads, which Google strongly recommends.

Not allowed

There is no standalone companion: it always depends on the master ad.
Responsive ads are not supported as video companions.
IMA does not support the click-to-activate function on video companions.
Formats with native video turned on cannot be used as companions.
With the player in an iframe, GPT is not recognized without the proxy script.

Tips

To do it right

For spaces created during the page, define them before the player shows the ads.
If the VAST carries fewer companions than the defined spaces, the leftover spaces can be filled by your network.
In the ciu_szs parameter, the vertical bar between sizes indicates a space with several sizes.
Those who do not use GPT can get the companion through the IMA API, choosing the size and putting the content in the box when the ad starts.

Watch out

Common errors

GPT inside an iframe

IMA for HTML5 only recognizes GPT spaces on the main page. In an iframe, without the proxy script, the companion does not appear.

Size that does not match

The companion must be the same size as the space. A 728x90 space does not receive a 300x250 companion.

Forgetting the sizes in the tag

A player with IMA must send the companion sizes in the ciu_szs parameter. Without it, the server does not know which sizes the page accepts.

Banner flashing before the companion

In video or audio that plays on its own, a regular banner may appear for a moment. Google recommends disableInitialLoad to avoid this.

Frequently asked questions

Does the companion appear without the video?

No. It always depends on the master ad playing in the player. If there is no companion, the space can receive another ad from your network.

How many companions can I have?

A VAST ad can carry up to 6 companion display ads.

Does it work with audio ads?

Yes. In video players that can receive audio ads, Google strongly recommends using companion banners, so the player does not stay blank while the sound plays.

What is enableVideoAds for?

It makes GPT and the IMA SDK use the same correlator, a number that is the same in all ad requests of the same page view.

Library

Official Google source

Everything on this page follows Google's official documentation. Read it straight from the source:

Does your site use this format the right way?

The audit reads the site as a visitor would, without clicking anything, and shows what to fix.

Run an audit