Create companion tags

Companion tags are JavaScript snippets in your webpage that indicate where companion ads should show. Learn how to create and add these snippets by expanding each section below.

When you use the Google Interactive Media Ads SDK for ad serving, the metrics reported back to the ad server may include whether or not the user interacted with the page on which the ads were served. This fact should be disclosed to your visitors to comply with the data collection and usage disclosure requirement of your contract with Google.

Click-to-play video players

JavaScript for the HEAD element of your webpage

You'll insert two pieces of JavaScript into the HEAD element of your page. This code doesn't influence how fast your page loads.

Part 1: The first part of the code loads the Google Publisher Tag. Insert the following JavaScript code into the HEAD element exactly as shown here:

<script type='text/javascript'>
var googletag = googletag || {};
googletag.cmd = googletag.cmd || [];
(function() {
var gads = document.createElement('script');
gads.async = true; gads.type = 'text/javascript';
gads.src = 'http://www.googletagservices.com/tag/js/gpt.js';
var node = document.getElementsByTagName('script')[0];
node.parentNode.insertBefore(gads, node);
})();
</script>

Part 2: The second part of the code defines the companion ad slots. For each companion slot, you'll create a short JavaScript snippet in this format:

googletag.defineSlot('%unitcode%', [%width%, %height%], '%div-id%').addService(googletag.companionAds()).addService(googletag.pubads());
First, replace each bold phrase with a real value as outlined below.

Parameter Description Example
unitcode Current ad unit. Follow this format: /network id/directory tree.../ad unit /6062/video-parent/child-ad-unit
width Width of the companion slot in pixels. 300
height Height of the companion slot in pixels. 250
div-id Unique id for a DIV layer in the page where the ad will show. Create a unique id for each unit. ad-div-1

Example snippet with real values:

googletag.defineSlot('/6062/video-parent/child-ad-unit', [300, 250], 'ad-div-1').addService(googletag.companionAds()).addService(googletag.pubads());

If you have only one companion slot on your page, you’re done. If you have more slots, create a snippet for each size. The sizes cannot be duplicated on a single page; for example, you cannot have two 300x250 companion slots.

After you create snippets for each companion slot, insert them where it says ---INSERT HERE--- in the code below.

<script type='text/javascript'>
googletag.cmd.push(function() {
---INSERT HERE---

googletag.companionAds().setRefreshUnfilledSlots(true);
googletag.pubads().enableVideoAds();
googletag.enableServices();
});
</script>

Example code with one companion snippet:

<script type='text/javascript'>
googletag.cmd.push(function() {
googletag.defineSlot('/6062/video-parent/child-ad-unit', [300, 250], 'ad-div-1').addService(googletag.companionAds()).addService(googletag.pubads());
googletag.companionAds().setRefreshUnfilledSlots(true);
googletag.pubads().enableVideoAds();
googletag.enableServices();
});
</script>
Example code with two companion snippets:
<script type='text/javascript'>
googletag.cmd.push(function() {
googletag.defineSlot('/6062/video-parent/child-ad-unit', [300, 250], 'ad-div-1').addService(googletag.companionAds()).addService(googletag.pubads());
googletag.defineSlot('/6062/video-parent/child-ad-unit', [728, 90], 'ad-div-2').addService(googletag.companionAds()).addService(googletag.pubads());

googletag.companionAds().setRefreshUnfilledSlots(true);
googletag.pubads().enableVideoAds();
googletag.enableServices();
});
</script>

JavaScript for the BODY element of your webpage

In order to display the companion ad slots that you defined in the HEAD element, you'll create a short HTML snippet for each of them in this format:

<div id='%div-id%' style='width:%width%px; height:%height%px;'>
<script type='text/javascript'>
googletag.cmd.push(function() { googletag.display('%div-id%'); });
</script>
</div>

Replace the two instances of %div-id% with the unique id you created for this companion slot in the HEAD element. Replace %width% and %height% with the dimensions of the companion slot.

Example HTML snippet with real values:

<div id='ad-div-1' style='width:300px; height:250px;'>
<script type='text/javascript'>
googletag.cmd.push(function() { googletag.display('ad-div-1'); });
</script>
</div>

Next, add each HTML snippet to the place on the webpage where the companion ad should show.

Sample webpage

Here’s an example of a page tagged for showing a 300x250 companion:

<html>
<head>
<title>My awesome video page!</title>

<script type='text/javascript'>
var googletag = googletag || {};
googletag.cmd = googletag.cmd || [];
(function() {
var gads = document.createElement('script');
gads.async = true;
gads.type = 'text/javascript';
gads.src = 'http://www.googletagservices.com/tag/js/gpt.js';
var node = document.getElementsByTagName('script')[0];
node.parentNode.insertBefore(gads, node); })();
</script>

<script type='text/javascript'>
googletag.cmd.push(function() {
googletag.defineSlot('/6062/video-parent/child-ad-unit', [300, 250], 'ad-div-1').addService(googletag.companionAds()).addService(googletag.pubads());
googletag.companionAds().setRefreshUnfilledSlots(true);
googletag.enableServices();
});
</script>
</head>
<body>
. . .
<div id='ad-div-1' style='width:300px; height: 250px;'>
<script type='text/javascript'>
googletag.cmd.push(function() {
googletag.display('ad-div-1'); });
</script>
</div>
. . .
</body>
</html>

Auto-play video players

Instructions and sample webpage

If your webpage has an auto-play video player, simply add one line to your code: Above googletag.enableServices();, add googletag.pubads().disableInitialLoad();.

Here's an example, using the same sample webpage as the click-to-play example above:

<html>
<head>
<title>My awesome video page!</title>

<script type='text/javascript'>
var googletag = googletag || {};
googletag.cmd = googletag.cmd || [];
(function() {
var gads = document.createElement('script');
gads.async = true; gads.type = 'text/javascript';
gads.src = 'http://www.googletagservices.com/tag/js/gpt.js';
var node = document.getElementsByTagName('script')[0];
node.parentNode.insertBefore(gads, node); })();
</script>

<script type='text/javascript'>
googletag.cmd.push(function() {
googletag.defineSlot('/6062/video-parent/child-ad-unit', [300, 250],
'ad-div-1').addService(googletag.companionAds()).addService(googletag.pubads());
googletag.companionAds().setRefreshUnfilledSlots(true);
googletag.pubads().disableInitialLoad(); googletag.enableServices();
});
</script>
</head>
<body>
. . .
<div id='ad-div-1' style='width:300px; height: 250px;'>
<script type='text/javascript'>
googletag.cmd.push(function() {
googletag.display('ad-div-1'); });
</script>
</div>
. . .
</body>
</html>

Companion dynamic allocation

Instructions

You can enable companion dynamic allocation to ensure that the HTML companion slots on a webpage are filled with display ads, even when no companion ads are available. Two lines of code are required for companion dynamic allocation, and both are included in the sample webpages above:

Step 1: Include the following line after the portion of the companion code that defines the ad slot sizes:

.addService(googletag.companionAds()).addService(googletag.pubads());

Here's an example from the sample webpages above:

googletag.defineSlot('/6062/video-parent/child-ad-unit', [300, 250], 'ad-div-1').addService(googletag.companionAds()).addService(googletag.pubads());

Step 2: Include the following line above googletag.enableServices(); wherever it appears. Learn more

googletag.companionAds().setRefreshUnfilledSlots(true);