Começar

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

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

Visão geral do IMA para o cliente

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

  • AdDisplayContainer: um objeto contêiner em que os anúncios são renderizados.
  • AdsLoader: um objeto que solicita anúncios e gerencia eventos de respostas de solicitações de anúncios. É necessário instanciar apenas um carregador de anúncios, que pode ser reutilizado durante a vida útil do aplicativo.
  • AdsRequest: um objeto que define uma solicitação de anúncio. As solicitações de anúncios especificam o URL da tag de anúncio VAST, além de outros parâmetros, como as dimensões do anúncio.
  • AdsManager: um objeto que contém a resposta à solicitação de anúncios, controla a reprodução de anúncios e detecta eventos de anúncios disparados pelo SDK.

Pré-requisitos

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

  • Três arquivos vazios:
    • index.html
    • style.css
    • ads.js
  • Python instalado no computador ou um servidor da Web para usar nos testes

1. Iniciar um servidor de desenvolvimento

Como o SDK do IMA carrega dependências pelo mesmo protocolo da página de origem, 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 do diretório que contém o arquivo index.html, execute:
      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 (em inglês).

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 em 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, no ads.js, a reprodução de vídeo é acionada quando o botão de reprodução é 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 esta etapa, ao abrir index.html no navegador (por meio do servidor de desenvolvimento), você verá o elemento de vídeo, e o vídeo começará quando você clicar no botão de reprodução.

3. Importar o SDK do IMA

Em seguida, adicione a estrutura do IMA usando uma tag de script em index.html, antes da tag de 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áginas e de players 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 a página terminar de carregar, inicialize o SDK do IMA.
  • Quando o botão de reprodução do vídeo receber um clique, carregue os anúncios (a menos que eles já estejam carregados).
  • Quando a janela do navegador for redimensionada, atualize as dimensões do elemento de vídeo e adsManager para tornar a página 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 de anúncios

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 a anúncios. Esse contêiner precisa ser dimensionado para sobrepor o elemento de vídeo do canto superior esquerdo. A altura e a largura dos anúncios nesse contêiner são definidas pelo objeto adsManager. Assim, não é necessário definir esses valores manualmente.

Para implementar esse elemento de contêiner do anúncio, primeiro crie um novo div no elemento video-container. Em seguida, atualize o CSS para posicionar o elemento no canto superior esquerdo da 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 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 outro URL de tag de anúncio usando o Video Suite Inspector 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úncios, 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
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. AdsManager carrega os anúncios individuais conforme definido pela resposta ao URL da tag de anúncio.

Além disso, resolva todos os erros que possam ocorrer durante o processo de carregamento. Se os anúncios não carregarem, confira se a reprodução de mídia continua, sem anúncios, para não interferir na experiência do usuário.

ads.js
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 gerenciador de anúncios

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

ads.js
...

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 gerenciador de anúncios 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 da janela precisará chamar adsManager.resize().

ads.js
...

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 gcp

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 pausa no conteúdo de vídeo e registrar erros.

Como processar os erros

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

ads.js
...

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 a AdsManager estiver pronta para inserir um anúncio para exibição, ela 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, o AdsManager dispara o evento CONTENT_RESUME_REQUESTED. Processe esse evento reiniciando a reprodução no vídeo do conteúdo subjacente.

ads.js
...

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();
}

Acionamento do recurso "clique para pausar" em dispositivos móveis

Como o AdContainer se sobrepõe ao elemento de vídeo, os usuários não podem interagir diretamente com o player subjacente. Isso pode confundir os usuários de 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 todos os cliques não processados pelo IMA da sobreposição de anúncios para o elemento AdContainer, onde eles podem ser gerenciados. Isso não se aplica a anúncios lineares em navegadores que não são para dispositivos móveis, já que um clique no anúncio abre o link de clique.

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

ads.js
...

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 de conteúdo quando um anúncio está pronto para ser reproduzido, 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 o AdsManager para emitir o evento LOADED. Em seguida, verifique se o anúncio é linear e, se não for, retome a reprodução no elemento de vídeo.

ads.js
...

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 recursos avançados do SDK, consulte os outros guias ou os exemplos no GitHub (em inglês).