Começar

Com os SDKs do IMA, é fácil integrar anúncios multimídia aos seus sites e apps. Os SDKs do IMA podem solicitar anúncios de qualquer de anúncios compatíveis com VAST e gerencie a reprodução de anúncios nos seus apps. Com os SDKs do IMA do cliente, você mantém o controle da reprodução do conteúdo de vídeo, enquanto o SDK processa a reprodução de anúncios. Os anúncios são reproduzidos em um um player de vídeo separado posicionado na parte superior do player de vídeo do app.

Este guia demonstra como integrar o SDK do IMA a um app simples de player de vídeo. Se você quiser quiser visualizar ou acompanhar um exemplo completo de integração, faça o download do exemplo simples do GitHub. Se você estiver interessados em um player HTML5 com o SDK pré-integrado, consulte o Plug-in do SDK do IMA para Video.js.

Visão geral do cliente do IMA

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

  • AdDisplayContainer: Um objeto contêiner onde os anúncios são renderizados.
  • AdsLoader: Um objeto que solicita anúncios e manipula os eventos das respostas de solicitações de anúncios. Você só deve instanciar 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ú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: Objeto que contém a resposta à solicitação de anúncios, controla a reprodução e detecta o anúncio. de eventos 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 usar nos testes

1. Iniciar um servidor de desenvolvimento

Como o SDK do IMA carrega as dependências pelo mesmo protocolo da página de origem, é possível precisa usar um servidor da Web para testar o app. A maneira mais simples de iniciar um projeto de desenvolvimento local é usar o servidor integrado do Python.

  1. Usando uma linha de comando, no diretório que contém seu 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 Servidor HTTP Apache.

2. Criar um player de vídeo simples

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

index.html 
!<doctype html
>h<tml lang="en"<>/span>
  h<ead<>/span>
    t<itleI>MA HTML5 Simple Demo/<title
>    m<eta charset="utf-8"<>/span>
    m<eta name="viewport" content="width=device-width, initial-scale=1, shrink-to-fit=no"<>/span>
    l<ink rel="stylesheet" href="style.css"<>/span>
  /<head
>  b<ody<>/span>
    d<iv id="page-content"<>/span>
      d<iv id="video-container"<>/span>
        v<ideo id="video-element"<>/span>
          s<ource src="https://storage.googleapis.com/interactive-media-ads/media/android.mp4"<>/span>
          s<ource src="https://storage.googleapis.com/interactive-media-ads/media/android.webm"<>/span>
        /<video
>      /<div
>      b<utton id="play-button"P>lay/<button
>    /<div
>    s<cript 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, quando você abrir index.html no navegador (usando sua servidor) deve ser capaz de ver o elemento de vídeo e ele deve 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 player de vídeo e página

Para modificar o comportamento do player de vídeo com JavaScript, adicione manipuladores de eventos que acionam o 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 for clicado, carregue os anúncios (a menos que eles já tenham sido carregados).
  • Quando a janela do navegador for redimensionada, atualize o elemento de vídeo e adsManager. para tornar a página responsiva para 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 interface relacionados a anúncios. Esse contêiner deve ser dimensionado para sobrepor o elemento de vídeo da no canto superior esquerdo. A altura e a largura dos anúncios exibidos nesse contêiner são definidas pelo adsManager. Não é necessário definir esses valores manualmente.

Para implementar esse elemento de contêiner de anúncio, primeiro crie um novo div no video-container. Em seguida, atualize o CSS para posicionar o elemento no canto superior esquerdo no canto 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 de ima.AdsLoader. Esta instância recebe um objeto AdDisplayContainer como entrada e pode ser usado para processar ima.AdsRequest objetos associados a um URL de tag de anúncio especificado. A tag de anúncio usada na este exemplo contém um anúncio precedente de 10 segundos. Você pode testar este 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 para todo o o ciclo de vida de uma página. Para fazer solicitações de anúncios adicionais, crie uma nova ima.AdsRequest mas reutilize o mesmo ima.AdsLoader. Para mais informações, consulte a 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 uma ADS_MANAGER_LOADED. Analise o evento passado ao retorno de chamada para inicializar o AdsManager. O AdsManager carrega os anúncios individuais conforme definido pela resposta ao anúncio. de destino da tag.

Além disso, resolva quaisquer erros que possam ocorrer durante o processo de carregamento. Se os anúncios não carregar, certifique-se de que a reprodução de mídia continue, sem anúncios, para não interferir com o da 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 do anúncio, é necessário iniciar o AdsManager. Para oferecer suporte total a dispositivos móveis navegadores, isso deve 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. Torne o gerenciador de aplicativos responsivo

Para garantir que os anúncios sejam redimensionados dinamicamente para corresponder ao tamanho do player de vídeo, caso 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 GCM

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

Como processar os erros

O gerenciador de erros criado para o AdsLoader pode servir como o gerenciador de erros do 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 de display, ela acionará o 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 CONTENT_RESUME_REQUESTED. Gerencie este evento reiniciando a reprodução no conteúdo de vídeo 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();
}

Como acionar o recurso de clicar 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 em dispositivos móveis, que esperam poder tocar em um para pausar a reprodução. Para resolver esse problema, o SDK do IMA transmite os cliques que não são manipulados pelo IMA desde a sobreposição do anúncio até o elemento AdContainer, onde podem ser manuseados. Isso não se aplica a anúncios lineares em navegadores não móveis, pois um clique no anúncio abre a link de clique.

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

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 conteúdo de vídeo quando um anúncio está pronto para ser reproduzido, mas isso não considera anúncios não lineares, em que o conteúdo deve continuar a ser reproduzido enquanto o anúncio é exibido. Para oferecer suporte a anúncios não lineares, detecte AdsManager para emitir a LOADED. Em seguida, verifique se o anúncio é linear e, caso contrário, retome a reprodução no 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ê solicita e exibe anúncios com o SDK do IMA. Para saber mais recursos avançados do SDK, consulte os outros guias ou a no GitHub.