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.
- Usando uma linha de comando, no diretório que contém
seu arquivo index.html execute:
python -m http.server 8000
- 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>
<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, 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
...
</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
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.
...
<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.
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.
...
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().
...
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.
...
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.
...
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.
...
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.
...
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.