Usar a API Ad Placement

A API Ad Placement contém duas funções: adBreak() e adConfig(), definidas no seguinte namespace global. A maioria dos argumentos são funções que você fornece e que permitem processar as etapas principais de preparação e exibição de um anúncio:

adBreak({
   type: '<type>',                      // The type of this placement
   name: '<name>',                      // A descriptive name for this placement
   beforeAd: () => {},                  // Prepare for the ad. Mute and pause the game flow
   afterAd: () => {},                   // Resume the game and un-mute the sound
   beforeReward: (showAdFn) => {},      // Show reward prompt (call showAdFn() if clicked)
   adDismissed: () => {},               // Player dismissed the ad before completion
   adViewed: () => {},                  // Ad was viewed and closed
   adBreakDone: (placementInfo) => {},  // Always called (if provided) even if an ad didn't show
});

adConfig({
   preloadAdBreaks: 'on|auto',      // Should ads always be preloaded
   sound: 'on|off',                 // Is sound currently enabled within the game
});

Essas funções são usadas para colocar e configurar anúncios no seu jogo. Os argumentos mostrados acima são os únicos válidos que podem ser transmitidos a essas funções. Diferentes tipos de anúncios exigem diferentes subconjuntos desses argumentos, conforme detalhado abaixo.

adBreak() é a função principal para veicular anúncios no seu jogo. Ele define uma posição de anúncio e usa um objeto chamado configuração de posição que especifica tudo o que é necessário para mostrar um anúncio.

A função adBreak() define um canal em que um anúncio pode ser mostrado. A exibição de um anúncio depende de fatores como:

• O tipo de posição de anúncio que você declarou
  • O anúncio está no início do jogo? Entre os níveis? Em um momento em que o jogador pausou o jogo?
• Se existe um anúncio adequado para o player atual
  • Este anúncio é relevante para eles?
  • Ela é consistente com as configurações de privacidade de dados e consentimento?
• O número de anúncios que o player viu recentemente
• As configurações de controle, por exemplo, a frequência de anúncios que você configurou para este jogo
  • Como dicas na tag ou
  • No Google AdSense. Os controles disponíveis no Google AdSense vão evoluir com o tempo.

O tipo de anúncio exibido também depende de fatores semelhantes.

Uma chamada para adBreak() pode não mostrar um anúncio. Ele apenas declara um lugar onde um anúncio pode ser mostrado.

Isso é diferente das APIs tradicionais, em que o código sempre sabe se um anúncio está disponível, e você decide no jogo se ele será mostrado. Essa abordagem de deixar a API Ad Placement decidir se um anúncio é mostrado em um determinado local é um padrão às vezes chamado de "inversão de controle".

O motivo da transição da nossa API de jogos para esse modelo é, primeiro, que ele encurta o código que você precisa escrever no jogo. Em segundo lugar, isso facilita a veiculação de posições em conformidade com a política e uma ótima experiência do usuário, o que nos permitiu oferecer alguns dos nossos formatos de melhor performance para editores de jogos. Por fim, ele separa de forma mais clara o processo de veiculação de anúncios no jogo das decisões de monetização sobre o tipo e o número de anúncios a serem mostrados.

Queremos que você possa mudar as configurações de monetização e controlar a experiência do usuário sem precisar editar e lançar uma nova versão do jogo, inicialmente especificando dicas na tag. Mas, em versões futuras, vamos oferecer controles diretamente nos front-ends do Google AdSense e da AdMob.

Intersticiais

Um anúncio intersticial é um anúncio em tela cheia que pode ser exibido em diferentes momentos do jogo, como quando o jogador inicia o jogo ou depois que ele conclui uma fase. Ele pausa o jogo, cobre todo o documento, e o jogador pode clicar no anúncio (nesse caso, ele aparece em outra guia do navegador) ou dispensá-lo para continuar jogando.

Observação: um anúncio intersticial pode ser mostrado antes mesmo de o jogo carregar a interface do usuário. Esse tipo de anúncio é chamado de pré-vídeo e precisa ser tratado de maneira um pouco diferente dos intersticiais comuns. Saiba mais sobre os pré-rolls

Para veicular um anúncio intersticial, preencha os seguintes campos na configuração de posicionamento:

adBreak({
   type: 'start',           // The type of this placement
   name: 'game_started',    // A descriptive name for this placement
   beforeAd: beforeAd,      // Prepare for the ad. Mute and pause the game flow
   afterAd: afterAd,        // Resume the game and un-mute the sound
   adBreakDone: breakDone,  // Always called (if provided) even if an ad didn't show
});

O argumento type é obrigatório, e recomendamos que você sempre nomeie suas posições. Os outros callbacks são opcionais.

Sequência de chamadas

Revise a sequência de chamadas de um anúncio intersticial.

Descrição

Intersticial – sequência de chamadas detalhada
Seu jogo H5	API Ad Placement
	Inicialização e pré-carregamento de anúncios
Executar o jogo
Uma boa oportunidade para mostrar um anúncio... adBreak() →
	Há um anúncio disponível, e agora é um bom momento para mostrá-lo... ← beforeAd()
O jogo é pausado, o som é silenciado e o anúncio fica pronto para ser exibido. return para a API →
	A API Ad Placement renderiza o anúncio intersticial. O player pode clicar no anúncio, que é exibido em uma nova guia. Eles precisam dispensar o anúncio para continuar jogando.
	← afterAd() é chamado se um anúncio foi mostrado
O jogo é retomado e o som é ativado.
	← adBreakDone()adBreakDone() é sempre chamado, mesmo que um anúncio não tenha sido mostrado.
O jogo registra análises sobre essa posição.

Observações

• adBreak() é uma função assíncrona que retorna imediatamente.
• Se não houver um anúncio para mostrar em um canal, nenhum dos callbacks será chamado, ou seja, nenhum de beforeAd(),afterAd() será chamado.
• Para garantir que o jogo não continue sendo executado enquanto o anúncio estiver sendo exibido, use o callback beforeAd() para silenciar o som e pausar o jogo.
• beforeAd() é síncrono. A API Ad Placement não mostra um anúncio até que ele seja retornado.
• Reinicie o jogo e ative o som quando receber a chamada afterAd().
• Se fornecido, adBreakDone() sempre será chamado, mesmo que um anúncio não tenha sido mostrado nessa posição.
• A chamada de adBreak() enquanto outro anúncio está sendo exibido vai falhar, e um aviso será mostrado no console JavaScript.

Anúncios precedentes

Um anúncio precedente é um intersticial que aparece antes de o jogo carregar a interface. É a primeira coisa que um jogador vê ao acessar seu jogo. Como um prerroll acontece muito cedo no carregamento da página, e seu jogo ainda não foi exibido, as chamadas usuais para pausar e silenciar o jogo não são necessárias. Em vez disso, use o callback adBreakDone() para sequenciar o início do jogo com o anúncio, ou seja, renderizar a interface e começar a tocar o som. Só é possível acionar uma pré-roll por carregamento de página.

Sequência de chamadas

A chamada de um pré-roll é feita muito cedo no carregamento da página. Como o jogo ainda não renderizou a interface neste momento, não transmita os callbacks beforeAd() e afterAd(). Em vez disso, use o callback adBreakDone() para iniciar o jogo após a posição, já que ele é chamado mesmo que não haja anúncio.

Chamar o código a seguir no início da lógica do jogo vai inserir um anúncio prerroll. A interface não pode ser renderizada antes da chamada desse código.

// Game must not be running.
// Nothing in the game area should be clickable
adBreak({
   type: ‘preroll',
   adBreakDone: startGame,
})

Prérrol – sequência detalhada de chamadas
Seu jogo H5	API Ad Placement
	A inicialização da API e o pré-armazenamento em cache de anúncios começam
Está em execução, mas não foi iniciado e não mostrou uma interface
adBreak(type:'preroll',…) →
	A API Ad Placement termina de inicializar e carregar anúncios. Se houver um anúncio, ele será mostrado. O player pode clicar no anúncio, que é exibido em uma nova guia. É preciso dispensar a mensagem para que o jogo comece.
	← adBreakDone() é sempre chamado, mesmo que um anúncio não tenha sido mostrado.
A interface do jogo é renderizada na tela, e o jogador pode interagir com ela. O jogo pode usar o objeto placementInfo transmitido para adBreakDone() conforme necessário (por exemplo, para registrar outras análises).

Observações

• Um anúncio precedente sempre tenta pré-carregar anúncios:
  • Não é necessário chamar adConfig(preloadAds: ‘on') com pré-rolls.
• Assim como outros canais de anúncio, um pre-roll pode ou não mostrar um anúncio.
• beforeAd() e afterAd() não devem ser transmitidos para um pré-roll.
  • Como os anúncios precedentes são veiculados antes do início do jogo, não é necessário pausar ou silenciar o som do jogo.
  • Se você transmitir beforeAd() ou afterAd() com um pré-roll, a chamada vai falhar e um erro será registrado no console JavaScript.
• Um anúncio precedentes espera automaticamente que a API Ad Placement seja inicializada e pré-carregue anúncios:
  • No entanto, há um tempo limite (2s) que impede que a chamada seja adiada indefinidamente. Isso garante que adBreakDone() seja chamado de maneira oportuna e que o jogo seja iniciado.
  • adBreakDone() é sempre chamado, mesmo que não haja um anúncio.
• Recomendamos usar um pré-roll para veicular anúncios antes do início do jogo.
  • Como alternativa, use o callback onReady() para adConfig() como um mecanismo para sequenciar a lógica do jogo com a inicialização da API e o pré-carregamento de anúncios.

Anúncios premiados

Com um anúncio premiado, você pode recompensar os jogadores com itens no app se eles escolherem assistir a um anúncio. Enquanto os intersticiais são desativados, um player vê o anúncio e pode dispensá-lo. Os anúncios premiados são ativados. O jogador escolhe se e quando quer assistir um anúncio para receber uma recompensa.

Ao contrário dos intersticiais, em que o player pode dispensar o anúncio a qualquer momento, para receber uma recompensa, ele precisa assistir o anúncio por um período mínimo (que pode variar dependendo do criativo mostrado).

Como os anúncios premiados são opcionais para o jogador, eles exigem uma integração mais profunda no fluxo do jogo. Você precisa fornecer funções para renderizar um comando de recompensa no jogo e alocar a recompensa ao jogador se ele assistir ao anúncio.

Os prêmios não podem ter valor fora do seu app, não podem ter valor monetário (ou ser facilmente trocados por ele) e não podem ser comercializados ou trocados por produtos e serviços. Além disso, você não pode incentivar os jogadores a clicar em anúncios. Consulte o rascunho da política para intersticiais e recompensados para mais detalhes.

Como as recompensas são opcionais para o jogador, você pode adicioná-las em qualquer lugar que faça sentido no jogo e usá-las além dos intersticiais. Assim como os intersticiais, esses posicionamentos são oportunidades para mostrar anúncios premiados. A API Ad Placement só vai chamar seu código se um anúncio premiado for realmente oferecido em um determinado ponto do jogo.

Mais uma vez, o objetivo é permitir que você integre seu jogo com a API Ad Placement uma vez e, com o tempo, usando controles na tag ou no AdSense, mude a combinação precisa de anúncios ativados sem precisar recodificar e relançar o jogo.

O tipo de um posicionamento premiado é sempre 'reward', e todos os campos na configuração de posicionamento podem ser usados.

adBreak({
   type: 'reward',                      // The type of this placement
   name: '<name>',                      // A descriptive name for this placement
   beforeAd: () => {},                  // Prepare for the ad. Mute and pause the game flow
   afterAd: () => {},                   // Resume the game and re-enable sound
   beforeReward: (showAdFn) => {},      // Show reward prompt (call showAdFn() if clicked)
   adDismissed: () => {},               // Player dismissed the ad before it finished.
   adViewed: () => {},                  // Player watched the ad–give them the reward.
   adBreakDone: (placementInfo) => {},  // Always called (if provided) even if an ad didn't show
});

As principais funções novas são beforeReward(), que é o gatilho que sinaliza que você deve renderizar a solicitação de recompensa, e adViewed(), que é chamada quando o jogador assiste o anúncio, para que você possa alocar a recompensa.

Você pode definir um posicionamento premiado da seguinte maneira:

adBreak({
   type: 'reward',
   name: 'new_life_reward_1',
   beforeAd: pauseGame,
   afterAd: restartGame,
   beforeReward: showRewardPrompt,
   adDismissed: adDismissed,
   adViewed: adViewed,
   adBreakDone: breakDone,
});

Os anúncios premiados começam com um aviso no jogo oferecendo uma recompensa ao jogador se ele assistir um anúncio.

Sequência de chamadas para um anúncio premiado

Descrição

Anúncio premiado: sequência de chamadas detalhada
Seu jogo H5	API Ad Placement
	Inicialização e pré-armazenamento em cache de anúncios
Executar o jogo
adBreak(type:'reward', ... ) →
	Há um anúncio disponível, então comece a inserir um anúncio premiado. beforeReward() é chamado de forma síncrona, imediatamente após a chamada para adBreak(). ← beforeReward(showAdFn)
O jogo renderiza a solicitação de recompensa. Isso oferece ao jogador a oportunidade de receber uma recompensa ao assistir um anúncio. Mais de um tipo de recompensa pode ser oferecido (por exemplo, uma nova vida ou uma moeda de ouro). O jogador pode clicar em um aviso de recompensa, dispensá-lo ou simplesmente ignorá-lo. Se eles clicarem em um comando, o jogo vai armazenar o tipo de recompensa solicitada e chamar showAdFn().... Caso contrário, se o aviso de recompensa for dispensado ou ignorado, nada vai acontecer até que você faça outra chamada para adBreak() com um tipo de veiculação de recompensa. Nesse momento, a API Ad Placement será redefinida e limpará o estado dessa chamada. Se o app chamar showAdFn de um intervalo de anúncio anterior, isso não terá efeito.
showAdFn() →
	← beforeAd()
O jogo é pausado, o som é silenciado e o anúncio fica pronto para ser exibido. return para a API →
	A API mostra o anúncio. Ele tem um botão para dispensar e uma contagem regressiva de quanto tempo resta no anúncio.
SE o player dispensar o anúncio...
	← adDismissed()
O jogador dispensou o anúncio, e o jogo não emitiu a recompensa.
ELSE o player assiste o anúncio até o fim...
	← adViewed()
O jogador assistiu o anúncio até o fim, e o jogo emitiu a recompensa. Normalmente, isso é feito definindo um estado do jogo que é captado quando o jogo é reiniciado com a chamada para afterAd() abaixo.
Depois que o anúncio é assistido ou dispensado...
	← afterAd() é chamado se um anúncio foi mostrado
O jogo é retomado e o som é ativado.
	← adBreakDone()adBreakDone() é sempre chamado, mesmo que um anúncio não tenha sido mostrado.
O jogo registra análises sobre essa posição.

Observações

• adBreak() é uma função assíncrona que retorna imediatamente.
• Se não houver um anúncio para mostrar em um posicionamento, nenhum dos callbacks será chamado, ou seja, nenhum de beforeAd() e beforeReward() será chamado.
• Para garantir que o jogo não continue sendo executado enquanto o anúncio estiver sendo exibido, use o callback beforeAd() para silenciar o som e pausar o jogo.
• beforeAd() é síncrono. A API Ad Placement não mostra um anúncio até que ele seja retornado.
• Reinicie o jogo e ative o som quando receber a chamada afterAd().
• Se fornecido, adBreakDone() sempre será chamado, mesmo que um anúncio não tenha sido mostrado nessa posição.
• A chamada de adBreak() enquanto outro anúncio está sendo exibido vai falhar, e um aviso será mostrado no console JavaScript.