Esta página foi traduzida pela API Cloud Translation.

Implementação de exemplo

A API Ad Placement foi criada para ser compatível com os desenvolvedores do Google AdSense e da AdMob que usam anúncios intersticiais e premiados em jogos HTML5 na Web ou em apps. Este exemplo demonstra como integrar a API Ad Placement a um jogo e usá-la para posicionar um anúncio intersticial.

Pré-requisitos

Antes de começar, você precisará de:

Crie dois arquivos vazios no mesmo diretório:
- index.html
- game.js
Instale o Python localmente ou use um servidor da Web para testar sua implementação

Amostra de código de aplicativo

Os editores da AdMob podem fazer o download de uma amostra de código do app para entender melhor como a API pode ser integrada a um jogo.

Fazer o download do exemplo de código do app

1. Iniciar um servidor de desenvolvimento

Como a API Ads Placement carrega dependências pelo mesmo protocolo da página em que é carregada, você precisa usar um servidor da Web para testar seu app. É possível usar o servidor integrado do Python para criar um ambiente de desenvolvimento local.

Abra o terminal.
Acesse o diretório que contém o arquivo index.html e execute:
```
python -m http.server 8000
```
Observação: http.server só está disponível em Python 3.x.
Em um navegador da Web, acesse localhost:8000

Também é possível usar qualquer outro servidor da Web, como o Apache HTTP Server.

2. Criar um jogo HTML5

Modifique index.html para criar um elemento da tela HTML5 e um botão para acionar a jogabilidade. Em seguida, adicione a tag de script necessária para carregar o arquivo game.js.

index.html

<!doctype html>
<html lang="en">
  <head>
    <title>Ad Placement API HTML5 demo</title>
    <meta name="viewport" content="width=device-width, initial-scale=1">
  </head>
  <body>
    <canvas id="gameContainer" height="300px" width="300px"></canvas>
    <button id="playButton">Play</button>
    <button style="display:none" id="headsButton">Heads</button>
    <button style="display:none" id="tailsButton">Tails</button>

    <script src="game.js"></script>
  </body>
</html>

Modifique game.js para jogar um jogo de cara ou coroa quando o botão "Jogar" for clicado.

game.js

// Create a coin flip game
class Game {
  constructor() {
    // Define variables
    this.score = 0;
    this.choice = '';

    this.canvas = document.getElementById('gameContainer').getContext('2d');
    this.canvas.font = '24px Arial';

    this.playButton = document.getElementById('playButton');
    this.headsButton = document.getElementById('headsButton');
    this.tailsButton = document.getElementById('tailsButton');

    // On click listeners for the game's buttons.
    this.playButton.addEventListener('click', () => {
      this.erase();
      this.play();
    });

    this.headsButton.addEventListener('click', () => {
      this.choice = 'Heads';
      this.flipCoin();
    });

    this.tailsButton.addEventListener('click', () => {
      this.choice = 'Tails';
      this.flipCoin();
    });

    this.erase();
  }

  // Start the game
  play() {
    this.score = 0;
    this.canvas.fillText('Score: ' + this.score, 8, 26);
    this.canvas.fillText('Heads or Tails?', 66, 150);
    this.playButton.style.display = 'none';
    this.headsButton.style.display = 'inline-block';
    this.tailsButton.style.display = 'inline-block';
  }

  // Flip the coin
  flipCoin() {
    this.headsButton.disabled = true;
    this.tailsButton.disabled = true;
    this.erase();
    this.canvas.fillText('Score: ' + this.score, 8, 26);
    this.canvas.fillText('Flipping coin . . .', 60, 150);

    setTimeout(() => { this.coinLanded() }, 2000);
  }

  // Logic for when the coin lands
  coinLanded() {
    this.headsButton.disabled = false;
    this.tailsButton.disabled = false;
    let sideUp;
    if(Math.random() < 0.5) {
      sideUp = 'Heads';
    } else {
      sideUp = 'Tails';
    }

    if (sideUp === this.choice ) {
      this.win(sideUp);
    } else {
      this.lose(sideUp);
    }
  }

  // Guess the flip correctly
  win(sideUp) {
    this.erase();
    this.score += 1;
    this.canvas.fillText('Score: ' + this.score, 8, 26);
    this.canvas.fillText('It was ' + sideUp + '!', 66, 150);
    this.canvas.fillText('Guess again', 70, 200);
  }

  // Guess the flip incorrectly
  lose(sideUp) {
    this.erase();
    this.canvas.fillText('Sorry, it was ' + sideUp, 50, 100);
    this.canvas.fillText('Your score was ' + this.score, 50, 150);
    this.canvas.fillText('Want to play again?', 45, 200);

    this.playButton.style.display = 'inline-block';
    this.headsButton.style.display = 'none';
    this.tailsButton.style.display = 'none';
  }

  // Erase the canvas
  erase() {
    this.canvas.fillStyle = '#ADD8E6';
    this.canvas.fillRect(0, 0, 300, 300);
    this.canvas.fillStyle = '#000000';
  }
}

const game = new Game();

Depois de concluir essa etapa, ao abrir index.html no navegador (pelo servidor de desenvolvimento), você verá a tela do jogo e o botão ""Jogar" Se você clicar em "Jogar", o jogo de cara ou coroa será iniciado.

3. Importar a API Ad Placement

Em seguida, adicione a API Ad Placement ao seu jogo inserindo uma tag de script em index.html, antes da tag de game.js.

A tag de script pode usar vários parâmetros. Os seguintes parâmetros serão usados para especificar o código da propriedade do Google AdSense e ativar o modo de teste:

data-ad-client=<AdSense property code> Seu código de propriedade do Google AdSense. Isso é sempre necessário até para jogos executados em apps.
data-adbreak-test="on" Ativa o modo de teste. Remova essa opção para jogos quando eles forem veiculados aos jogadores.

Configurar o código do AdSense e ativar o modo de teste

A funcionalidade da API Ad Placement está incluída no código do AdSense. Para ativá-la, primeiro adicione o código do AdSense e inclua um pequeno snippet de script que inicialize as duas funções principais: adBreak() e adConfig().

index.html (Web)

 [...]
    <canvas id="gameContainer" height="300px" width="300px"></canvas>
    <button id="playButton">Play</button>
    <button style="display:none" id="headsButton">Heads</button>
    <button style="display:none" id="tailsButton">Tails</button>

    <script async
      data-adbreak-test="on"
      src="https://pagead2.googlesyndication.com/pagead/js/adsbygoogle.js?client=ca-pub-123456789"
      crossorigin="anonymous">
    </script>
    <script>
      window.adsbygoogle = window.adsbygoogle || [];
      const adBreak = adConfig = function(o) {adsbygoogle.push(o);}
    </script>
    <script src="game.js"></script>
  </body>
</html>

Incorporação do jogo (opcional)

Para incorporar um jogo a outras páginas em um iframe, e a tag adsbygoogle estiver na página HTML do jogo, adicione allow='autoplay' ao elemento iframe. Essa é uma prática recomendada e é necessária para que determinados anúncios sejam qualificados para seu jogo.

<head>
  <!-- The adsbygoogle tag is not here -->
</head>
<body>
  <iframe src="https://www.my-game.com" title="My game" allow="autoplay">
    <!-- The game is loaded here and contains the adsbygoogle tag -->
  </iframe>
</body>

Suporte para apps

Um jogo H5 pode ser executado em um navegador da Web normal ou em uma guia personalizada do Chrome ou WebView em um app. A API Ad Placement pode detectar em qual ambiente seu jogo está sendo executado e direcionar as solicitações de anúncio adequadamente. Se seu jogo estiver em execução em um navegador da Web normal, as solicitações de anúncios serão tratadas como solicitações normais do Google AdSense. Se a API Ad Placement detecta um ambiente no app, ela se comunica com o SDK do GMA, se houver, para solicitar e exibir anúncios da AdMob.

No momento, esse recurso é compatível com apps Android vinculados ao SDK dos GMAs da AdMob. Para habilitá-lo, registre o WebView que mostrará seu jogo com o SDK do GMA, configure os blocos de anúncios da AdMob e os transmita como parâmetros adicionais à tag do Google AdSense. Quando seu jogo for executado em um app adequado, a API Ad Placement usará esses blocos de anúncios para exibir anúncios.

Para ativar o suporte para dispositivos móveis, é preciso especificar os seguintes parâmetros de tag adicionais:

data-admob-interstitial-slot=<AdMob slot ID> Um ID do bloco de anúncios intersticiais da AdMob que você configurou anteriormente.
data-admob-rewarded-slot=<AdMob slot ID> É um ID de bloco de anúncios premiado da AdMob.

Seu código de propriedade do Google AdSense precisa ser sempre transmitido com o parâmetro data-ad-client e, pelo menos, um data-admob-interstitial-slot ou data-admob-rewarded-slot precisa ser especificado. Os dois parâmetros precisam ser especificados se o jogo usar os dois formatos.

Você também pode especificar o parâmetro de tag data-admob-ads-only=on para indicar que seu jogo precisa exibir anúncios somente da AdMob, e não substitutos para o Google AdSense quando o jogo estiver sendo jogado em um ambiente que não oferece suporte a solicitações da AdMob (por exemplo, ambientes que não são de apps ou aplicativos sem o SDK dos GMAs da AdMob configurado).

Importante: quando você projeta o jogo para ser incorporado a um app e é proprietário dele ou está firmando um contrato de participação na receita com o proprietário do app, a única maneira de fazer isso de acordo com a política e com alto desempenho é usar esse suporte da AdMob.

Primeiro, registre o WebView que mostrará seu jogo com o SDK do GMA:

MainActivity.java (app)

...
public void onCreate(@Nullable Bundle savedInstanceState) {
    super.onCreate(savedInstanceState);
    setContentView(R.layout.activity_main);

    webView = findViewById(R.id.webview_minigame);

    WebSettings settings = webView.getSettings();
    settings.setJavaScriptEnabled(true);

    h5AdsWebViewClient = new H5AdsWebViewClient(this, webView);
    webView.setWebViewClient(h5AdsWebViewClient);

    h5AdsWebViewClient.setDelegateWebViewClient(pubWebViewClient);

Depois, transmita os blocos de anúncios da AdMob (um para intersticiais e outro para anúncios premiados) da seguinte maneira:

index.html (app)

 [...]
    <canvas id="gameContainer" height="300px" width="300px"></canvas>
    <button id="playButton">Play</button>
    <button style="display:none" id="headsButton">Heads</button>
    <button style="display:none" id="tailsButton">Tails</button>
    <script async
      data-admob-interstitial-slot="ca-app-pub-0987654321/1234567890"
      data-admob-rewarded-slot="ca-app-pub-0987654321/0987654321"
      src="https://pagead2.googlesyndication.com/pagead/js/adsbygoogle.js?client=ca-pub-123456789"
      crossorigin="anonymous">
    </script>
    <script>
      window.adsbygoogle = window.adsbygoogle || [];
      const adBreak = adConfig = function(o) {adsbygoogle.push(o);}
    </script>
    <script src="game.js"></script>
  </body>
</html>

4. Fazer uma chamada para adConfig()

A chamada adConfig() comunica a configuração atual do jogo à API Ad Placement. A API pode usar essas informações para filtrar os tipos de anúncios solicitados para que sejam adequados ao jogo (como anúncios em vídeo que precisam de som, se o som estiver ativado).

Uma chamada precisa ser feita para adConfig() sempre que essa configuração for alterada, como quando um usuário desativa ou ativa o som do jogo. Faça uma chamada para adConfig() no construtor do jogo e adicione um botão para desativar e ativar o som do jogo que faz uma chamada adConfig() adicional.

game.js

class Game {
  constructor() {
    // Define variables
    this.score = 0;
    this.choice = '';
    this.muted = false;

    this.canvas = document.getElementById('gameContainer').getContext('2d');
    this.canvas.font = '24px Arial';

    this.playButton = document.getElementById('playButton');
    this.headsButton = document.getElementById('headsButton');
    this.tailsButton = document.getElementById('tailsButton');
    this.muteButton = document.getElementById('muteButton');

    adConfig({
      sound: 'on',
    });

    // On click listeners for the game's buttons.
    this.playButton.addEventListener('click', () => {
      this.erase();
      this.play();
    });

    this.headsButton.addEventListener('click', () => {
      this.choice = 'Heads';
      this.flipCoin();
    });

    this.tailsButton.addEventListener('click', () => {
      this.choice = 'Tails';
      this.flipCoin();
    });

    this.muteButton.addEventListener('click', () => {
      var soundString = this.muted ? 'on' : 'off';
      this.muteButton.innerHTML = this.muted ? 'Mute sound' : 'Un-mute sound';
      this.muted = !this.muted;
      adConfig({
        sound: soundString,
      });
    });

    this.erase();
  [...]

Agora, adicione o botão de desativar microfone ao seu arquivo HTML.

index.html

[...]
    <canvas id="gameContainer" height="300px" width="300px"></canvas>
    <button id="playButton">Play</button>
    <button style="display:none" id="headsButton">Heads</button>
    <button style="display:none" id="tailsButton">Tails</button>
    <button id="muteButton">Mute sound</button>

    <script async
      data-adbreak-test="on"
      src="https://pagead2.googlesyndication.com/pagead/js/adsbygoogle.js?client=ca-pub-123456789"
      crossorigin="anonymous">
    </script>
[...]

5. Faça uma chamada para `adBreak()` quando o jogo terminar

A chamada adBreak() define uma posição do anúncio e usa o objeto chamado configuração de posição que especifica tudo o que é necessário para exibir um anúncio neste ponto do seu jogo. Para oferecer suporte a diferentes tipos de anúncio, será necessário inicializar subconjuntos diferentes da configuração de posicionamento.

A chamada adBreak() define uma posição em que um anúncio pode exibir ou, em outras palavras, uma oportunidade de exibir um anúncio. A exibição real de um anúncio depende de diversos fatores:

É o tipo de posição do anúncio que você declarou.
se houve interações do usuário adequadas antes da posição do anúncio;
Se um anúncio adequado existe para o player atual, isso:
- É relevante para eles.
- é consistente com as configurações de privacidade e consentimento de dados;
O número de anúncios que o usuário viu recentemente.
São as configurações de controle definidas para este jogo como:
- Dicas na tag.
- No Google AdSense (observação: os controles disponíveis no Google AdSense evoluirão com o tempo)

Adicione o código de um anúncio intersticial para ser exibido quando o jogo for reiniciado: faça uma chamada para adBreak() dentro da função play(), que é executada somente após o jogo ser jogado uma vez.

adBreak() precisa ser chamado como parte de uma ação do usuário, como clicar no botão "Play" caso contrário, a API não poderá solicitar e exibir anúncios.

Crie funções para serem chamadas antes e depois do intervalo de anúncio, que serão usadas na configuração de posicionamento adBreak(). É importante saber que as funções beforeAd e afterAd só serão chamadas se um anúncio adequado for encontrado.

game.js

class Game {
  constructor() {
    // Define variables
    this.score = 0;
    this.choice = '';
    this.muted = false;
    this.shouldShowAdOnPlay = false;

  [...]

  // Start the game
  play() {
    if (this.shouldShowAdOnPlay) {
      this.shouldShowAdOnPlay = false;

      adBreak({
        type: 'next',  // ad shows at start of next level
        name: 'restart-game',
        beforeAd: () => { this.disableButtons(); },  // You may also want to mute the game's sound.
        afterAd: () => { this.enableButtons(); },    // resume the game flow.
      });
    }

    this.score = 0;
    this.canvas.fillText('Score: ' + this.score, 8, 26);
    this.canvas.fillText('Heads or Tails?', 66, 150);
    this.playButton.style.display = 'none'
    this.headsButton.style.display = 'inline-block'
    this.tailsButton.style.display = 'inline-block'
  }

  [...]

  // Guess the flip incorrectly
  lose(sideUp) {
    this.erase()
    this.canvas.fillText('Sorry, it was ' + sideUp, 50, 100);
    this.canvas.fillText('Your score was ' + this.score, 50, 150);
    this.canvas.fillText('Want to play again?', 45, 200);

    this.playButton.style.display = 'inline-block'
    this.headsButton.style.display = 'none'
    this.tailsButton.style.display = 'none'
    this.shouldShowAdOnPlay = true;
  }

  [...]

  // Erase the canvas
  erase() {
    this.canvas.fillStyle = '#ADD8E6';
    this.canvas.fillRect(0, 0, 300, 300);
    this.canvas.fillStyle = '#000000';
  }

  enableButtons() {
    this.playButton.disabled = false;
    this.headsButton.disabled = false;
    this.tailsButton.disabled = false;
  }

  disableButtons() {
    this.playButton.disabled = true;
    this.headsButton.disabled = true;
    this.tailsButton.disabled = true;
  }
}

const game = new Game();

O app de cara ou coroa agora cria posições de anúncios para exibir.

O app pode ter outros lugares adequados para anúncios que não sejam quando o jogo termina. Chamar adBreak() nesses locais será semelhante a este exemplo.

Desativar testes de apps de produção

Antes de lançar o app, é importante remover ou comentar a linha data-adbreak-test="on" em index.html, já que esse código ativa as configurações de teste na produção.

Implementação de exemplo

Pré-requisitos

Amostra de código de aplicativo

1. Iniciar um servidor de desenvolvimento

2. Criar um jogo HTML5

index.html

game.js

3. Importar a API Ad Placement

Configurar o código do AdSense e ativar o modo de teste

index.html (Web)

Incorporação do jogo (opcional)

Suporte para apps

MainActivity.java (app)

index.html (app)

4. Fazer uma chamada para adConfig()

game.js

index.html

5. Faça uma chamada para adBreak() quando o jogo terminar

game.js

Desativar testes de apps de produção

5. Faça uma chamada para `adBreak()` quando o jogo terminar