Configurar o SDK do IMA

Os SDKs do IMA facilitam a integração de anúncios multimídia aos seus sites e apps. Os SDKs do IMA podem solicitar anúncios de qualquer servidor de anúncios compatível com VAST e gerenciar a veiculaçã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 de conteúdo, enquanto o SDK lida com a reprodução de anúncios. Os anúncios são veiculados em um player de vídeo separado posicionado sobre o player de vídeo de conteúdo do app.

Este guia demonstra como integrar o SDK do IMA a um app de player de vídeo simples. Se você quiser ver ou seguir uma integração de exemplo 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 do lado do cliente

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

  • AdDisplayContainer: um objeto de contêiner que especifica onde a IMA renderiza elementos da interface do anúncio e mede a visibilidade, incluindo Active View e Open Measurement.
  • AdsLoader: um objeto que solicita anúncios e processa eventos de respostas de solicitação de anúncios. Você só precisa instanciar um carregador de anúncios, que pode ser reutilizado durante toda a 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 e 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 ouve eventos de anúncios acionados 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 uso em testes

1. Iniciar um servidor de desenvolvimento

Como o SDK do IMA carrega dependências usando 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 o arquivo index.html, execute: 
      python -m http.server 8000
  2. Em um navegador da Web, acesse http://localhost:8000/.

Você também pode 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 união, e um botão para acionar a reprodução. O exemplo a seguir importa o SDK do IMA e configura o elemento do contêiner AdDisplayContainer. Para mais detalhes, consulte as etapas Importar o SDK do IMA e Criar o contêiner de anúncios . 

<html>
  <head>
    <title>IMA HTML5 Simple Demo</title>
    <link rel="stylesheet" href="style.css">
  </head>

  <body>
    <div id="mainContainer">
      <div id="content">
        <video id="contentElement">
          <source src="https://storage.googleapis.com/gvabox/media/samples/stock.mp4"></source>
        </video>
      </div>
      <div id="adContainer"></div>
    </div>
    <button id="playButton">Play</button>
    <script src="//imasdk.googleapis.com/js/sdkloader/ima3.js"></script>
    <script src="ads.js"></script>
  </body>
</html>

index.html
 
#mainContainer {
  position: relative;
  width: 640px;
  height: 360px;
}

#content {
  position: absolute;
  top: 0;
  left: 0;
  width: 640px;
  height: 360px;
}

#contentElement {
  width: 640px;
  height: 360px;
  overflow: hidden;
}

#playButton {
  margin-top:10px;
  vertical-align: top;
  width: 350px;
  height: 60px;
  padding: 0;
  font-size: 22px;
  color: white;
  text-align: center;
  text-shadow: 0 1px 2px rgba(0, 0, 0, 0.25);
  background: #2c3e50;
  border: 0;
  border-bottom: 2px solid #22303f;
  cursor: pointer;
  -webkit-box-shadow: inset 0 -2px #22303f;
  box-shadow: inset 0 -2px #22303f;
}
style.css
 
let adsManager;
let adsLoader;
let adDisplayContainer;
let isAdPlaying;
let isContentFinished;
let playButton;
let videoContent;
let adContainer;

// On window load, attach an event to the play button click
// that triggers playback of the video element.
window.addEventListener('load', function(event) {
  videoContent = document.getElementById('contentElement');
  adContainer = document.getElementById('adContainer');
  adContainer.addEventListener('click', adContainerClick);
  playButton = document.getElementById('playButton');
  playButton.addEventListener('click', playAds);
  setUpIMA();
});
ads.js

Adicione 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 para dispositivos móveis. Por fim, em ads.js, declare suas variáveis e acione a reprodução do vídeo ao clicar no botão de reprodução.

O snippet de código ads.js contém uma chamada para setUpIMA(), que é definida na seção Inicialize o AdsLoader e faça uma solicitação de anúncios .

3. Importar o SDK do IMA

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

<script src="//imasdk.googleapis.com/js/sdkloader/ima3.js"></script>
index.html

4. Criar o contêiner de anúncios

Na maioria dos navegadores, o SDK do IMA usa um elemento de contêiner de anúncios dedicado para mostrar anúncios e elementos de interface 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 colocados nesse contêiner são definidas pelo objeto adsManager. Portanto, não é necessário definir esses valores manualmente.

Para implementar esse elemento de contêiner de anúncios, primeiro crie uma nova div no elemento video-container. Em seguida, atualize o CSS para posicionar o elemento no canto superior esquerdo do video-element. Por fim, adicione a função createAdDisplayContainer() para criar o objeto AdDisplayContainer usando o novo contêiner de anúncios div. 

<div id="adContainer"></div>
index.html
 
#adContainer {
  position: absolute;
  top: 0;
  left: 0;
  width: 640px;
  height: 360px;
}
style.css
 
/**
 * Sets the 'adContainer' div as the IMA ad display container.
 */
function createAdDisplayContainer() {
  adDisplayContainer = new google.ima.AdDisplayContainer(
      document.getElementById('adContainer'), videoContent);
}
ads.js

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

Para solicitar anúncios, crie uma instância de AdsLoader. O construtor AdsLoader usa um objeto AdDisplayContainer como entrada e pode ser usado para processar objetos 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 da tag de anúncio usando o Video Suite Inspector do IMA.

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

Detecte e responda a anúncios carregados e eventos de erro usando AdsLoader.addEventListener. Detecte os seguintes eventos:

  • ADS_MANAGER_LOADED
  • AD_ERROR

Para criar os listeners onAdsManagerLoaded() e onAdError(), consulte o exemplo abaixo: 

/**
 * Sets up IMA ad display container, ads loader, and makes an ad request.
 */
function setUpIMA() {
  // Create the ad display container.
  createAdDisplayContainer();
  // Create ads loader.
  adsLoader = new google.ima.AdsLoader(adDisplayContainer);
  // Listen and respond to ads loaded and error events.
  adsLoader.addEventListener(
      google.ima.AdsManagerLoadedEvent.Type.ADS_MANAGER_LOADED,
      onAdsManagerLoaded, false);
  adsLoader.addEventListener(
      google.ima.AdErrorEvent.Type.AD_ERROR, onAdError, false);

  // An event listener to tell the SDK that our content video
  // is completed so the SDK can play any post-roll ads.
  const contentEndedListener = function() {
    // An ad might have been playing in the content element, in which case the
    // content has not actually ended.
    if (isAdPlaying) return;
    isContentFinished = true;
    adsLoader.contentComplete();
  };
  videoContent.onended = contentEndedListener;

  // Request video ads.
  const 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 = 640;
  adsRequest.linearAdSlotHeight = 400;

  adsRequest.nonLinearAdSlotWidth = 640;
  adsRequest.nonLinearAdSlotHeight = 150;

  adsLoader.requestAds(adsRequest);
}
ads.js

6. Responder a eventos do AdsLoader

Quando o AdsLoader carrega anúncios, ele 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.

Processe todos os erros que ocorrerem durante o carregamento. Se os anúncios não carregarem, verifique se a reprodução de mídia continua sem anúncios para evitar interferência na visualização do conteúdo pelo usuário. 

/**
 * Handles the ad manager loading and sets ad event listeners.
 * @param {!google.ima.AdsManagerLoadedEvent} adsManagerLoadedEvent
 */
function onAdsManagerLoaded(adsManagerLoadedEvent) {
  // Get the ads manager.
  const adsRenderingSettings = new google.ima.AdsRenderingSettings();
  adsRenderingSettings.restoreCustomPlaybackStateOnAdBreakComplete = true;
  // videoContent should be set to the content video element.
  adsManager =
      adsManagerLoadedEvent.getAdsManager(videoContent, adsRenderingSettings);

  // Add listeners to the required events.
  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);
}

/**
 * Handles ad errors.
 * @param {!google.ima.AdErrorEvent} adErrorEvent
 */
function onAdError(adErrorEvent) {
  // Handle the error logging.
  console.log(adErrorEvent.getError());
  adsManager.destroy();
}
ads.js

Para mais detalhes sobre os listeners definidos na função onAdsManagerLoaded(), consulte as seguintes subseções:

Processar erros AdsManager

O gerenciador de erros criado para o AdsLoader também pode servir como gerenciador de erros para o AdsManager. Consulte o manipulador de eventos que reutiliza a função onAdError(). 

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

Processar eventos de reprodução e pausa

Quando o AdsManager está pronto para inserir um anúncio para exibição, ele aciona o evento CONTENT_PAUSE_REQUESTED. Processe esse evento acionando uma pausa no player de vídeo. 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 de conteúdo. 

adsManager.addEventListener(
    google.ima.AdEvent.Type.CONTENT_PAUSE_REQUESTED, onContentPauseRequested);
adsManager.addEventListener(
    google.ima.AdEvent.Type.CONTENT_RESUME_REQUESTED,
    onContentResumeRequested);
ads.js

Para definições das funções onContentPauseRequested() e onContentResumeRequested(), consulte o exemplo a seguir: 

/**
 * Pauses video content and sets up ad UI.
 */
function onContentPauseRequested() {
  isAdPlaying = true;
  videoContent.pause();
  // This function is where you should setup UI for showing ads (for example,
  // display ad timer countdown, disable seeking and more.)
  // setupUIForAds();
}

/**
 * Resumes video content and removes ad UI.
 */
function onContentResumeRequested() {
  isAdPlaying = false;
  if (!isContentFinished) {
    videoContent.play();
  }
  // This function is where you should ensure that your UI is ready
  // to play content. It is the responsibility of the Publisher to
  // implement this function when necessary.
  // setupUIForContent();
}
ads.js

Processar a reprodução de conteúdo durante anúncios não lineares

O AdsManager pausa o vídeo do 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 continua sendo reproduzido enquanto o anúncio é exibido. 

adsManager.addEventListener(google.ima.AdEvent.Type.LOADED, onAdLoaded);
ads.js

Para oferecer suporte a anúncios não lineares, detecte o AdsManager para emitir o evento LOADED. Verifique se o anúncio é linear. Se não for, retome a reprodução no elemento de vídeo.

Para conferir a definição da função onAdLoaded(), consulte o exemplo a seguir. 

/**
 * Handles ad loaded event to support non-linear ads. Continues content playback
 * if the ad is not linear.
 * @param {!google.ima.AdEvent} adEvent
 */
function onAdLoaded(adEvent) {
  let ad = adEvent.getAd();
  if (!ad.isLinear()) {
    videoContent.play();
  }
}
ads.js

7. 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. 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, porque clicar no anúncio abre o link de clique.

Para implementar o recurso "clique para pausar", adicione a função de gerenciador de cliques adContainerClick() chamada no listener de carregamento da janela. 

/**
 * Handles clicks on the ad container to support expected play and pause
 * behavior on mobile devices.
 * @param {!Event} event
 */
function adContainerClick(event) {
  console.log("ad container clicked");
  if(videoContent.paused) {
    videoContent.play();
  } else {
    videoContent.pause();
  }
}
ads.js

8. Iniciar o AdsManager

Para iniciar a exibição de anúncios, inicie e inicie o AdsManager. Para oferecer suporte total aos navegadores para dispositivos móveis, em que não é possível exibir anúncios automaticamente, acione a reprodução de anúncios com base nas interações do usuário com a página, como clicar no botão "play". 

/**
 * Loads the video content and initializes IMA ad playback.
 */
function playAds() {
  // Initialize the container. Must be done through a user action on mobile
  // devices.
  videoContent.load();
  adDisplayContainer.initialize();

  try {
    // Initialize the ads manager. This call starts ad playback for VMAP ads.
    adsManager.init(640, 360);
    // Call play to start showing the ad. Single video and overlay ads will
    // start at this time; the call will be ignored for VMAP ads.
    adsManager.start();
  } catch (adError) {
    // An error may be thrown if there was a problem with the VAST response.
    videoContent.play();
  }
}
ads.js

9. Oferecer suporte ao redimensionamento do player

Para que os anúncios sejam redimensionados dinamicamente e correspondam ao tamanho de um player de vídeo ou às mudanças na orientação da tela, chame adsManager.resize() em resposta aos eventos de redimensionamento de janela. 

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

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.