adBreak()

Funktionssignatur:

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

Parameter „adBreak()“

Name Typ Beschreibung
Alle Placement-Typen
type String

Der Typ des Placements. Werte:

  • 'preroll' vor dem Laden des Spiels (bevor die UI gerendert wurde)
  • 'start' vor Beginn des Spiels (nachdem die UI gerendert wurde)
  • 'pause': Der Spieler pausiert das Spiel
  • 'next' Spieler wechselt zur nächsten Stufe.
  • 'browse': Der Spieler erkundet Optionen außerhalb des Spiels
  • 'reward' Anzeige mit Prämie
name String (Optional) Ein Name für dieses bestimmte Anzeigen-Placement in Ihrem Spiel. Es handelt sich um eine interne Kennung, die dem Spieler nicht angezeigt wird. In zukünftigen Versionen kann diese Kennung verwendet werden, um zusätzliche Berichts- und Optimierungsfunktionen zu aktivieren.

Wir empfehlen, alle Placements zu benennen.
beforeAd Funktion (Optional) Wird aufgerufen, bevor die Anzeige ausgeliefert wird. Das Spiel sollte den Ton anhalten und stummschalten. Diese Aktionen müssen synchron erfolgen. Die Anzeige wird sofort nach Abschluss dieses Callbacks eingeblendet.
afterAd Funktion (Optional) Wird aufgerufen, wenn die Anzeige erstellt wurde. Bei Anzeigen mit Prämie wird er je nach Spieleraktion nach adDismissed oder adViewed genannt. Diese Funktion sollte verwendet werden, um den Spielfluss fortzusetzen. Beispielsweise kannst du damit die Stummschaltung aufheben und das nächste Level starten.
adBreakDone Funktion (Optional) Wird immer als letzter Schritt in einem adBreak() aufgerufen, auch wenn keine Anzeige ausgeliefert wurde. Die Funktion verwendet als Argument ein placementInfo-Objekt, das so definiert ist: 
{
    breakType: '<type>',
    breakName: '<name>',
    breakFormat: 'interstitial|reward',
    breakStatus:  'error|noAdPreloaded|...|viewed',
}
Eine ausführliche Erläuterung des Objekts „Placement-Info“ finden Sie unter adBreakDone und placementInfo().
Nur Placements mit Prämie...
beforeReward Funktion Wird aufgerufen, wenn eine Anzeige mit Prämie verfügbar ist Die Funktion sollte nur ein Argument (showAdFn()) verwenden, das aufgerufen werden muss, damit die Anzeige mit Prämie ausgeliefert wird.
adDismissed Funktion Wird nur für Anzeigen mit Prämie aufgerufen, wenn der Player die Anzeige schließt. Es wird nur aufgerufen, wenn der Player die Anzeige vor dem Ende schließt. In diesem Fall sollte die Prämie nicht gewährt werden.
adViewed Funktion Wird nur für Anzeigen mit Prämie aufgerufen, wenn der Spieler die Anzeige abschließt, und erhält die Prämie.

adBreakDone() and placementInfo

Wenn die Ad Placement API keine Anzeige zum Anzeigen hat, ruft sie die verschiedenen Vorher-/Nachher-Callbacks nicht auf. Wenn Sie jedoch einen adBreakDone()-Callback angeben, wird dieser immer aufgerufen, auch wenn eine Anzeige nicht erscheint. So können Sie weitere Arbeitsschritte für das Placement ausführen, z. B. zusätzliche Analysen zum Placement protokollieren.

Die Funktion adBreakDone() verwendet als Argument ein placementInfo-Objekt, das so definiert ist:

{
  breakType: '<type>',
  breakName: '<name>',
  breakFormat: 'interstitial|reward',
  breakStatus: 'notReady|timeout|error|noAdPreloaded|frequencyCapped|ignored|other|dismissed|viewed',
}

Dabei haben die Felder in diesem Objekt die folgende Semantik:

  • breakType ist das Typargument, das an adBreak() übergeben wurde
  • breakName ist das Namensargument, das an adBreak() übergeben wurde
  • breakStatus ist der Status des Placements und kann einer der folgenden Werte sein:
breakStatus Grund
'notReady' Die Ad Placement API wurde nicht initialisiert
'timeout' Bei einem Placement ist eine Zeitüberschreitung aufgetreten, weil es zu lange dauerte, bis die Ad Placement API geantwortet hat
'invalid' Das Placement war ungültig und wurde ignoriert. So sollte beispielsweise pro Seitenaufbau nur ein Pre-Roll-Placement vorhanden sein. Nachfolgende Pre-Rolls schlagen mit diesem Status fehl.
'error' Ein Callback enthielt einen JavaScript-Fehler
'noAdPreloaded' Eine Anzeige wurde noch nicht vorab geladen, deshalb wurde dieses Placement übersprungen
'frequencyCapped' Eine Anzeige wurde nicht ausgeliefert, weil das Frequency Capping auf dieses Placement angewendet wurde
'ignored' Der Nutzer hat nicht auf eine Aufforderung zur Prämie geklickt, bevor er das nächste Placement erreicht hat, d. h. showAdFn() wurde vor dem nächsten adBreak() aufgerufen.
'other' Die Anzeige wurde aus einem anderen Grund nicht ausgeliefert. (z. B. Die Anzeige wurde noch abgerufen oder eine zuvor zwischengespeicherte Anzeige wurde entsorgt, weil die Größe des Bildschirms geändert oder das Display gedreht wurde.
'dismissed' Der Nutzer hat eine Anzeige mit Prämie geschlossen, bevor er sie bis zum Ende angesehen hat.
'viewed' Die Anzeige wurde vom Nutzer angesehen.

Hinweis: adBreakDone() ist immer der letzte Callback von adBreak().

Wenn Sie mit afterAd() die Pausierung des Spiels aufheben, nachdem eine Anzeige ausgeliefert wurde, wird adBreakDone() aufgerufen, nachdem das Spiel neu gestartet wurde. Das ist beispielsweise für die Protokollierung von Analysen geeignet. Wenn du jedoch vor dem Neustart deines Spiels zusätzliche Aufgaben erledigen möchtest, verschiebe die Logik, um die Pausierung des Spiels von „afterAd()“ zu „adBreakDone()“ aufzuheben.