Diese Seite wurde von der Cloud Translation API übersetzt.

Beispielimplementierung

Die Ad Placement API unterstützt AdSense- und AdMob-Entwickler bei der Verwendung von Interstitial-Anzeigen und Anzeigen mit Prämie in HTML5-Spielen im Web oder in Apps. In diesem Beispiel wird gezeigt, wie Sie die Ad Placement API in ein Spiel einbinden und damit eine Interstitial-Anzeige platzieren.

Voraussetzungen

Zuerst benötigen Sie Folgendes:

Erstellen Sie zwei leere Dateien im selben Verzeichnis:
- index.html
- game.js
Installieren Sie Python lokal oder testen Sie Ihre Implementierung mit einem Webserver

Beispielcode der App

AdMob-Publisher können Beispielcode für Apps herunterladen, um besser zu verstehen, wie die API in ein App-Spiel integriert werden kann.

App-Beispielcode herunterladen

1. Entwicklungsserver starten

Da die Ads Placement API Abhängigkeiten über dasselbe Protokoll wie die Seite lädt, auf der sie geladen wird, müssen Sie Ihre Anwendung mit einem Webserver testen. Sie können auch mit dem integrierten Python-Server eine lokale Entwicklungsumgebung erstellen.

Öffnen Sie das Terminal.
Wechseln Sie in das Verzeichnis, das die Datei „index.html“ enthält, und führen Sie den folgenden Befehl aus:
```
python -m http.server 8000
```
Hinweis: http.server ist nur in Python 3.x verfügbar.
Rufen Sie in einem Webbrowser localhost:8000 auf.

Sie können auch einen anderen Webserver wie den Apache HTTP Server verwenden.

2. HTML5-Spiel erstellen

Ändern Sie index.html, um ein HTML5-Canvas-Element und eine Schaltfläche zum Auslösen des Spiels zu erstellen. Fügen Sie dann das erforderliche Skript-Tag hinzu, um die Datei game.js zu laden.

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>

Ändern Sie die Datei „game.js“, um ein Münzwurfspiel zu spielen, wenn auf die Schaltfläche „Wiedergabe“ geklickt wird.

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

Wenn Sie nach Abschluss dieses Schritts index.html in Ihrem Browser (über Ihren Entwicklungsserver) öffnen, sollten Sie den Spiel-Canvas und die Schaltfläche „Wiedergabe“ sehen. Wenn Sie auf „Spielen“ klicken, sollte das Münzwurfspiel starten.

3. Ad Placement API importieren

Fügen Sie als Nächstes Ihrem Spiel die Ad Placement API hinzu, indem Sie in index.html vor dem Tag ein Skript-Tag für game.js einfügen.

Das Skript-Tag kann eine Reihe von Parametern annehmen. Wir verwenden die folgenden Parameter, um den AdSense-Property-Code anzugeben und den Testmodus zu aktivieren:

data-ad-client=<AdSense property code> Ihr AdSense-Property-Code Dies ist immer erforderlich, auch wenn Spiele in Apps ausgeführt werden.
data-adbreak-test="on" Aktiviert den Testmodus. Entferne es für Spiele, sobald diese für Spieler verfügbar sind.

AdSense-Code einrichten und Testmodus aktivieren

Die AdSense API-Funktionen sind im AdSense-Code enthalten. Dazu muss der AdSense-Code zuerst hinzugefügt und ein kleines Skript-Snippet eingefügt werden, mit dem die beiden Hauptfunktionen „adBreak()“ und „adConfig()“ initialisiert werden.

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>

Spiel einbetten (optional)

Wenn du ein Spiel auf anderen Seiten in einem iFrame einbetten möchtest und sich das adsbygoogle-Tag auf der HTML-Seite des Spiels befindet, muss allow='autoplay' zum iFrame-Element hinzugefügt werden. Diese Best Practice ist erforderlich, damit bestimmte Anzeigen in Ihrem Spiel präsentiert werden können.

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

Unterstützung für mobile Apps

Ein H5-Spiel kann in einem regulären Webbrowser oder in einem WebView- oder Chrome-Tab in einer App ausgeführt werden. Die Ad Placement API kann erkennen, in welcher Umgebung dein Spiel ausgeführt wird, und die Anzeigenanfragen entsprechend steuern. Wenn Ihr Spiel in einem regulären Webbrowser ausgeführt wird, werden die Anzeigenanfragen wie normale AdSense-Anfragen behandelt. Wenn die Ad Placement API eine In-App-Umgebung erkennt, kommuniziert sie mit dem GMA SDK, falls AdMob vorhanden ist, um AdMob-Anzeigen anzufordern und auszuliefern.

Derzeit wird diese Funktion in Android-Apps unterstützt, die mit dem AdMob GMA SDK verknüpft sind. Um die Funktion zu aktivieren, müssen Sie das WebView registrieren, das Ihr Spiel mit dem GMA SDK anzeigt. Anschließend konfigurieren Sie AdMob-Anzeigenblöcke und übergeben sie als zusätzliche Parameter an das AdSense-Tag. Wenn Ihr Spiel in einer geeigneten App ausgeführt wird, verwendet die Ad Placement API diese Anzeigenblöcke zum Ausliefern von Anzeigen.

Zum Aktivieren der Unterstützung für Mobilgeräte müssen Sie die folgenden zusätzlichen Tag-Parameter angeben:

data-admob-interstitial-slot=<AdMob slot ID> Die ID eines zuvor konfigurierten Interstitial-Anzeigenblocks in AdMob.
data-admob-rewarded-slot=<AdMob slot ID> Die Anzeigenblock-ID in AdMob mit Prämie.

Dein AdSense-Property-Code sollte immer mit dem Parameter data-ad-client übergeben werden. Außerdem muss entweder data-admob-interstitial-slot oder data-admob-rewarded-slot angegeben werden. Beide Parameter sollten angegeben werden, wenn Ihr Spiel beide Formate verwendet.

Optional können Sie auch den Tag-Parameter data-admob-ads-only=on angeben, um anzugeben, dass in Ihrem Spiel nur Anzeigen aus AdMob ausgeliefert werden sollen und kein Fallback auf AdSense erfolgen soll, wenn das Spiel in einer Umgebung gespielt wird, in der AdMob-Anfragen nicht unterstützt werden (z.B. Apps oder Apps, die nicht mit dem AdMob GMA SDK konfiguriert sind).

Wichtig: Wenn Sie Ihr Spiel so entwerfen, dass es in eine App eingebettet wird, und Sie der Inhaber der App sind oder eine Vereinbarung zur Umsatzbeteiligung mit dem Inhaber der App getroffen haben, können Sie dies nur auf leistungsstarke und richtlinienkonforme Weise tun, indem Sie diesen AdMob-Support nutzen.

Registrieren Sie zuerst das WebView, mit dem Ihr Spiel angezeigt wird, mit dem GMA SDK:

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

Übergeben Sie als Nächstes AdMob-Anzeigenblöcke (einen für Interstitials und einen für Anzeigen mit Prämie):

index.html (Anwendung)

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

Mit dem Aufruf adConfig() wird die aktuelle Konfiguration des Spiels an die Ad Placement API übermittelt. Die API kann diese Informationen dann verwenden, um die angeforderten Anzeigentypen zu filtern, damit sie für das Spiel geeignet sind, z. B. Videoanzeigen, die Ton erfordern, sofern Ton aktiviert ist.

Bei jeder Änderung dieser Konfiguration sollte ein Aufruf an adConfig() erfolgen, z. B. wenn ein Nutzer das Spiel stummschaltet oder die Stummschaltung aufhebt. Rufen Sie adConfig() im Konstruktor des Spiels auf und fügen Sie dann eine Schaltfläche zum Stummschalten und Aufheben der Stummschaltung des Spiels hinzu, das einen zusätzlichen adConfig()-Aufruf ausführt.

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

Fügen Sie nun die HTML-Datei zum Stummschalten hinzu.

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. Ruf `adBreak()` an, wenn das Spiel endet

Der Aufruf adBreak() definiert ein Anzeigen-Placement und verwendet das Placement namens „Placement-Konfiguration“, das alles angibt, was erforderlich ist, um eine Anzeige an diesem Punkt in deinem Spiel auszuliefern. Wenn verschiedene Arten von Anzeigen unterstützt werden, müssen Sie verschiedene Teilmengen der Placement-Konfiguration initialisieren.

Mit dem adBreak()-Aufruf wird ein Placement definiert, auf dem eine Anzeige präsentiert werden könnte. Ob eine Anzeige tatsächlich ausgeliefert wird, hängt von mehreren Faktoren ab:

Der von Ihnen angegebene Anzeigen-Placement-Typ.
Ob es vor diesem Anzeigen-Placement geeignete Nutzerinteraktionen gab.
Ob für den aktuellen Player eine geeignete Anzeige vorhanden ist:
- Ist für sie relevant.
- Entspricht den Datenschutz- und Einwilligungseinstellungen.
Die Anzahl der Anzeigen, die der Nutzer in letzter Zeit gesehen hat.
Die Steuerelemente, die du für dieses Spiel konfiguriert hast:
- Hinweise im Tag.
- In AdSense (Hinweis: Die in AdSense verfügbaren Steuerelemente werden weiterentwickelt)

Fügen Sie Code für eine Interstitial-Anzeige hinzu, die beim Neustart des Spiels eingeblendet wird: Rufen Sie adBreak() in der Funktion play() auf. Diese wird erst ausgeführt, nachdem das Spiel einmal abgespielt wurde.

adBreak() muss als Teil einer Nutzeraktion aufgerufen werden, z. B. durch Klicken auf die Schaltfläche „Wiedergabe“. Andernfalls kann die API keine Anzeigen anfordern und anzeigen.

Erstellen Sie Funktionen, die vor und nach der Werbeunterbrechung aufgerufen werden sollen, die Sie dann in der Placement-Konfiguration adBreak() verwenden. Die Funktionen beforeAd und afterAd werden nur aufgerufen, wenn eine geeignete Anzeige gefunden wird.

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

In der Münzwurf-App werden jetzt Anzeigen-Placements für Anzeigen erstellt.

Ihre eigene App kann neben dem Ende des Spiels möglicherweise zusätzliche, geeignete Orte für Werbung bieten. Das Aufrufen von adBreak() an diesen Orten sollte diesem Beispiel ähneln.

Tests für Produktions-Apps deaktivieren

Bevor Sie die Anwendung veröffentlichen, ist es wichtig, die Zeile data-adbreak-test="on" in index.html zu entfernen oder zu kommentieren, da dieser Code die Testeinstellungen in der Produktionsumgebung aktiviert.

Beispielimplementierung

Voraussetzungen

Beispielcode der App

1. Entwicklungsserver starten

2. HTML5-Spiel erstellen

index.html

game.js

3. Ad Placement API importieren

AdSense-Code einrichten und Testmodus aktivieren

index.html (Web)

Spiel einbetten (optional)

Unterstützung für mobile Apps

MainActivity.java (App)

index.html (Anwendung)

4. Aufruf an adConfig()

game.js

index.html

5. Ruf adBreak() an, wenn das Spiel endet

game.js

Tests für Produktions-Apps deaktivieren

5. Ruf `adBreak()` an, wenn das Spiel endet