Questa pagina è stata tradotta dall'API Cloud Translation.

Esempio di implementazione

L'API Ad Placement è progettata per supportare gli sviluppatori AdSense e AdMob che utilizzano annunci interstitial e con premio nei giochi HTML5 sul Web o all'interno delle app. Questo esempio mostra come integrare l'API Ad Placement in un gioco e utilizzarla per posizionare un annuncio interstitial.

Prerequisiti

Prima di iniziare, assicurati di avere quanto segue:

Crea due file vuoti nella stessa directory:
- index.html
- gioco.js
Installa Python localmente o utilizza un server web per testare la tua implementazione

Codice campione dell'app

I publisher AdMob possono scaricare un codice dell'app di esempio per comprendere meglio come l'API può essere integrata in un gioco di app.

Scarica codice di esempio dell'app

1. Avvia un server di sviluppo

Poiché l'API Ads Placement carica le dipendenze tramite lo stesso protocollo della pagina su cui viene caricato, devi utilizzare un server web per testare la tua app. Puoi utilizzare il server integrato di Python per creare un ambiente di sviluppo locale.

Apri il terminale.
Vai alla directory che contiene il file index.html, quindi esegui:
```
python -m http.server 8000
```
Nota: http://server è disponibile solo in Python 3.x.
Da un browser web, vai alla pagina localhost:8000

Puoi anche utilizzare qualsiasi altro server web, ad esempio il server HTTP Apache.

2. Creare un gioco HTML5

Modifica index.html per creare un elemento canvas HTML5 e un pulsante per attivare il gameplay. Aggiungi quindi il tag script necessario per caricare il file 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>

Modifica il file game.js per poter usare una modalità di selezione delle monete quando si fa clic sul pulsante "Gioca".

gioco.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();

Dopo aver completato questo passaggio, quando apri index.html nel browser (tramite il tuo server di sviluppo) dovresti essere in grado di vedere la tela di gioco e il pulsante "Gioca". Se fai clic su Gioca, il gioco di lancio delle monete dovrebbe iniziare.

3. Importa l'API Ad Placement

Poi aggiungi l'API Ad Placement al tuo gioco inserendo un tag script in index.html, prima del tag per game.js.

Il tag script può utilizzare diversi parametri. Utilizzeremo i seguenti parametri per specificare il codice proprietà AdSense e per attivare la modalità di prova:

data-ad-client=<AdSense property code> Il codice proprietà AdSense. Questa proprietà è sempre obbligatoria anche per i giochi che vengono eseguiti all'interno delle app.
data-adbreak-test="on" Abilita la modalità di test. Rimuovi questa opzione per i giochi quando vengono pubblicati per i giocatori.

Imposta il codice AdSense e attiva la modalità di prova

La funzionalità API Ad Placement è inclusa nel codice AdSense. Per attivarlo, devi prima aggiungere il codice AdSense e includere un piccolo snippet script che inizializza le sue due funzioni chiave: 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>

Incorporamento del gioco (facoltativo)

Se vuoi incorporare un gioco in altre pagine all'interno di un iframe e il tag adsbygoogle si trova nella pagina HTML del gioco, assicurati di aggiungere allow='autoplay' all'elemento iframe. Si tratta di una best practice ed è necessario che determinati annunci siano idonei per il tuo gioco.

<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>

Supporta le app per dispositivi mobili

Un gioco H5 può essere eseguito in un normale browser web, in una WebView o scheda personalizzata di Chrome all'interno di un'app. L'API Ad Placement può rilevare l'ambiente in cui è in corso il tuo gioco e indirizzare le richieste di annunci in modo appropriato. Se il tuo gioco è in esecuzione su un normale browser web, le richieste di annunci vengono trattate come normali richieste di AdSense. Se l'API Ad Placement rileva un ambiente in-app, comunica con l'SDK GMA, se presente, di richiedere e mostrare gli annunci AdMob.

Attualmente questa funzionalità è supportata nelle app per Android collegate all'SDK GMA di AdMob. Per attivarlo, devi registrare il componente WebView che mostrerà il tuo gioco con l'SDK GMA, quindi configurare le unità pubblicitarie AdMob e trasmetterle come parametri aggiuntivi al tag AdSense. Se il tuo gioco viene eseguito all'interno di un'app adatta, l'API Ad Placement utilizzerà queste unità pubblicitarie per mostrare gli annunci.

Per abilitare il supporto per dispositivi mobili, devi specificare i seguenti parametri tag aggiuntivi:

data-admob-interstitial-slot=<AdMob slot ID> Un ID unità pubblicitaria interstitial di AdMob configurato in precedenza.
data-admob-rewarded-slot=<AdMob slot ID> Un ID unità pubblicitaria con premio di AdMob.

Il codice proprietà AdSense deve sempre essere trasmesso con il parametro data-ad-client e deve essere specificato almeno un elemento data-admob-interstitial-slot o data-admob-rewarded-slot. Entrambi i parametri devono essere specificati se il gioco utilizza entrambi i formati.

Facoltativamente, puoi anche specificare il parametro del tag data-admob-ads-only=on per indicare che il tuo gioco deve mostrare annunci solo da AdMob e non di riserva ad AdSense nei casi in cui il gioco viene eseguito in un ambiente che non supporta le richieste AdMob (ad es. ambienti o app non configurati per l'SDK GMA di AdMob).

Importante: se progetti il gioco per essere incorporato in un'app e sei il proprietario dell'app oppure stai stipulando un contratto relativo alla quota di condivisione delle entrate con il proprietario dell'app, l'unico modo per farlo in modo alto e conforme alle norme è utilizzare questo supporto AdMob.

Innanzitutto, registra la WebView che mostrerà il tuo gioco con l'SDK 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);

Successivamente, trasmetti le unità pubblicitarie AdMob (una per gli annunci interstitial e una per gli annunci con premio) come segue:

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. Chiamata adConfigConfig()

La chiamata adConfig() comunica la configurazione attuale del gioco all'API Ad Placement. L'API può quindi utilizzare queste informazioni per filtrare i tipi di annunci richiesti in modo che siano adatti al gioco (come gli annunci video che richiedono l'audio, se l'audio è attivato).

È necessario effettuare una chiamata a adConfig() ogni volta che questa configurazione cambia, ad esempio quando un utente disattiva o riattiva l'audio del gioco. Chiama il numero adConfig() nel costruttore del gioco, quindi aggiungi un pulsante per disattivare e riattivare il gioco che effettua un'altra chiamata adConfig().

gioco.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();
  [...]

A questo punto, aggiungi il pulsante di disattivazione dell'audio al file 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. Chiama il numero `adBreak()` al termine della partita

La chiamata adBreak() definisce un posizionamento dell'annuncio e utilizza l'oggetto denominato config posizionamento che specifica tutto il necessario per mostrare un annuncio in questo punto del tuo gioco. Il supporto di tipi di annunci diversi richiede l'inizializzazione di sottoinsiemi diversi della configurazione del posizionamento.

La chiamata adBreak() definisce un posizionamento in cui un annuncio potrebbe essere pubblicato o, in altre parole, un'opportunità per mostrare un annuncio. La pubblicazione effettiva di un annuncio dipende da diversi fattori:

Il tipo di posizionamento dell'annuncio che hai dichiarato.
Se ci sono state interazioni appropriate dell'utente prima di questo posizionamento dell'annuncio.
Se esiste un annuncio adatto per il player corrente:
- È pertinente per loro.
- È coerente con le impostazioni sulla privacy e sul consenso dei dati.
Il numero di annunci visualizzati di recente dall'utente.
Le impostazioni di controllo di questo gioco che hai configurato come:
- Suggerimenti nel tag.
- In AdSense (nota: i controlli disponibili in AdSense si evolveranno nel tempo)

Aggiungi il codice per un annuncio interstitial da mostrare al riavvio del gioco: effettua una chiamata a adBreak() all'interno della funzione play(), che viene eseguita solo dopo che il gioco è stato giocato una volta.

L'elemento adBreak() deve essere chiamato come parte di un'azione utente, ad esempio il clic sul pulsante"Riproduci"; in caso contrario l'API non potrà richiedere e visualizzare gli annunci.

Crea funzioni da richiamare prima e dopo l'interruzione pubblicitaria e che utilizzerai poi nella configurazione del posizionamento adBreak(). È importante notare che le funzioni beforeAd e afterAd vengono richiamate solo se viene trovato un annuncio adatto.

gioco.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();

L'app di attivazione e disattivazione delle monete ora sta creando posizionamenti per la visualizzazione degli annunci.

La tua app potrebbe avere ulteriori spazi appropriati per gli annunci, tranne quando termina il gioco. Le chiamate adBreak() in queste località devono essere simili a questo esempio.

Disattiva test per app di produzione

Prima di rilasciare l'app, è importante rimuovere o commentare la riga data-adbreak-test="on" in index.html, poiché questo codice attiva le impostazioni di test in produzione.

Esempio di implementazione

Prerequisiti

Codice campione dell'app

1. Avvia un server di sviluppo

2. Creare un gioco HTML5

index.html

gioco.js

3. Importa l'API Ad Placement

Imposta il codice AdSense e attiva la modalità di prova

index.html (web)

Incorporamento del gioco (facoltativo)

Supporta le app per dispositivi mobili

MainActivity.java (app)

index.html (app)

4. Chiamata adConfigConfig()

gioco.js

index.html

5. Chiama il numero adBreak() al termine della partita

gioco.js

Disattiva test per app di produzione

5. Chiama il numero `adBreak()` al termine della partita