Interstitial-Anzeigen einrichten

Plattform auswählen: Android iOS Unity Flutter Android (Legacy)

Interstitial-Anzeigen sind Vollbildanzeigen, die die Benutzeroberfläche der App überlagern. Sie werden an natürlichen Übergangspunkten in Ihrer App eingeblendet, z. B. zwischen Aktivitäten oder während Pausen in Spiellevels.

Wenn in Ihrer App eine Interstitial-Anzeige präsentiert wird, können Nutzer entweder auf die Anzeige tippen und fortfahren oder die Anzeige schließen und zur App zurückkehren. Lesen Sie diese Fallstudie.

In dieser Anleitung wird erklärt, wie Sie Interstitial-Anzeigen in eine Android-App einbinden.

Hinweis

Führen Sie zuerst folgende Schritte aus:

  • Richten Sie GMA Next-Gen SDK ein.
  • Verwenden Sie die Test-Anzeigenblock-ID für Interstitials ca-app-pub-3940256099942544/1033173712.
    • Verwenden Sie beim Erstellen und Testen Ihrer App Testanzeigen anstelle von Live-Anzeigen. Wenn Sie die Test-Anzeigenblock-ID nicht verwenden, kann Google Ihr Konto sperren.
    • Ersetzen Sie diese ID vor der Veröffentlichung Ihrer App durch Ihre Anzeigenblock-ID.
    • Weitere Informationen zu GMA Next-Gen SDK Testanzeigen finden Sie unter Testanzeigen aktivieren.

Vorabladen von Anzeigen (Beta)

Beim Vorabladen von Anzeigen in GMA Next-Gen SDK werden Anzeigen automatisch geladen und im Cache gespeichert.

Das Vorabladen von Anzeigen bietet folgende Vorteile:

  • Referenzverwaltung: Referenzen werden beibehalten, bis Anzeigen präsentiert werden.
  • Automatisches Neuladen: Eine neue Anzeige wird geladen, wenn eine aus dem Cache abgerufen wird.
  • Verwaltung von Wiederholungen: Eine neue Anzeige wird geladen, wenn das Laden einer Anzeige fehlschlägt.
  • Ablaufbehandlung: Anzeigen werden aktualisiert, bevor sie ablaufen.
  • Cache-Optimierung: Die Cache-Reihenfolge wird optimiert, um die Anzeige mit der höchsten Priorität auszuliefern.

Vorabladen von Anzeigen starten

Rufen Sie zum Starten des Vorabladens von Anzeigen die start Methode einmal auf wenn Sie GMA Next-Gen SDK initialisieren. Nachdem Sie die start Methode aufgerufen haben, lädt GMA Next-Gen SDK automatisch Anzeigen vorab und wiederholt fehlgeschlagene Anfragen für vorab geladene Konfigurationen.

Das folgende Beispiel zeigt, wie Sie das Vorabladen von Anzeigen starten:

Kotlin

private fun startPreloading(adUnitId: String) {
  // Call start() once after SDK initialization.
  // Preload only one ad unit per format to optimize performance.
  val adRequest = AdRequest.Builder(adUnitId).build()
  val preloadConfig = PreloadConfiguration(adRequest)
  InterstitialAdPreloader.start(adUnitId, preloadConfig)
}

Java

private void startPreloading(String adUnitId) {
  // Call start() once after SDK initialization.
  // Preload only one ad unit per format to optimize performance.
  AdRequest adRequest = new AdRequest.Builder(adUnitId).build();
  PreloadConfiguration preloadConfig = new PreloadConfiguration(adRequest);
  InterstitialAdPreloader.start(adUnitId, preloadConfig);
}

Ersetzen Sie AD_UNIT_ID durch Ihre Anzeigenblock-ID.

Im vorherigen Beispiel wird die Anzeigenblock-ID als Vorabladungs-ID verwendet. Eine Vorabladungs-ID ist ein String-Bezeichner, den Sie erstellen, um eine Konfiguration für das Vorabladen von Anzeigen zu identifizieren. Wenn Ihre App mehrere Targeting-Konfigurationen für dieselbe Anzeigenblock-ID erfordert, übergeben Sie einen benutzerdefinierten String-Bezeichner.

Das Vorabladen von Anzeigen unterstützt keine Änderungen an Targeting-Parametern oder Anzeigenanfragen. Wenn Sie Targeting-Parameter zwischen Anfragen ändern müssen, verwenden Sie das einzelne Laden.

Vorab geladene Anzeigen abrufen und präsentieren

Rufen Sie vor dem Präsentieren der Anzeige die Methode pollAd auf. Speichern Sie das vorab geladene Anzeigenobjekt nicht. Wenn Sie die pollAd Methode aufrufen, GMA Next-Gen SDK ruft eine verfügbare Anzeige ab und lädt im Hintergrund automatisch die nächste Anzeige vorab. Wenn keine Anzeige verfügbar ist, gibt GMA Next-Gen SDK keine Anzeigen zurück.

Wenn Sie ein verfügbares Anzeigenobjekt haben, rufen Sie die Methode show auf, um die Anzeige zu präsentieren. Das folgende Beispiel zeigt, wie Sie eine vorab geladene Anzeige abrufen und präsentieren:

Kotlin

private fun pollAndShowAd(activity: Activity, adUnitId: String) {
  // Polling returns the next available ad and loads another ad in the background.
  val ad = InterstitialAdPreloader.pollAd(adUnitId)
  if (ad == null) {
    Log.e(TAG, "Interstitial ad is not available.")
    return
  }

  // Interact with the ad object as needed.
  Log.d(TAG, "Interstitial ad response info: ${ad.getResponseInfo()}")
  ad.adEventCallback =
    object : InterstitialAdEventCallback {
      override fun onAdImpression() {
        Log.d(TAG, "Interstitial ad recorded an impression.")
      }
    }
  ad.show(activity)
}

Java

private void pollAndShowAd(Activity activity, String adUnitId) {
  // Polling returns the next available ad and loads another ad in the background.
  final InterstitialAd ad = InterstitialAdPreloader.pollAd(adUnitId);

  // Interact with the ad object as needed.
  if (ad == null) {
    Log.e(TAG, "Interstitial ad is not available.");
    return;
  }

  Log.d(TAG, "Interstitial ad response info: " + ad.getResponseInfo());
  ad.setAdEventCallback(
      new InterstitialAdEventCallback() {
        @Override
        public void onAdImpression() {
          Log.d(TAG, "Interstitial ad recorded an impression.");
        }
      });

  // Show the ad.
  ad.show(activity);
}

Wenn Ihre App ein Anzeigen-Placement erreicht und die Methode show aufrufen kann, rufen Sie die Methode pollAd auf. Rufen Sie die Methode pollAd nicht in Rückrufen für das Vorabladen oder nach dem Prüfen der Methode isAdAvailable auf, um eine Anzeige zu reservieren. Wenn Sie die Metadaten der Anzeige prüfen müssen, bevor Sie sie präsentieren, lesen Sie die Antwortinformationen ohne die Anzeige aus dem Cache zu entfernen.

Auf Anzeigenereignisse warten

Warten Sie vor dem Präsentieren der Anzeige auf Anzeigenereignisse. Im folgenden Beispiel werden Rückrufe für Anzeigenereignisse registriert:

Kotlin

// Listen for ad events.
val ad = interstitialAd
if (ad == null) {
  Log.e(TAG, "Interstitial ad is not ready yet.")
  return
}

ad.adEventCallback =
  object : InterstitialAdEventCallback {
    override fun onAdShowedFullScreenContent() {
      // Interstitial ad did show.
    }

    override fun onAdDismissedFullScreenContent() {
      // Interstitial ad did dismiss.
      interstitialAd = null
    }

    override fun onAdFailedToShowFullScreenContent(
      fullScreenContentError: FullScreenContentError
    ) {
      // Interstitial ad failed to show.
      Log.e(TAG, "Interstitial ad failed to show: ${fullScreenContentError.message}")
    }

    override fun onAdImpression() {
      // Interstitial ad did record an impression.
    }

    override fun onAdClicked() {
      // Interstitial ad did record a click.
    }
  }

Java

// Listen for ad events.
if (interstitialAd == null) {
  Log.e(TAG, "Interstitial ad is not ready yet.");
  return;
}

interstitialAd.setAdEventCallback(
    new InterstitialAdEventCallback() {
      @Override
      public void onAdShowedFullScreenContent() {
        // Interstitial ad did show.
      }

      @Override
      public void onAdDismissedFullScreenContent() {
        // Interstitial ad did dismiss.
        interstitialAd = null;
      }

      @Override
      public void onAdFailedToShowFullScreenContent(
          @NonNull FullScreenContentError fullScreenContentError) {
        // Interstitial ad failed to show.
        Log.e(TAG, "Interstitial ad failed to show: " + fullScreenContentError.getMessage());
      }

      @Override
      public void onAdImpression() {
        // Interstitial ad did record an impression.
      }

      @Override
      public void onAdClicked() {
        // Interstitial ad did record a click.
      }
    });

Optional: Auf Ereignisse für das Vorabladen warten

Wenn Sie mit dem Vorabladen von Anzeigen beginnen, registrieren Sie sich für Ereignisse für das Vorabladen, um benachrichtigt zu werden, wenn Anzeigen erfolgreich vorab geladen wurden, das Vorabladen fehlschlägt oder der Anzeigen-Cache erschöpft ist.

Das folgende Beispiel zeigt, wie Sie sich für Ereignisse für das Vorabladen von Anzeigen registrieren:

Kotlin

val preloadCallback =
  // [Important] Don't call ad preloader start() or pollAd() within the PreloadCallback.
  object : PreloadCallback {
    override fun onAdFailedToPreload(preloadId: String, adError: LoadAdError) {
      Log.d(
        TAG,
        ("Interstitial preload ad $preloadId failed to load with error: ${adError.message}"),
      )
    }

    override fun onAdsExhausted(preloadId: String) {
      Log.i(TAG, "Interstitial preload ad $preloadId is not available")
      // [Important] Don't call ad preloader start() or pollAd() from onAdsExhausted.
    }

    override fun onAdPreloaded(preloadId: String, responseInfo: ResponseInfo) {
      Log.i(TAG, "Interstitial preload ad $preloadId is available")
    }
  }
val adRequest = AdRequest.Builder(adUnitId).build()
val preloadConfig = PreloadConfiguration(adRequest)
InterstitialAdPreloader.start(adUnitId, preloadConfig, preloadCallback)

Java

PreloadCallback preloadCallback =
    // [Important] Don't call ad preloader start() or pollAd() within the PreloadCallback.
    new PreloadCallback() {
      @Override
      public void onAdFailedToPreload(@NonNull String preloadId, @NonNull LoadAdError adError) {
        Log.d(
            TAG,
            String.format(
                "Interstitial preload ad %s failed to load with error: %s",
                preloadId, adError.getMessage()));
        // [Optional] Get the error response info for additional details.
        // ResponseInfo responseInfo = adError.getResponseInfo();
      }

      @Override
      public void onAdsExhausted(@NonNull String preloadId) {
        Log.i(TAG, "Interstitial preload ad " + preloadId + " is not available");
        // [Important] Don't call ad preloader start() or pollAd() from onAdsExhausted.
      }

      @Override
      public void onAdPreloaded(@NonNull String preloadId, @NonNull ResponseInfo responseInfo) {
        Log.i(TAG, "Interstitial preload ad " + preloadId + " is available");
      }
    };

AdRequest adRequest = new AdRequest.Builder(adUnitId).build();
PreloadConfiguration preloadConfig = new PreloadConfiguration(adRequest);
InterstitialAdPreloader.start(adUnitId, preloadConfig, preloadCallback);

Wenn das Laden einer Anzeige fehlschlägt, lädt GMA Next-Gen SDK automatisch Anzeigen vorab und wiederholt fehlgeschlagene Anfragen für vorab geladene Konfigurationen. Rufen Sie in Rückrufen für Fehler keine manuellen Ladeanfragen auf. Rufen Sie in Callback-Methoden für Vorablade-Ereignisse nicht die Methoden pollAd, destroy oder start auf. Wenn Sie diese Methoden in Rückrufen aufrufen, können rekursive Ladeschleifen ausgelöst werden.

Optional: Verfügbarkeit von Anzeigen prüfen

Wenn Sie wissen müssen, ob eine Anzeige verfügbar ist, prüfen Sie die Verfügbarkeit von Anzeigen. Im folgenden Beispiel wird geprüft, ob eine vorab geladene Anzeige verfügbar ist:

Kotlin

private fun isAdAvailable(adUnitId: String): Boolean {
  return InterstitialAdPreloader.isAdAvailable(adUnitId)
}

Java

private boolean isAdAvailable(String adUnitId) {
  return InterstitialAdPreloader.isAdAvailable(adUnitId);
}

Optional: Puffergröße festlegen

Die Puffergröße steuert die Anzahl der vorab geladenen Anzeigen, die im Arbeitsspeicher gespeichert werden. Standardmäßig optimiert Google die Puffergröße, um ein Gleichgewicht zwischen Arbeitsspeicherverbrauch und Latenz beim Ausliefern von Anzeigen zu schaffen. Sie können eine benutzerdefinierte Puffergröße festlegen, um die Anzahl der im Arbeitsspeicher gespeicherten Anzeigen zu erhöhen oder zu verringern. Wir empfehlen eine Puffergröße von zwei vorab geladenen Anzeigen. Wenn der Großteil Ihres Traffics von Geräten mit wenig Arbeitsspeicher stammt, reduzieren Sie die Puffergröße.

Das folgende Beispiel zeigt, wie Sie eine Puffergröße festlegen:

Kotlin

private fun setBufferSize(adUnitId: String) {
  val adRequest = AdRequest.Builder(adUnitId).build()
  // Define a PreloadConfiguration and set the buffer size to 2 preloaded ads.
  val preloadConfig = PreloadConfiguration(adRequest, bufferSize = 2)
  InterstitialAdPreloader.start(adUnitId, preloadConfig)
}

Java

private void setBufferSize(String adUnitId) {
  AdRequest adRequest = new AdRequest.Builder(adUnitId).build();
  // Define a PreloadConfiguration and set the buffer size to 2 preloaded ads.
  PreloadConfiguration preloadConfig = new PreloadConfiguration(adRequest, 2);
  InterstitialAdPreloader.start(adUnitId, preloadConfig);
}

Limits für den Vorabladungs-Cache

GMA Next-Gen SDK erzwingt ein app-weites Limit für die Gesamtzahl der vorab geladenen Anzeigen für alle Anzeigenblöcke und Vorabladungs-IDs:

  • Standardlimit: Google speichert maximal sechs vorab geladene Anzeigen im Arbeitsspeicher. Dieses Limit gilt für alle Formate und Vorabladungs-IDs.
  • Wir empfehlen, für jede Vorabladungs-ID eine Puffergröße von zwei beizubehalten.

Optional: Vorabladen von Anzeigen beenden

Lassen Sie das Vorabladen aktiv, während Ihre App Anzeigen ausliefert. Rufen Sie während dieser Zeit nicht die Methode destroy auf. Wenn Sie in der Sitzung keine Anzeigen für eine bestimmte Vorabladungs-ID mehr präsentieren müssen, können Sie das Vorabladen von Anzeigen beenden. Rufen Sie zum Beenden des Ladens von Anzeigen für eine bestimmte Vorabladungs-ID die Methode destroy mit einer Vorabladungs-ID auf. Wenn Sie die Methode destroy aufrufen, werden alle vorab geladenen Anzeigen, die mit der Vorabladungs-ID verknüpft sind, aus dem Cache entfernt.

Das folgende Beispiel zeigt, wie Sie das Vorabladen von Anzeigen beenden:

Kotlin

private fun stopPreloading(adUnitId: String) {
  // Stops the preloading and destroy preloaded ads.
  InterstitialAdPreloader.destroy(adUnitId)
}

Java

private void stopPreloading(String adUnitId) {
  // Stops the preloading and destroy preloaded ads.
  InterstitialAdPreloader.destroy(adUnitId);
}

Optional: Antwortinformationen lesen

Lesen Sie die Antwortinformationen der nächsten vorab geladenen Anzeige, ohne die Anzeige aus dem Cache zu entfernen. Wenn Sie die Metadaten der Anzeige prüfen müssen, bevor Sie sie präsentieren, lesen Sie die Antwortinformationen, anstatt die Methode pollAd aufzurufen.

Das folgende Beispiel zeigt, wie Sie die Antwortinformationen der nächsten vorab geladenen Anzeige lesen:

Kotlin

val responseInfo = InterstitialAdPreloader.peekAdResponseInfo(preloadId)
if (responseInfo == null) {
  Log.e(TAG, "Failed to peek ad response info.")
  return
}

Log.d(TAG, "Peeked ad response ID: ${responseInfo.responseId}")

Java

ResponseInfo responseInfo = InterstitialAdPreloader.peekAdResponseInfo(preloadId);
if (responseInfo == null) {
  Log.e(TAG, "Failed to peek ad response info.");
  return;
}

Log.d(TAG, "Peeked ad response ID: " + responseInfo.getResponseId());