Implementation guide

Pre-roll video

Pre-roll video ads

A video ad that plays inside the player before the video the person chose to watch.

Ad Manager
Ad Exchange
AdSense (via Ad Manager)
inside the video player (mobile and desktop)

Learn the format Check my site

Desktop

Mobile

Understand it in 1 minute

What a pre-roll video is

You know when you go to the movies and, before the film starts, they show some trailers and ads? Pre-roll video is exactly that, but on your site. The person presses play to watch a video and, before the content appears, an ad plays inside the same player. The player is the little box where the video plays, with the play, pause and volume buttons. When the ad ends, the chosen video starts.

For this to work, the player needs to know how to request the ad. Google offers a code package called the IMA SDK, which you place alongside the player. It sends a request to Ad Manager using an ad tag, which is an internet address with the information about the space, such as the ad unit and the player size. The response comes in VAST, which is a standard format, like a recipe that says which video to play and how to count the views. When the site uses video ad rules, the response can come in VMAP, which is like a TV schedule, saying when each break comes in.

Google also explains something important about videos that start on their own, known as autoplay. Browsers like Chrome and Safari have their own rules, and often the video can only start on its own if it is muted. There is no simple way to ask whether the browser allows it: the only way is to try playing. That is why the IMA guide says that, on mobile, the ad container should be started by a user action, such as tapping the play button. And, if the player is going to start on its own or muted, it should say so in the request, so that only ads that can play that way are returned.

The pre-roll is worth it when the video is the reason for the visit, like a class, a recipe or a news video. In Google's video policy, this space is called In-stream, which means inside the content the person chose to watch, and it must be declared the right way. Always remember: the person came for the video, so the ad cannot get in the way of the controls or freeze the content.

Step by step

How to implement

Create a video ad unitIn Ad Manager, the pre-roll uses a video and audio ad unit. The tag the player will use comes from this unit.
Generate the ad tagGo to Inventory, Ad units, open the unit and click Tags. Choose Google Publisher Tag for video and audio, go through the steps and copy the tag. The values between brackets must be filled in by the player at request time.
Add the IMA SDK to the pageLoad the IMA SDK script before your code. Create a container over the video for the ad and connect the container to the video with the AdDisplayContainer, which is the IMA piece that shows the ad.
Request the adCreate an AdsLoader and an AdsRequest with your tag. Provide the width and height of the linear ad slot. This helps IMA choose the right ad when several come back.
Pause and resume the contentWhen IMA asks for a pause (the CONTENT_PAUSE_REQUESTED event), pause the video. When it asks to continue (CONTENT_RESUME_REQUESTED), play again. If there is an error, destroy the ads manager and let the video play without an ad.
Start on the person's clickOn the play button, initialize the ad container and then initialize and start the AdsManager. The IMA guide says that, on mobile, the ad container must be started by a user action.

Implemented example

The code and how it looks on screen

It goes on the video page: the IMA script at the top, the player with the ad container over it, and the code that requests the pre-roll when the person clicks Watch.

<!-- 1. Carrega o IMA SDK (antes do seu código) -->
<script src="//imasdk.googleapis.com/js/sdkloader/ima3.js"></script>

<!-- 2. O vídeo e, por cima dele, a caixa do anúncio -->
<div style="position:relative;width:640px;height:360px">
  <video id="conteudo" width="640" height="360" playsinline controls>
    <source src="meu-video.mp4" type="video/mp4">
  </video>
  <div id="adContainer" style="position:absolute;top:0;left:0"></div>
</div>
<button id="playButton">Assistir</button>

<script>
  var video = document.getElementById('conteudo');
  var adDisplayContainer = new google.ima.AdDisplayContainer(
      document.getElementById('adContainer'), video);
  var adsLoader = new google.ima.AdsLoader(adDisplayContainer);
  var adsManager;

  adsLoader.addEventListener(
      google.ima.AdsManagerLoadedEvent.Type.ADS_MANAGER_LOADED,
      function (e) {
        adsManager = e.getAdsManager(video);
        adsManager.addEventListener(
            google.ima.AdEvent.Type.CONTENT_PAUSE_REQUESTED,
            function () { video.pause(); });
        adsManager.addEventListener(
            google.ima.AdEvent.Type.CONTENT_RESUME_REQUESTED,
            function () { video.play(); });
        adsManager.addEventListener(
            google.ima.AdErrorEvent.Type.AD_ERROR, onAdError);
      });
  adsLoader.addEventListener(
      google.ima.AdErrorEvent.Type.AD_ERROR, onAdError);

  function onAdError(e) {
    console.log(e.getError());
    if (adsManager) { adsManager.destroy(); }
    video.play(); // sem anúncio, o vídeo continua
  }

  // 3. Pedido do anúncio (IDs de exemplo)
  var adsRequest = new google.ima.AdsRequest();
  adsRequest.adTagUrl = 'https://pubads.g.doubleclick.net/gampad/ads?' +
      'iu=/1234567/exemplo&sz=640x480&env=vp&gdfp_req=1&output=vast' +
      '&unviewed_position_start=1&vpa=click&vpmute=0&plcmt=1' +
      '&description_url=https%3A%2F%2Fwww.exemplo.com%2Fvideo&correlator=';
  adsRequest.linearAdSlotWidth = 640;
  adsRequest.linearAdSlotHeight = 400;
  adsLoader.requestAds(adsRequest);

  // 4. Só começa quando a pessoa clica em Assistir
  document.getElementById('playButton').addEventListener('click', function () {
    adDisplayContainer.initialize();
    try {
      adsManager.init(640, 360, google.ima.ViewMode.NORMAL);
      adsManager.start();
    } catch (err) {
      video.play();
    }
  });
</script>

On desktopThe ad plays inside the player, in the same place where the video will play, before the content starts. When it ends, the chosen video starts.

On mobileIt also appears inside the player, usually after the person taps play. On iPhone, the video needs the playsinline attribute to play inside the page, and not in the full-screen player.

What Google recommends

Do and don't

Allowed

Play the ad before the video the person chose, inside the player, using the IMA SDK, one of the tools Google requires for In-stream spaces.
Start the ad from the person's click on the play button, as the IMA guide recommends for mobile.
Use autoplay, including muted, as long as the player says in the request that it will play on its own and whether it will play muted.
Let the video play normally when the ad has an error, as Google's example does.

Not allowed

You cannot declare the wrong space: an ad in a player with video must be declared as In-stream or Companion content (video that goes along with the main content).
Do not leave the ad and video controls covered, hidden or not working.
Do not have more than one video playing on its own with sound at the same time, or more than one visible player playing on its own on screen.
The ad must not start on its own before at least 50% of the space is visible.
Do not use IMA products to earn money from YouTube videos.

Tips

To do it right

Google says the only way to know whether the browser allows autoplay is to try playing. If it fails, show the play button and wait for the click.
If the player is going to start muted, think about audio-only ads: Google suggests adding ad_type=video to the tag or not starting muted.
Use only one AdsLoader per page. For each new ad request, create a new AdsRequest.
On desktop, IMA does not open the ad link in the first 2 seconds, to avoid accidental clicks.

Watch out

Common errors

Opening the file directly on the computer

The IMA guide asks you to serve the page through a web server, even a local one. Opening the HTML file directly can make the test fail.

Starting without a user action on mobile

On mobile, the ad container must be started by a user action, such as tapping play. Without it, the ad may not play.

Not handling the ad error

A VAST response with a problem can cause an error. Google's example destroys the ads manager and plays the video, so the person is not stuck on a frozen screen.

Forgetting to adjust the size

When the window changes size, Google's example calls the AdsManager resize with the video size. Without it, the ad can end up the wrong size.

Frequently asked questions

Do I need ad rules to have a pre-roll?

No. The player can request a VAST tag through IMA. Google says the ad rules parameter (ad_rule) is not required to serve ads, only to use video ad rules.

What is the difference between VAST and VMAP?

VAST is the response that says which ad to play. VMAP is the response used with ad rules, which says when the breaks come in. The tag chooses the format with the output parameter, with values like vast and vmap.

Can pre-roll play on its own?

Yes, when the browser allows it. Chrome and Safari limit autoplay, especially with sound. The player should test it, say in the request whether it will play on its own and muted, and on mobile start the ad from the person's action.

What happens if the ad does not load?

Google's guide asks that the video keep playing when ads fail to load. In the example, the ads manager is destroyed and the video plays without ads.

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