Cette page a été traduite par l'API Cloud Translation.

Exemple d'implémentation

L'API Ad Placement est conçue pour aider les développeurs AdSense et AdMob à utiliser des annonces interstitielles et avec récompense dans les jeux HTML5 sur le Web ou dans des applications. Cet exemple montre comment intégrer l'API Ad Placement dans un jeu et l'utiliser pour placer une annonce interstitielle.

Prérequis

Avant de commencer, vous avez besoin des éléments suivants:

Créez deux fichiers vides dans le même répertoire :
- index.html
- jeu.js
Installer Python localement ou utiliser un serveur Web pour tester votre implémentation

Exemple de code d'application

Les éditeurs AdMob peuvent télécharger des exemples de code d'application afin de mieux comprendre comment intégrer l'API à un jeu.

Télécharger un exemple de code d'application

1. Démarrer un serveur de développement

L'API Ads Placement charge les dépendances via le même protocole que la page sur laquelle elle est chargée. Par conséquent, vous devez utiliser un serveur Web pour tester votre application. Vous pouvez utiliser le serveur intégré de Python pour créer un environnement de développement local.

Ouvrez le terminal.
Accédez au répertoire qui contient votre fichier index.html, puis exécutez la commande suivante:
```
python -m http.server 8000
```
Remarque:http.server n'est disponible que dans Python 3.x.
Dans un navigateur Web, accédez à localhost:8000

Vous pouvez également utiliser n'importe quel autre serveur Web, tel que le serveur HTTP Apache.

2. Créer un jeu HTML5

Modifiez index.html pour créer un élément de canevas HTML5 et un bouton permettant de déclencher une partie. Ajoutez ensuite la balise de script nécessaire pour charger le fichier 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>

Modifiez game.js pour jouer à pile ou face lorsque l'utilisateur clique sur le bouton "Jouer".

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

Une fois cette étape terminée, lorsque vous ouvrez index.html dans votre navigateur (via votre serveur de développement), vous devriez pouvoir voir la toile du jeu et le bouton"Jouer". Si vous cliquez sur "Jouer", le jeu de pile ou face devrait commencer.

3. Importer l'API Ad Placement

Ajoutez ensuite l'API Ad Placement à votre jeu en insérant un tag de script dans index.html, avant le tag game.js.

La balise de script peut accepter un certain nombre de paramètres. Nous utiliserons les paramètres suivants pour spécifier le code de propriété AdSense et activer le mode de test:

data-ad-client=<AdSense property code> Votre code de propriété AdSense. Cela est toujours nécessaire, même pour les jeux qui s'exécutent au sein d'applications.
data-adbreak-test="on" Active le mode test. Supprimez cette information pour les jeux lorsqu'ils sont proposés aux joueurs.

Configurer le code AdSense et activer le mode test

La fonctionnalité de l'API Ad Placement est incluse dans le code AdSense. Pour l'activer, vous devez d'abord ajouter le code AdSense et inclure un petit extrait de script qui initialise ses deux fonctions clés: adBreak() et 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>

Intégrer votre jeu (facultatif)

Si vous souhaitez intégrer un jeu dans d'autres pages à l'intérieur d'un cadre iFrame et que la balise adsbygoogle figure sur la page HTML du jeu, assurez-vous d'ajouter allow='autoplay' à l'élément iFrame. Il s'agit d'une bonne pratique, qui est nécessaire pour que certaines annonces soient éligibles à votre jeu.

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

Applications mobiles compatibles

Un jeu H5 peut s'exécuter dans un navigateur Web standard, ou dans un onglet WebView ou Chrome personnalisé d'une application. L'API Ad Placement peut détecter l'environnement dans lequel votre jeu est exécuté et diriger les demandes d'annonces de manière appropriée. Si votre jeu est exécuté dans un navigateur Web standard, les demandes d'annonces sont traitées comme des demandes AdSense normales. Si l'API Ad Placement détecte un environnement intégré à l'application, elle communique avec le SDK GMA, s'il est présent, pour demander et diffuser des annonces AdMob.

Actuellement, cette fonctionnalité est compatible avec les applications Android associées au SDK AdMob GMA. Pour l'activer, vous devez enregistrer la WebView qui affiche votre jeu avec le SDK GMA, puis configurer les blocs d'annonces AdMob et les transmettre en tant que paramètres supplémentaires à la balise AdSense. Lorsque votre jeu est exécuté dans une application adaptée, l'API Ad Placement utilise ces blocs d'annonces pour diffuser des annonces.

Pour activer la compatibilité avec les mobiles, vous devez spécifier les paramètres de tag supplémentaires suivants:

data-admob-interstitial-slot=<AdMob slot ID> ID de bloc d'annonces interstitielles AdMob que vous avez configuré précédemment
data-admob-rewarded-slot=<AdMob slot ID> ID de bloc d'annonces avec récompense AdMob.

Votre code de propriété AdSense doit toujours être transmis avec le paramètre data-ad-client, et vous devez spécifier au moins l'une des valeurs suivantes : data-admob-interstitial-slot ou data-admob-rewarded-slot. Les deux paramètres doivent être spécifiés si votre jeu utilise les deux formats.

Vous pouvez également spécifier le paramètre de balise data-admob-ads-only=on pour indiquer que votre jeu ne doit diffuser des annonces qu'à partir d'AdMob et qu'il ne doit pas revenir à AdSense dans les cas où le jeu se déroule dans un environnement non compatible avec les demandes AdMob (par exemple, dans des environnements autres que des applications ou des applications sans SDK GMA pour AdMob).

Important: Si vous concevez votre jeu pour l'intégrer à une application et que vous êtes propriétaire de l'application, ou si vous passez un accord de partage des revenus avec le propriétaire de l'application, la seule façon d'effectuer cette opération de manière performante et conforme au règlement consiste à utiliser cette compatibilité AdMob.

Tout d'abord, enregistrez la WebView qui montre votre jeu avec le SDK GMA:

MainActivity.java (application)

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

Ensuite, transmettez les blocs d'annonces AdMob (un pour les interstitiels et un pour les annonces avec récompense) comme suit:

index.html (application)

 [...]
    <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. Appeler adConfig()

L'appel adConfig() communique la configuration actuelle du jeu à l'API Ad Placement. L'API peut ensuite utiliser ces informations pour filtrer les types d'annonces qu'elle demande afin de les adapter au jeu (par exemple, les annonces vidéo qui nécessitent un son, si le son est activé).

Un appel doit être envoyé à adConfig() chaque fois que cette configuration change, par exemple lorsqu'un utilisateur coupe ou réactive le son du jeu. Appelez adConfig() dans le constructeur du jeu, puis ajoutez un bouton pour couper le son et réactiver le son du jeu qui appelle adConfig().

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

À présent, ajoutez le bouton du micro à votre fichier 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. Appelez `adBreak()` à la fin du jeu

L'appel adBreak() définit un emplacement d'annonce et utilise l'objet appelé "config config" qui spécifie tout ce qui est nécessaire pour diffuser une annonce à ce stade de votre jeu. La prise en charge de différents types d'annonces nécessite l'initialisation de différents sous-ensembles de la configuration d'emplacement.

L'appel adBreak() définit un emplacement où une annonce peut être diffusée. En d'autres termes, il s'agit d'une opportunité de diffuser une annonce. La diffusion effective d'une annonce dépend de plusieurs facteurs:

Type d'emplacement d'annonce que vous avez déclaré.
si des interactions utilisateur appropriées ont eu lieu avant cet emplacement d'annonce ;
Indique s'il existe une annonce adaptée au lecteur actuel qui :
- est pertinent pour eux ;
- est conforme à ses paramètres de confidentialité des données et de consentement ;
Nombre d'annonces que l'utilisateur a vues récemment.
Voici les paramètres de contrôle que vous avez configurés pour ce jeu :
- Indices dans le tag.
- Sur AdSense (remarque: les commandes disponibles dans AdSense évolueront au fil du temps)

Ajoutez le code permettant d'afficher une annonce interstitielle au redémarrage du jeu: appelez adBreak() dans la fonction play(), qui ne s'exécute qu'une seule fois.

adBreak() doit être appelé dans le cadre d'une action de l'utilisateur, telle qu'un clic sur le bouton"Lire". Sinon, l'API ne pourra pas demander ni afficher d'annonces.

Créez des fonctions à appeler avant et après la coupure publicitaire. Vous les utiliserez ensuite dans la configuration de l'emplacement adBreak(). Notez que les fonctions beforeAd et afterAd ne sont appelées que si une annonce appropriée est trouvée.

jeu.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'application à pile ou face crée désormais des emplacements pour les annonces à diffuser.

Votre propre application peut disposer d'emplacements supplémentaires appropriés pour les annonces, en dehors de la fin du jeu. L'appel de adBreak() dans ces lieux doit être semblable à cet exemple.

Désactiver les tests pour les applications de production

Avant de publier votre application, il est important de supprimer ou de commenter la ligne data-adbreak-test="on" dans index.html, car ce code active les paramètres de test en production.

Exemple d'implémentation

Prérequis

Exemple de code d'application

1. Démarrer un serveur de développement

2. Créer un jeu HTML5

index.html

jeu.js

3. Importer l'API Ad Placement

Configurer le code AdSense et activer le mode test

index.html (Web)

Intégrer votre jeu (facultatif)

Applications mobiles compatibles

MainActivity.java (application)

index.html (application)

4. Appeler adConfig()

jeu.js

index.html

5. Appelez adBreak() à la fin du jeu

jeu.js

Désactiver les tests pour les applications de production

5. Appelez `adBreak()` à la fin du jeu