Ad Placement API verwenden

Die Ad Placement API enthält zwei Funktionen: adBreak() und adConfig(), die im folgenden globalen Namespace definiert sind. Die meisten Argumente sind Funktionen, die Sie bereitstellen, um die wichtigsten Schritte bei der Vorbereitung und Darstellung einer Anzeige zu verarbeiten:

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

Mit diesen Funktionen können Sie Anzeigen in Ihrem Spiel platzieren und konfigurieren. Die oben gezeigten Argumente sind die einzigen gültigen Argumente, die an diese Funktionen übergeben werden können. Für die verschiedenen Anzeigentypen sind unterschiedliche Teilmengen dieser Argumente erforderlich, wie unten beschrieben.

adBreak() ist die Schlüsselfunktion zum Platzieren von Anzeigen in Ihrem Spiel. Es definiert ein Anzeigen-Placement und verwendet ein Objekt namens Placement-Konfiguration, in dem alles angegeben ist, was zum Ausliefern einer Anzeige erforderlich ist.

Mit der Funktion adBreak() wird ein Placement definiert, in dem eine Anzeige gezeigt werden könnte. Ob eine Anzeige tatsächlich ausgeliefert wird, hängt von Faktoren wie den folgenden ab:

  • Der von Ihnen angegebene Typ des Anzeigen-Placements
    • Wird diese Anzeige zu Beginn des Spiels ausgeliefert? Zwischen den Levels? In einem Moment, in dem der Spieler das Spiel pausiert hat?
  • Ob für den aktuellen Player eine geeignete Anzeige vorhanden ist
    • Ist diese Anzeige für sie relevant?
    • Entspricht sie den Datenschutz- und Einwilligungseinstellungen?
  • Anzahl der Anzeigen, die der Zuschauer in letzter Zeit gesehen hat
  • Die Steuerungseinstellungen, z. B. die Anzeigenhäufigkeit, die Sie für dieses Spiel konfiguriert haben
    • entweder als Hinweise im Tag oder
    • In AdSense – die in AdSense verfügbaren Einstellungen werden im Laufe der Zeit weiterentwickelt.

Welche Art von Anzeige ausgeliefert wird, hängt ebenfalls von ähnlichen Faktoren ab.

Hinweis: Bei einem Aufruf von adBreak() wird möglicherweise gar keine Anzeige ausgeliefert. Damit wird lediglich ein Ort deklariert, an dem eine Anzeige ausgeliefert werden könnte.

Das ist anders als bei herkömmlichen APIs, bei denen Ihr Code immer weiß, ob eine Anzeige verfügbar ist, und Sie im Spiel entscheiden, ob sie präsentiert wird. Bei diesem Ansatz wird die Entscheidung, ob eine Anzeige an einer bestimmten Position ausgeliefert wird, der Ad Placement API überlassen. Dieses Muster wird manchmal als „Inversion of Control“ bezeichnet.

Der Grund für die Umstellung unserer Spiele-API auf dieses Modell ist, dass der Code, den Sie in Ihrem Spiel schreiben müssen, dadurch verkürzt wird. Zweitens ist es einfacher, richtlinienkonforme Placements mit einer hervorragenden Nutzererfahrung zu liefern. So konnten wir Spieleverlagen einige unserer leistungsstärksten Formate zur Verfügung stellen. Außerdem wird der Prozess des Platzierens von Anzeigen in Ihrem Spiel von den Monetarisierungsentscheidungen über Art und Anzahl der zu schaltenden Anzeigen getrennt.

Wir möchten, dass Sie Ihre Monetarisierungseinstellungen ändern und die Nutzerfreundlichkeit steuern können, ohne eine neue Version Ihres Spiels bearbeiten und veröffentlichen zu müssen. Dazu können Sie anfangs Hinweise im Tag angeben. In zukünftigen Versionen werden wir die Einstellungen jedoch direkt in der AdSense- und AdMob-Benutzeroberfläche bereitstellen können.

Interstitials

Eine Interstitial-Anzeige ist eine Vollbildanzeige, die zu verschiedenen Zeitpunkten in Ihrem Spiel eingeblendet werden kann, z. B. wenn der Spieler das Spiel startet oder nachdem er ein Level abgeschlossen hat. Das Spiel wird pausiert, das gesamte Dokument wird abgedeckt und der Spieler kann auf die Anzeige klicken (in diesem Fall wird die Anzeige in einem anderen Tab des Browsers angezeigt) oder sie schließen, um mit dem Spiel fortzufahren.

Wenn Sie ein Interstitial-Anzeigen-Placement erstellen möchten, füllen Sie die folgenden Felder in der Placement-Konfiguration aus:

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

Das type-Argument ist erforderlich. Wir empfehlen, Placements immer zu benennen. Die anderen Callbacks sind optional.

Anrufsequenz

Sehen Sie sich die Aufrufsequenz für eine Interstitial-Anzeige an.

Sequenzdiagramm für Interstitial-Anzeigenaufrufe

Beschreibung

Interstitial – Detaillierte Anrufsequenz
Ihr H5-Spiel Ad Placement API
  Initialisierung und Vorabladen von Anzeigen
Spiel ausführen  

Eine gute Gelegenheit, eine Anzeige zu schalten…

adBreak() →

 
 

Es ist eine Anzeige verfügbar und jetzt ist ein guter Zeitpunkt, sie zu präsentieren.

← beforeAd()
Das Spiel wird pausiert, der Ton wird stummgeschaltet und die Anzeige wird vorbereitet.

return zur API →

 
  Die Interstitial-Anzeige wird über die Ad Placement API gerendert. Der Spieler kann auf die Anzeige klicken, die in einem neuen Tab geöffnet wird. Sie müssen die Anzeige schließen, um das Spiel fortzusetzen.
  ← afterAd() wird aufgerufen, wenn eine Anzeige ausgeliefert wurde.
Das Spiel wird fortgesetzt und der Ton wird wieder aktiviert.  
  ← adBreakDone()adBreakDone() wird immer aufgerufen (auch wenn keine Anzeige ausgeliefert wurde)
Das Spiel protokolliert Analysen zu diesem Placement.  

Hinweise

  • adBreak() ist eine asynchrone Funktion, die sofort zurückgegeben wird.
  • Wenn für ein Placement keine Anzeige ausgeliefert werden kann, werden keine der Callbacks aufgerufen, d. h. weder beforeAd() noch afterAd().
  • Damit das Spiel während der Anzeigenschaltung nicht weiter ausgeführt wird, verwenden Sie den beforeAd()-Callback, um den Ton stummzuschalten und das Spiel zu pausieren.
  • beforeAd() ist synchron. Die Ad Placement API zeigt erst eine Anzeige, wenn sie zurückgegeben wird.
  • Starte das Spiel neu und hebe die Stummschaltung auf, wenn du den Anruf von afterAd() erhältst.
  • Falls angegeben, wird adBreakDone() immer aufgerufen, auch wenn in diesem Placement keine Anzeige ausgeliefert wurde.
  • Wenn Sie adBreak() aufrufen, während eine andere Anzeige ausgeliefert wird, schlägt der Aufruf fehl und in der JavaScript-Konsole wird eine Warnung angezeigt.

Pre-Rolls

Ein Preroll ist ein Interstitial, das angezeigt wird, bevor die Benutzeroberfläche Ihres Spiels geladen wird. Es ist das Erste, was ein Spieler sieht, wenn er zu Ihrem Spiel navigiert. Da ein Preroll sehr früh beim Laden der Seite erfolgt und Ihr Spiel noch nicht angezeigt wird, sind die üblichen Aufrufe zum Pausieren und Stummschalten Ihres Spiels nicht erforderlich. Stattdessen verwenden Sie den adBreakDone()-Callback, um den Start Ihres Spiels mit der Anzeige abzustimmen, d. h. die Benutzeroberfläche zu rendern und mit der Wiedergabe von Audio zu beginnen. Pro Seitenaufruf kann nur ein Preroll ausgelöst werden.

Anrufsequenz

Der Aufruf für einen Preroll erfolgt sehr früh beim Laden der Seite. Da die Benutzeroberfläche Ihres Spiels zu diesem Zeitpunkt noch nicht gerendert wurde, sollten Sie die beforeAd()- und afterAd()-Callbacks nicht übergeben. Verwenden Sie stattdessen den adBreakDone()-Callback, um Ihr Spiel nach dem Placement zu starten. Dieser wird garantiert aufgerufen, auch wenn keine Anzeige ausgeliefert wurde.

Sequenzdiagramm für Pre-Roll-Anzeigenaufrufe

Wenn Sie den folgenden Code früh in Ihrer Spiellogik aufrufen, wird eine Preroll-Anzeige ausgeliefert. Die Benutzeroberfläche sollte erst gerendert werden, nachdem dieser Code aufgerufen wurde.

// Game must not be running.
// Nothing in the game area should be clickable
adBreak({
   type: ‘preroll',
   adBreakDone: startGame,
})
Preroll – Detaillierte Anrufsequenz
Ihr H5-Spiel Ad Placement API
  API-Initialisierung und Vorab-Caching von Anzeigen werden gestartet
Wird ausgeführt, wurde aber noch nicht gestartet und hat keine Benutzeroberfläche angezeigt  

adBreak(type:'preroll',…) →

 
 

Die Ad Placement API wird initialisiert und Anzeigen werden geladen. Wenn es eine Anzeige gibt, wird sie eingeblendet. Der Spieler kann auf die Anzeige klicken, die in einem neuen Tab geöffnet wird. Er muss sie schließen, damit das Spiel gestartet werden kann.

 

← adBreakDone() wird immer aufgerufen (auch wenn keine Anzeige ausgeliefert wurde)

Die Benutzeroberfläche des Spiels wird auf dem Bildschirm gerendert und der Spieler kann jetzt mit ihr interagieren. Das Spiel kann das an adBreakDone() übergebene placementInfo-Objekt nach Bedarf verwenden, z. B. um zusätzliche Analysen zu protokollieren.

  

Hinweise

  • Bei einem Pre-Roll wird immer versucht, Anzeigen vorab zu laden:
    • Bei Prerolls ist kein Aufruf von adConfig(preloadAds: ‘on') erforderlich.
  • Wie bei anderen Anzeigen-Placements kann es sein, dass bei einem Preroll eine Anzeige ausgeliefert wird oder nicht.
  • beforeAd() und afterAd() sollten nicht an einen Preroll übergeben werden.
    • Da Pre-Roll-Anzeigen vor dem Start Ihres Spiels ausgeliefert werden, müssen Sie den Spielsound nicht pausieren oder stummschalten.
    • Wenn Sie beforeAd() oder afterAd() mit einem Preroll übergeben, schlägt der Aufruf fehl und in der JavaScript-Konsole wird ein Fehler protokolliert.
  • Bei einem Pre-Roll wird automatisch gewartet, bis die Ad Placement API initialisiert und Anzeigen vorab geladen wurden:
    • Es gibt jedoch ein Zeitlimit (2 Sekunden), das verhindert, dass der Aufruf unbegrenzt verzögert wird. So wird sichergestellt, dass adBreakDone() rechtzeitig aufgerufen wird und Ihr Spiel startet.
    • adBreakDone() wird immer aufgerufen, auch wenn keine Anzeige vorhanden ist.
  • Wir empfehlen, einen Preroll zu verwenden, um Anzeigen vor dem Start Ihres Spiels zu platzieren.
    • Alternativ können Sie den onReady()-Callback für adConfig() als Mechanismus verwenden, um Ihre Spiellogik mit der Initialisierung der API und dem Vorabladen von Anzeigen zu sequenzieren.

Anzeigen mit Prämie

Mit Anzeigen mit Prämie können Sie Ihre Spieler mit In-App-Artikeln belohnen, wenn sie sich eine Anzeige ansehen. Interstitials sind Opt-out-Anzeigen. Einem Spieler wird die Anzeige präsentiert und er kann sie schließen. Anzeigen mit Prämie sind opt-in. Spieler können selbst entscheiden, ob und wann sie sich eine Anzeige ansehen möchten, um eine Prämie zu erhalten.

Im Gegensatz zu Interstitials, bei denen der Spieler die Anzeige jederzeit schließen kann, muss er sie ansehen, um eine Prämie zu erhalten. Die Mindestdauer kann je nach angezeigtem Creative variieren.

Da Anzeigen mit Prämie für den Spieler optional sind, müssen sie stärker in den Spielfluss integriert werden. Sie müssen Funktionen bereitstellen, mit denen eine Aufforderung zur Prämie in Ihrem Spiel gerendert und die Prämie dem Spieler zugewiesen wird, wenn er sich die Anzeige ansieht.

Prämien dürfen keinen Wert außerhalb Ihrer App haben, dürfen keinen Geldwert haben (oder leicht gegen einen solchen eingetauscht werden können) und dürfen nicht gegen Waren oder Dienstleistungen verkauft oder eingetauscht werden. Außerdem sollten Sie Spieler nicht dazu anregen, auf Anzeigen zu klicken. Weitere Informationen finden Sie im Richtlinienentwurf für Interstitials und Belohnungen.

Da Prämien für den Spieler optional sind, können Sie sie an beliebiger Stelle in Ihrem Spiel einfügen und zusätzlich zu Interstitials verwenden. Wie bei Interstitials handelt es sich bei diesen Placements um Möglichkeiten, Anzeigen mit Prämie auszuliefern. Die Ad Placement API ruft Ihren Code nur auf, wenn an einem bestimmten Punkt in Ihrem Spiel tatsächlich eine Anzeige mit Prämie angeboten wird.

Auch hier ist das Ziel, dass Sie Ihr Spiel nur einmal in die AdPlacement API einbinden müssen. Im Laufe der Zeit können Sie dann über Steuerelemente im Tag oder in AdSense die genaue Mischung der aktivierten Anzeigen ändern, ohne Ihr Spiel neu codieren und veröffentlichen zu müssen.

Der Typ einer Placement-Ressource mit Prämie ist immer 'reward' und alle Felder in der Placement-Konfiguration können verwendet werden.

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

Die wichtigsten neuen Funktionen sind beforeReward(), der Trigger, der signalisiert, dass Sie die Aufforderung zur Prämie rendern sollten, und adViewed(), die aufgerufen wird, wenn der Spieler die Anzeige erfolgreich angesehen hat, damit Sie die Prämie zuweisen können.

Sie könnten eine Placement-ID für Prämien so definieren:

adBreak({
   type: 'reward',
   name: 'new_life_reward_1',
   beforeAd: pauseGame,
   afterAd: restartGame,
   beforeReward: showRewardPrompt,
   adDismissed: adDismissed,
   adViewed: adViewed,
   adBreakDone: breakDone,
});

Anzeigen mit Prämie beginnen mit einer Aufforderung in Ihrem Spiel, in der dem Spieler eine Prämie angeboten wird, wenn er sich eine Anzeige ansieht.

Beispiel für einen Anzeigen-Prompt: „Sehen Sie sich ein Video an, um ein Extraleben zu erhalten.“

Aufrufsequenz für eine Anzeige mit Prämie

Sequenzdiagramm für Anrufe mit Prämie

Beschreibung

Anzeige mit Prämie – Detaillierte Anrufsequenz
Ihr H5-Spiel Ad Placement API
  Initialisierung und Vorab-Caching von Anzeigen
Spiel ausführen  

adBreak(type:'reward', ... ) →

 
 

Es ist eine Anzeige verfügbar. Starten Sie also ein Placement für Anzeigen mit Prämie. beforeReward() wird synchron aufgerufen, d. h. direkt nach dem Aufruf von adBreak().

← beforeReward(showAdFn)

Das Spiel rendert den Prämien-Prompt. So hat der Spieler die Möglichkeit, sich eine Anzeige anzusehen und dafür eine Prämie zu erhalten. Es können mehrere Arten von Prämien angeboten werden, z. B. ein neues Leben oder eine Goldmünze.

Der Spieler kann auf eine Aufforderung zur Belohnung klicken, sie schließen oder einfach ignorieren.

Wenn der Nutzer auf eine Aufforderung klickt, speichert das Spiel die Art der angeforderten Prämie und ruft showAdFn()... auf.

Wenn die Aufforderung zur Prämie geschlossen oder ignoriert wird, passiert nichts, bis Sie einen weiteren Aufruf von adBreak() mit einem Placement-Typ für Prämien vornehmen. Dann wird der Status aus diesem Aufruf von der Ad Placement API zurückgesetzt und bereinigt. Wenn die App showAdFn aus einer vorherigen Werbeunterbrechung aufruft, hat das keine Auswirkungen.

  

showAdFn() →

 
  ← beforeAd()

Das Spiel wird pausiert, der Ton wird stummgeschaltet und die Anzeige wird vorbereitet.

return zur API →

 
  Die Anzeige wird über die API ausgeliefert. Sie hat eine Schaltfläche zum Schließen und einen Countdown, der angibt, wie viel Zeit noch in der Anzeige verbleibt.
WENN der Nutzer die Anzeige schließt...
  ← adDismissed()
Der Spieler hat die Anzeige geschlossen und das Spiel hat die Prämie nicht ausgegeben.  
ELSE the player watches the ad to completion...
  ← adViewed()
Der Spieler hat sich die Anzeige bis zum Ende angesehen und das Spiel hat die Belohnung ausgegeben. Dies erfolgt in der Regel durch Festlegen eines Spielstatus, der dann beim Neustart des Spiels mit dem Aufruf von afterAd() (siehe unten) abgerufen wird.  
Nachdem die Anzeige angesehen oder geschlossen wurde…
  ← afterAd() wird aufgerufen, wenn eine Anzeige ausgeliefert wurde.
Das Spiel wird fortgesetzt und der Ton wird wieder aktiviert.  
  ← adBreakDone()adBreakDone() wird immer aufgerufen (auch wenn keine Anzeige ausgeliefert wurde)
Das Spiel protokolliert Analysen zu diesem Placement.  

Hinweise

  • adBreak() ist eine asynchrone Funktion, die sofort zurückgegeben wird.
  • Wenn für eine Platzierung keine Anzeige ausgeliefert werden kann, werden keine der Callbacks aufgerufen, d. h. weder beforeAd() noch beforeReward().
  • Damit das Spiel während der Anzeigenschaltung nicht weiter ausgeführt wird, verwenden Sie den beforeAd()-Callback, um den Ton stummzuschalten und das Spiel zu pausieren.
  • beforeAd() ist synchron. Die Ad Placement API zeigt erst eine Anzeige, wenn sie zurückgegeben wird.
  • Starte das Spiel neu und hebe die Stummschaltung auf, wenn du den Anruf von afterAd() erhältst.
  • Falls angegeben, wird adBreakDone() immer aufgerufen, auch wenn in diesem Placement keine Anzeige ausgeliefert wurde.
  • Wenn Sie adBreak() aufrufen, während eine andere Anzeige ausgeliefert wird, schlägt der Aufruf fehl und in der JavaScript-Konsole wird eine Warnung angezeigt.