Vamos começar

Os SDKs do IMA facilitam a integração de anúncios multimídia nos seus sites e apps. Os SDKs do IMA podem solicitar anúncios de qualquer servidor compatível com VAST e gerenciar a exibição de anúncios nos seus apps. Com os SDKs do lado do cliente do IMA, você mantém o controle da reprodução de vídeo do conteúdo, enquanto o SDK gerencia a reprodução do anúncio. Os anúncios são reproduzidos em um player de vídeo separado posicionado no player de vídeo do app.

Neste guia, demonstramos como integrar o SDK do IMA a um app de player de vídeo simples. Se você quiser ver ou acompanhar uma integração de amostra concluída, faça o download do exemplo simples do GitHub. Se você tiver interesse em um player HTML5 com o SDK pré-integrado, confira o plug-in SDK do IMA para Video.js.

Visão geral do lado do cliente do IMA

A implementação do lado do cliente do IMA envolve quatro componentes principais do SDK, demonstrados neste guia:

  • AdDisplayContainer: é um objeto contêiner em que os anúncios são renderizados.
  • AdsLoader: um objeto que solicita anúncios e processa eventos de respostas de solicitações de anúncios. Só é possível instanciar um carregador de anúncios, que pode ser reutilizado ao longo da vida útil do aplicativo.
  • AdsRequest: um objeto que define uma solicitação de anúncios. As solicitações de anúncios especificam o URL da tag de anúncio VAST, bem como parâmetros adicionais, como dimensões de anúncio.
  • AdsManager: um objeto que contém a resposta à solicitação de anúncios, controla a reprodução dos anúncios e detecta os eventos de anúncios disparados pelo SDK.

Pré-requisitos

Antes de começar, você precisará de:

  • Três arquivos vazios:
    • index.html
    • style.css (link em inglês)
    • ads.js (em inglês)
  • Python instalado no computador ou servidor da Web para testar

1. Iniciar um servidor de desenvolvimento

Como o SDK do IMA carrega dependências com o mesmo protocolo da página de onde ele é carregado, você precisa usar um servidor da Web para testar seu app. A maneira mais simples de iniciar um servidor de desenvolvimento local é usar o servidor integrado do Python.

  1. Usando uma linha de comando, no diretório que contém a execução do arquivo index.html: 
      python -m http.server 8000
  2. Em um navegador da Web, acesse http://localhost:8000/.

Também é possível usar qualquer outro servidor da Web, como o Apache HTTP Server.

2. Criar um player de vídeo simples

Primeiro, modifique index.html para criar um elemento de vídeo HTML5 simples, contido em um elemento de wrapper e um botão para acionar a reprodução. Adicione também as tags necessárias para carregar os arquivos style.css e ads.js. Em seguida, modifique styles.css para tornar o player de vídeo responsivo em dispositivos móveis. Por fim, em ads.js, acione a reprodução do vídeo quando o botão de reprodução for clicado.

index.html 

<!doctype html>
<html lang="en">
  <head>
    <title>IMA HTML5 Simple Demo</title>
    <meta charset="utf-8">
    <meta name="viewport" content="width=device-width, initial-scale=1, shrink-to-fit=no">
    <link rel="stylesheet" href="style.css">
  </head>
  <body>
    <div id="page-content">
      <div id="video-container">
        <video id="video-element">
          <source src="https://storage.googleapis.com/interactive-media-ads/media/android.mp4">
          <source src="https://storage.googleapis.com/interactive-media-ads/media/android.webm">
        </video>
      </div>
      <button id="play-button">Play</button>
    </div>
    <script src="ads.js"></script>
  </body>
</html>
style.css 
#page-content {
  position: relative;
  /* this element's width controls the effective height */
  /* of the video container's padding-bottom */
  max-width: 640px;
  margin: 10px auto;
}

#video-container {
  position: relative;
  /* forces the container to match a 16x9 aspect ratio */
  /* replace with 75% for a 4:3 aspect ratio, if needed */
  padding-bottom: 56.25%;
}

#video-element {
  /* forces the contents to fill the container */
  position: absolute;
  top: 0;
  left: 0;
  width: 100%;
  height: 100%;
}
ads.js 
var videoElement;

// On window load, attach an event to the play button click
// that triggers playback on the video element
window.addEventListener('load', function(event) {
  videoElement = document.getElementById('video-element');
  var playButton = document.getElementById('play-button');
  playButton.addEventListener('click', function(event) {
    videoElement.play();
  });
});

Depois de concluir essa etapa, ao abrir index.html no navegador (usando seu servidor de desenvolvimento), você verá o elemento de vídeo e o vídeo será iniciado quando você clicar no botão de reprodução.

3. Importar o SDK do IMA

Em seguida, adicione o framework do IMA usando uma tag de script em index.html, antes da tag do ads.js.

index.html 
...

        </video>
      </div>
      <button id="play-button">Play</button>
    </div>
    <script src="//imasdk.googleapis.com/js/sdkloader/ima3.js"></script>
    <script src="ads.js"></script>
  </body>
</html>

4. Anexar gerenciadores de página e player de vídeo

Para modificar o comportamento do player de vídeo com JavaScript, adicione manipuladores de eventos que acionam as seguintes ações:

  • Quando o carregamento da página for concluído, inicialize o SDK do IMA.
  • Quando o botão de reprodução do vídeo for clicado, carregar anúncios, a menos que já haja anúncios carregados.
  • Quando a janela do navegador for redimensionada, atualize o elemento de vídeo e as dimensões de adsManager para que a página seja responsiva em dispositivos móveis
ads.js 
var videoElement;
// Define a variable to track whether there are ads loaded and initially set it to false
var adsLoaded = false;

window.addEventListener('load', function(event) {
  videoElement = document.getElementById('video-element');
  initializeIMA();
  videoElement.addEventListener('play', function(event) {
    loadAds(event);
  });
  var playButton = document.getElementById('play-button');
  playButton.addEventListener('click', function(event) {
    videoElement.play();
  });
});

window.addEventListener('resize', function(event) {
  console.log("window resized");
});

function initializeIMA() {
  console.log("initializing IMA");
}

function loadAds(event) {
  // Prevent this function from running on if there are already ads loaded
  if(adsLoaded) {
    return;
  }
  adsLoaded = true;

  // Prevent triggering immediate playback when ads are loading
  event.preventDefault();

  console.log("loading ads");
}

5. Criar o contêiner do anúncio

Na maioria dos navegadores, o SDK do IMA usa um elemento de contêiner de anúncio dedicado para exibir anúncios e elementos de IU relacionados. Esse contêiner precisa ser dimensionado para se sobrepor ao elemento de vídeo do canto superior esquerdo. A altura e a largura dos anúncios neste contêiner são definidas pelo objeto adsManager. Assim, você não precisa definir esses valores manualmente.

Para implementar esse elemento de contêiner de anúncios, primeiro crie um novo div no elemento video-container. Em seguida, atualize o CSS para posicionar o elemento no canto superior esquerdo do video-element. Por fim, defina uma variável para o contêiner na função initializeIMA() que é executada quando a página é carregada.

index.html 
...

  <div id="video-container">
    <video id="video-element" controls>
      <source src="https://storage.googleapis.com/interactive-media-ads/media/android.mp4">
      <source src="https://storage.googleapis.com/interactive-media-ads/media/android.webm">
    </video>
    <div id="ad-container"></div>
  </div>

...
style.css 
...

#ad-container {
  position: absolute;
  top: 0;
  left: 0;
  width: 100%;
}
ads.js 
var videoElement;
var adsLoaded = false;
var adContainer;

...

function initializeIMA() {
  console.log("initializing IMA");
  adContainer = document.getElementById('ad-container');
}

6. Inicializar o AdsLoader e fazer uma solicitação de anúncios

Para solicitar um conjunto de anúncios, crie uma instância de ima.AdsLoader. Essa instância usa um objeto AdDisplayContainer como entrada e pode ser usada para processar objetos ima.AdsRequest associados a um URL de tag de anúncio especificado. A tag de anúncio usada neste exemplo contém um anúncio precedente de 10 segundos. É possível testar esse ou qualquer URL de tag de anúncio usando o Inspetor do pacote de vídeo do IMA.

Como prática recomendada, mantenha apenas uma instância de ima.AdsLoader durante todo o ciclo de vida de uma página. Para fazer outras solicitações de anúncio, crie um novo objeto ima.AdsRequest, mas reutilize o mesmo ima.AdsLoader. Para mais informações, consulte as Perguntas frequentes sobre o SDK do IMA.

ads.js (em inglês) 
var videoElement;
var adsLoaded = false;
var adContainer;
var adDisplayContainer;
var adsLoader;

...

function initializeIMA() {
  console.log("initializing IMA");
  adContainer = document.getElementById('ad-container');
  adDisplayContainer = new google.ima.AdDisplayContainer(adContainer, videoElement);
  adsLoader = new google.ima.AdsLoader(adDisplayContainer);

  // Let the AdsLoader know when the video has ended
  videoElement.addEventListener('ended', function() {
    adsLoader.contentComplete();
  });

  var adsRequest = new google.ima.AdsRequest();
  adsRequest.adTagUrl = 'https://pubads.g.doubleclick.net/gampad/ads?' +
      'iu=/21775744923/external/single_ad_samples&sz=640x480&' +
      'cust_params=sample_ct%3Dlinear&ciu_szs=300x250%2C728x90&' +
      'gdfp_req=1&output=vast&unviewed_position_start=1&env=vp&impl=s&correlator=';

  // Specify the linear and nonlinear slot sizes. This helps the SDK to
  // select the correct creative if multiple are returned.
  adsRequest.linearAdSlotWidth = videoElement.clientWidth;
  adsRequest.linearAdSlotHeight = videoElement.clientHeight;
  adsRequest.nonLinearAdSlotWidth = videoElement.clientWidth;
  adsRequest.nonLinearAdSlotHeight = videoElement.clientHeight / 3;

  // Pass the request to the adsLoader to request ads
  adsLoader.requestAds(adsRequest);
}

7. Detectar eventos AdsLoader

Quando os anúncios são carregados, o ima.AdsLoader emite um evento ADS_MANAGER_LOADED. Analise o evento transmitido ao callback para inicializar o objeto AdsManager. O AdsManager carrega os anúncios individuais conforme definido pela resposta ao URL da tag de anúncio.

Além disso, processe todos os erros que podem ocorrer durante o processo de carregamento. Caso os anúncios não sejam carregados, a reprodução de mídia continuará sem anúncios, para não interferir na experiência do usuário.

ads.js (em inglês) 
var videoElement;
var adsLoaded = false;
var adContainer;
var adDisplayContainer;
var adsLoader;
var adsManager;

...

function initializeIMA() {
  console.log("initializing IMA");
  adContainer = document.getElementById('ad-container');
  adDisplayContainer = new google.ima.AdDisplayContainer(adContainer, videoElement);
  adsLoader = new google.ima.AdsLoader(adDisplayContainer);
  adsLoader.addEventListener(
      google.ima.AdsManagerLoadedEvent.Type.ADS_MANAGER_LOADED,
      onAdsManagerLoaded,
      false);
  adsLoader.addEventListener(
      google.ima.AdErrorEvent.Type.AD_ERROR,
      onAdError,
      false);

...

function onAdsManagerLoaded(adsManagerLoadedEvent) {
  // Instantiate the AdsManager from the adsLoader response and pass it the video element
  adsManager = adsManagerLoadedEvent.getAdsManager(
      videoElement);
}

function onAdError(adErrorEvent) {
  // Handle the error logging.
  console.log(adErrorEvent.getError());
  if(adsManager) {
    adsManager.destroy();
  }
}

8. Iniciar o StorageClass

Para iniciar a reprodução do anúncio, inicie o AdsManager. Para oferecer suporte total a navegadores para dispositivos móveis, o recurso precisa ser acionado por uma interação do usuário.

ads.js (em inglês) 
...

function loadAds(event) {
  // prevent this function from running on every play event
  if(adsLoaded) {
    return;
  }
  adsLoaded = true;

  // prevent triggering immediate playback when ads are loading
  event.preventDefault();

  console.log("loading ads");

  // Initialize the container. Must be done via a user action on mobile devices.
  videoElement.load();
  adDisplayContainer.initialize();

  var width = videoElement.clientWidth;
  var height = videoElement.clientHeight;
  try {
    adsManager.init(width, height, google.ima.ViewMode.NORMAL);
    adsManager.start();
  } catch (adError) {
    // Play the video without ads, if an error occurs
    console.log("AdsManager could not be started");
    videoElement.play();
  }
}

...

9. Tornar o PersistentVolume responsivo

Para garantir que os anúncios sejam redimensionados dinamicamente para corresponder ao tamanho do player de vídeo, se a tela mudar de tamanho ou orientação, o evento de redimensionamento de janela precisará chamar adsManager.resize().

ads.js (em inglês) 
...

window.addEventListener('resize', function(event) {
  console.log("window resized");
  if(adsManager) {
    var width = videoElement.clientWidth;
    var height = videoElement.clientHeight;
    adsManager.resize(width, height, google.ima.ViewMode.NORMAL);
  }
});

...

10. Detectar eventos StorageClass

O AdsManager também dispara vários eventos que precisam ser processados. Esses eventos são usados para rastrear mudanças de estado, acionar a reprodução e a pausa no vídeo de conteúdo e registrar erros.

Como processar os erros

O manipulador de erros criado para AdsLoader pode servir como o manipulador de erros para o AdsManager adicionando um novo manipulador de eventos com a mesma função de callback.

ads.js (em inglês) 
...

function onAdsManagerLoaded(adsManagerLoadedEvent) {
  adsManager = adsManagerLoadedEvent.getAdsManager(
      videoElement);

  adsManager.addEventListener(
      google.ima.AdErrorEvent.Type.AD_ERROR,
      onAdError);
}

...

Como acionar eventos de reprodução e pausa

Quando o AdsManager estiver pronto para inserir um anúncio de display, ele acionará o evento CONTENT_PAUSE_REQUESTED. Processe esse evento acionando uma pausa no player de vídeo subjacente. Da mesma forma, quando um anúncio é concluído, a AdsManager dispara o evento CONTENT_RESUME_REQUESTED. Processe esse evento reiniciando a reprodução no vídeo de conteúdo subjacente.

ads.js (em inglês) 
...

function onAdsManagerLoaded(adsManagerLoadedEvent) {
  adsManager = adsManagerLoadedEvent.getAdsManager(
      videoElement);

  adsManager.addEventListener(
      google.ima.AdErrorEvent.Type.AD_ERROR,
      onAdError);
  adsManager.addEventListener(
      google.ima.AdEvent.Type.CONTENT_PAUSE_REQUESTED,
      onContentPauseRequested);
  adsManager.addEventListener(
      google.ima.AdEvent.Type.CONTENT_RESUME_REQUESTED,
      onContentResumeRequested);
}

...

function onContentPauseRequested() {
  videoElement.pause();
}

function onContentResumeRequested() {
  videoElement.play();
}

Como acionar o recurso "clique para pausar" em dispositivos móveis

Como o AdContainer sobrepõe o elemento de vídeo, os usuários não podem interagir diretamente com o player subjacente. Isso pode confundir os usuários em dispositivos móveis, que esperam poder tocar em um player de vídeo para pausar a reprodução. Para resolver esse problema, o SDK do IMA transmite os cliques que não são processados pelo IMA da sobreposição de anúncios para o elemento AdContainer, onde eles podem ser processados. Isso não se aplica a anúncios lineares em navegadores não móveis, já que clicar no anúncio abre o link de clique.

Para implementar um clique para pausar, adicione um gerenciador de cliques ao AdContainer e acione eventos de reprodução ou pausa no vídeo subjacente.

ads.js (em inglês) 
...

function initializeIMA() {
  console.log("initializing IMA");
  adContainer = document.getElementById('ad-container');
  adContainer.addEventListener('click', adContainerClick);
  adDisplayContainer = new google.ima.AdDisplayContainer(adContainer, videoElement);
  adsLoader = new google.ima.AdsLoader(adDisplayContainer);

...

function adContainerClick(event) {
  console.log("ad container clicked");
  if(videoElement.paused) {
    videoElement.play();
  } else {
    videoElement.pause();
  }
}

...

Como acionar a reprodução em anúncios não lineares

O AdsManager pausa o vídeo do conteúdo quando um anúncio está pronto para exibição, mas esse comportamento não considera anúncios não lineares, em que o conteúdo precisa continuar a ser reproduzido enquanto o anúncio é exibido. Para oferecer compatibilidade com anúncios não lineares, detecte AdsManager para emitir o evento LOADED. Em seguida, verifique se o anúncio é linear. Se não for, retome a reprodução no elemento de vídeo.

ads.js (em inglês) 
...

function onAdsManagerLoaded(adsManagerLoadedEvent) {
  adsManager = adsManagerLoadedEvent.getAdsManager(
      videoElement);

  adsManager.addEventListener(
      google.ima.AdErrorEvent.Type.AD_ERROR,
      onAdError);
  adsManager.addEventListener(
      google.ima.AdEvent.Type.CONTENT_PAUSE_REQUESTED,
      onContentPauseRequested);
  adsManager.addEventListener(
      google.ima.AdEvent.Type.CONTENT_RESUME_REQUESTED,
      onContentResumeRequested);
  adsManager.addEventListener(
      google.ima.AdEvent.Type.LOADED,
      onAdLoaded);
}

...

function onAdLoaded(adEvent) {
  var ad = adEvent.getAd();
  if (!ad.isLinear()) {
    videoElement.play();
  }
}

Pronto! Agora você está solicitando e exibindo anúncios com o SDK do IMA. Para saber mais sobre os recursos mais avançados do SDK, consulte os outros guias ou as amostras no GitHub.