Usar a API Ad Placement

A API Ad Placement contém duas funções: adBreak() e adConfig(), definidas no namespace global a seguir. A maioria dos argumentos são funções que você fornece, o que permite que você execute as principais etapas 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 posicionar e configurar anúncios no seu jogo. Os argumentos mostrados acima são os únicos argumentos válidos que podem ser transmitidos para essas funções. Diferentes tipos de anúncios exigem diferentes subconjuntos desses argumentos, conforme detalhado abaixo.

adBreak() é a principal função para inserir anúncios no jogo. Ele define uma posição do anúncio e usa um objeto chamado configuração da posição, que especifica tudo o que é necessário para exibir um anúncio.

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

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

O tipo de anúncio exibido depende de fatores semelhantes.

Talvez uma chamada para adBreak() não exiba um anúncio. Ela simplesmente declara um lugar onde o anúncio pode ser exibido.

Ao contrário das APIs tradicionais, em que seu código sempre sabe se um anúncio está disponível, e você decide, no jogo, se quer exibi-lo. Essa abordagem de deixar a API Ad Placement decidir se o anúncio será exibido em uma posição específica é um padrão conhecido como "inversão de controle".

O motivo da transição da nossa API de jogos para esse modelo é que ela encurta o código que você precisa escrever no seu jogo. Em segundo lugar, facilita a entrega de posições em conformidade com as políticas com uma ótima experiência do usuário, o que, por sua vez, permitiu a entrega de alguns dos nossos formatos de melhor desempenho aos editores de jogos. Por fim, ele separa de maneira mais clara o processo de inserção de anúncios no jogo das decisões de monetização sobre o tipo e o número de anúncios que serão exibidos.

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. No entanto, em versões futuras, poderemos fornecer controles diretamente nos front-ends do Google AdSense e da AdMob.

Intersticiais

Um anúncio intersticial é um anúncio em tela cheia mostrado 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, o anúncio é exibido em uma guia diferente do navegador) ou dispensá-lo para continuar o jogo.

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

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

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. 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
Como executar o jogo
Uma boa oportunidade de mostrar um anúncio... adBreak() →
	Há um anúncio disponível, e agora é um bom momento para exibi-lo... ← beforeAd()
O jogo pausa, silencia o som e se prepara para mostrar o anúncio. return à API →
	A API Ad Placement renderiza o anúncio intersticial. O player pode clicar no anúncio (que aparece em uma nova guia). Eles precisam dispensar o anúncio para continuar jogando.
	← afterAd() será chamado se um anúncio for exibido
O jogo pausa e ativa o som.
	← adBreakDone()adBreakDone() é sempre chamado (mesmo que um anúncio não tenha sido exibido)
O jogo registra as análises sobre esta posição.

Observações

• adBreak() é uma função assíncrona que retorna imediatamente.
• Se não houver anúncios para exibir para uma posição, nenhum dos callbacks será chamado, ou seja, nenhum de beforeAd(), afterAd() será chamado.
• Para garantir que seu jogo não continue sendo executado enquanto o anúncio é exibido, use o callback beforeAd() para desativar o som e pausar o jogo.
• beforeAd() é síncrono, a API Ad Placement não mostrará um anúncio até que ele retorne.
• Reinicie o jogo e ative o som ao receber a chamada afterAd().
• Se fornecido, adBreakDone() sempre será chamado, mesmo que um anúncio não tenha sido exibido nesta posição.
• Chamar adBreak() enquanto outro anúncio está sendo exibido falhará e um aviso será exibido no Console JavaScript.

Anúncios precedentes

Um anúncio precedente é um intersticial mostrado antes do jogo carregar a IU. É a primeira coisa que um jogador vê ao navegar para o jogo. Como um anúncio precedente ocorre muito cedo no carregamento da página e seu jogo ainda não é exibido, as chamadas comuns para pausar e desativar o som do jogo não são necessárias. Em vez disso, você usa o callback adBreakDone() para sequenciar o início do jogo com o anúncio, ou seja, renderizar a IU e começar a tocar. Somente um anúncio precedente pode ser acionado para cada carregamento de página.

Sequência de chamadas

A chamada de um anúncio precedente é feita muito cedo no carregamento de página. Como seu jogo ainda não renderizou a IU, 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 isso é chamado mesmo que não tenha um anúncio.

Chamar o código a seguir colocará um anúncio precedente no início da lógica do jogo. A IU não deve ser renderizada antes que esse código seja chamado.

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

Anúncio precedente: sequência de chamadas detalhada
Seu jogo H5	API Ad Placement
	Inicialização da API e armazenamento em cache prévio de anúncios
Está em execução, mas não inicia e não exibe uma IU
adBreak(type:'preroll',…) →
	A API Ad Placement termina a inicialização e o carregamento de anúncios. Se houver um anúncio, ele será exibido. O player pode clicar no anúncio (que aparece em uma nova guia). É necessário dispensá-la para que o jogo comece.
	← adBreakDone() sempre é chamado (mesmo que um anúncio não tenha sido exibido)
A IU do jogo é renderizada para a 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 análises adicionais).

Observações

• Um anúncio precedente sempre tentará pré-carregar os anúncios:
  • Não é necessário chamar adConfig(preloadAds: ‘on') com anúncios precedentes.
• Assim como outras posições, um anúncio precedente pode ou não exibir um anúncio.
• beforeAd() e afterAd() não podem ser transmitidos para um anúncio precedente.
  • Como os anúncios precedentes são exibidos antes do início do jogo, não é necessário pausar ou desativar o som.
  • Se você transmitir beforeAd() ou afterAd() com um anúncio precedente, a chamada falhará e um erro será registrado no Console JavaScript.
• Um anúncio precedente automaticamente espera que a API Ad Placement inicialize e pré-carregue anúncios:
  • No entanto, há um tempo limite (2 s) que impede a chamada de atrasar indefinidamente. Isso garante que adBreakDone() seja chamado em tempo hábil e o jogo comece.
  • O adBreakDone() é sempre chamado, mesmo quando não há anúncio.
• Recomendamos que você use um anúncio precedente para posicionar anúncios antes do início do jogo.
  • Como alternativa, você pode usar 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 seus jogadores com itens no app se eles assistirem a um anúncio. Enquanto os intersticiais são desativados, o usuário vê o anúncio e pode dispensar o anúncio. Os anúncios premiados são ativados. Um jogador escolhe se quer assistir a um anúncio para receber um prêmio.

Ao contrário dos intersticiais, em que o jogador pode dispensar o anúncio a qualquer momento, ele precisa receber o prêmio por um período mínimo, que pode variar dependendo do criativo exibido.

Como os anúncios premiados são opcionais para o jogador, eles exigem integração mais profunda no fluxo do jogo. Você precisa fornecer funções para renderizar uma solicitação 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 (ou ser facilmente trocados) um valor monetário e não podem ser vendidos ou trocados por produtos e serviços. Você não deve incentivar os jogadores a clicar em anúncios. Para mais detalhes, consulte a política de rascunho sobre intersticiais e recompensas.

Como os prêmios são opcionais para o jogador, você pode adicioná-los em qualquer lugar que faça sentido no seu jogo e usá-los além dos intersticiais. Assim como os intersticiais, essas posições são oportunidades de exibir anúncios premiados. A API Ad Placement só vai chamar o código se um anúncio premiado for realmente oferecido em um ponto específico do jogo.

Mais uma vez, a meta é permitir que você integre seu jogo à API Ad Placement de vez em quando. Use controles na tag ou no Google AdSense para mudar a combinação exata de anúncios ativados, sem precisar recodificar e lançar o jogo novamente.

O tipo de uma posição premiada é sempre 'reward', e todos os campos na configuração da posição 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 novas funções são beforeReward(), que são o acionador que indica que você precisa renderizar a solicitação de recompensa, e adViewed(), que é chamado quando o jogador visualiza o anúncio para que você possa alocar o prêmio.

É possível definir uma posição premiada 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 uma solicitação no jogo, oferecendo ao jogador uma recompensa caso ele veja 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 armazenamento em cache de anúncios
Como executar o jogo
adBreak(type:'reward', ... ) →
	Há um anúncio disponível, então comece um posicionamento de 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 ganhar uma recompensa ao assistir a 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 nele para dispensar um aviso de recompensa ou simplesmente o ignorar. Ao clicar em uma solicitação, o jogo armazena o tipo de recompensa solicitado e chama showAdFn().... Caso contrário, se a solicitação de recompensa for dispensada ou ignorada, nada acontecerá até que você faça outra chamada para adBreak() com um tipo de canal de recompensa. A API Ad Placement será redefinida e limpará o estado dessa chamada. Se o app chamar showAdFn de um intervalo de anúncio anterior, ele não terá efeito.
showAdFn() →
	← beforeAd()
O jogo pausa, silencia o som e se prepara para mostrar o anúncio return à API →
	A API mostra o anúncio. Ele tem um botão "Dispensar" e uma contagem regressiva de quanto tempo resta no anúncio.
Se o jogador dispensa o anúncio...
	← adDismissed()
O jogador dispensou o anúncio, e o jogo não emite o prêmio.
SE o player assistir ao anúncio até o final...
	← adViewed()
O jogador assistiu ao anúncio até o fim e o jogo emite o prêmio. Normalmente, isso ocorre com a configuração de um estado de jogo que é selecionado quando o jogo é reiniciado com a chamada de afterAd() abaixo.
Depois que o anúncio foi assistido ou dispensado...
	← afterAd() vai ser chamado se um anúncio for exibido
O jogo pausa e ativa o som.
	← adBreakDone()adBreakDone() é sempre chamado (mesmo que um anúncio não tenha sido exibido)
O jogo registra as análises sobre esta posição.

Observações

• adBreak() é uma função assíncrona que retorna imediatamente.
• Se não houver anúncios para exibir para uma posição, nenhum dos callbacks será chamado, ou seja, nenhum de beforeAd(), beforeReward() será chamado.
• Para garantir que seu jogo não continue sendo executado enquanto o anúncio é exibido, use o callback beforeAd() para desativar o som e pausar o jogo.
• beforeAd() é síncrono, a API Ad Placement não mostrará um anúncio até que ele retorne.
• Reinicie o jogo e ative o som ao receber a chamada afterAd().
• Se fornecido, adBreakDone() sempre será chamado, mesmo que um anúncio não tenha sido exibido nesta posição.
• Chamar adBreak() enquanto outro anúncio está sendo exibido falhará e um aviso será exibido no Console JavaScript.