Interstitial-Anzeigen mit Prämie einrichten

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

Interstitials mit Prämie sind ein Format, mit dem Sie Prämien für Anzeigen anbieten können, die automatisch an natürlichen Übergangspunkten innerhalb einer App ausgeliefert werden. Anders als bei Anzeigen mit Prämie müssen Nutzer nicht zustimmen, sich Interstitials mit Prämie anzusehen.

In dieser Anleitung wird beschrieben, wie Sie Interstitials mit Prämie in eine Android-App einbinden.

Hinweis

Bevor Sie fortfahren, führen Sie die folgenden Schritte aus:

  • Richten Sie GMA Next-Gen SDK ein.
  • Verwenden Sie die Test-Anzeigenblock-ID für Interstitials mit Prämie /21775744923/example/rewarded-interstitial.
    • Verwenden Sie beim Erstellen und Testen Ihrer App Testanzeigen anstelle von Live-Anzeigen. Andernfalls kann es zur Sperrung Ihres Kontos kommen.
    • 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)

Mit dem Vorabladen von Anzeigen (Beta) in GMA Next-Gen SDK werden das Laden und Caching von Anzeigen automatisiert.

Das Vorabladen von Anzeigen bietet folgende Vorteile:

  • Referenzverwaltung: Referenzen werden beibehalten, bis Anzeigen ausgeliefert werden.
  • Automatisches Neuladen: Eine neue Anzeige wird geladen, wenn eine aus dem Cache abgerufen wird.
  • Verwaltete 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 die Methode start einmal beim Start der App auf, um mit dem Vorabladen von Anzeigen zu beginnen. Nachdem Sie die Methode start aufgerufen haben, GMA Next-Gen SDK lädt automatisch Anzeigen vorab und wiederholt fehlgeschlagene Anfragen für vorabgeladene 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)
  RewardedInterstitialAdPreloader.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);
  RewardedInterstitialAdPreloader.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-Identifier, 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-Identifier.

Vorabgeladene Anzeige abrufen und präsentieren

Wenn Sie eine Anzeige präsentieren möchten, rufen Sie die Methode pollAd auf. GMA Next-Gen SDK ruft eine verfügbare Anzeige ab und lädt automatisch die nächste Anzeige im Hintergrund 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. Verwenden Sie einen Prämien-Listener, um Prämienereignisse zu verarbeiten. Das folgende Beispiel zeigt, wie Sie eine vorabgeladene 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 = RewardedInterstitialAdPreloader.pollAd(adUnitId)
  if (ad == null) {
    Log.e(TAG, "Rewarded interstitial ad is not available.")
    return
  }

  // Interact with the ad object as needed.
  Log.d(TAG, "Rewarded interstitial ad response info: ${ad.getResponseInfo()}")
  ad.adEventCallback =
    object : RewardedInterstitialAdEventCallback {
      override fun onAdImpression() {
        Log.d(TAG, "Rewarded interstitial ad recorded an impression.")
      }
    }
  ad.show(activity) { rewardItem -> Log.d(TAG, "User earned reward: ${rewardItem.amount}") }
}

Java

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

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

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

  // Show the ad.
  ad.show(
      activity,
      rewardItem -> {
        Log.d(TAG, "User earned reward: " + rewardItem.getAmount());
      });
}

Rufen Sie die Methode pollAd erst auf, wenn Sie bereit sind, eine Anzeige zu präsentieren. Informationen zum Lesen der Anzeigenantwort, ohne sie zu präsentieren, finden Sie unter Antwortinformationen lesen.

Anzeigenereignisse beobachten

Beobachten Sie Anzeigenereignisse, bevor Sie die Anzeige präsentieren. Das folgende Beispiel zeigt, wie Sie Callbacks für Anzeigenereignisse registrieren:

Kotlin

private fun listenToAdEvents() {
  // Listen for ad events.
  val ad = rewardedInterstitialAd
  if (ad == null) {
    Log.e(TAG, "Rewarded interstitial ad is not ready yet.")
    return
  }

  ad.adEventCallback =
    object : RewardedInterstitialAdEventCallback {
      override fun onAdShowedFullScreenContent() {
        // Rewarded interstitial ad did show.
      }

      override fun onAdDismissedFullScreenContent() {
        // Rewarded interstitial ad did dismiss.
        rewardedInterstitialAd = null
      }

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

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

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

Java

private void listenToAdEvents() {
  // Listen for ad events.
  if (rewardedInterstitialAd == null) {
    Log.e(TAG, "Rewarded interstitial ad is not ready yet.");
    return;
  }

  rewardedInterstitialAd.setAdEventCallback(
      new RewardedInterstitialAdEventCallback() {
        @Override
        public void onAdShowedFullScreenContent() {
          // Rewarded interstitial ad did show.
        }

        @Override
        public void onAdDismissedFullScreenContent() {
          // Rewarded interstitial ad did dismiss.
          rewardedInterstitialAd = null;
        }

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

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

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

Optional: Serverseitige Überprüfungscallbacks (SSV) validieren

Wenn Ihre App zusätzliche Daten in serverseitigen Überprüfungscallbacks benötigt, verwenden Sie die Funktion für benutzerdefinierte Daten von Interstitials mit Prämie. Jeder Stringwert, der für ein Objekt für Interstitial-Anzeigen mit Prämie festgelegt wurde, wird an den Abfrageparameter custom_data des SSV-Callbacks übergeben. Wenn kein benutzerdefinierter Datenwert festgelegt ist, ist der custom_data Parameterwert des Abfrageparameters im SSV-Callback nicht vorhanden.

Das folgende Codebeispiel zeigt, wie Sie benutzerdefinierte Daten für ein Objekt für Interstitials mit Prämie festlegen, bevor Sie die Anzeige präsentieren:

Kotlin

RewardedInterstitialAd.load(
  context,
  AD_UNIT_ID,
  AdRequest.Builder().build(),
  object : RewardedInterstitialAdLoadCallback() {
    override fun onAdLoaded(ad: RewardedInterstitialAd) {
      rewardedInterstitialAd = ad
      val options =
        ServerSideVerificationOptions.Builder().setCustomData("SAMPLE_CUSTOM_DATA_STRING").build()
      rewardedInterstitialAd?.setServerSideVerificationOptions(options)
    }
  },
)

Java

RewardedInterstitialAd.load(
    context,
    AD_UNIT_ID,
    new AdRequest.Builder().build(),
    new RewardedInterstitialAdLoadCallback() {
      @Override
      public void onAdLoaded(RewardedInterstitialAd ad) {
        rewardedInterstitialAd = ad;
        ServerSideVerificationOptions options =
            new ServerSideVerificationOptions.Builder()
                .setCustomData("SAMPLE_CUSTOM_DATA_STRING")
                .build();
        rewardedInterstitialAd.setServerSideVerificationOptions(options);
      }
    });

Ersetzen Sie SAMPLE_CUSTOM_DATA_STRING durch Ihre benutzerdefinierten Daten.

Optional: Vorabladungsereignisse beobachten

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

Das folgende Beispiel zeigt, wie Sie sich für Vorabladungsereignisse für 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,
        "Rewarded interstitial preload ad $preloadId failed to load with error: ${adError.message}",
      )
    }

    override fun onAdsExhausted(preloadId: String) {
      Log.i(TAG, "Rewarded 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, "Rewarded interstitial preload ad $preloadId is available")
    }
  }
val adRequest = AdRequest.Builder(adUnitId).build()
val preloadConfig = PreloadConfiguration(adRequest)
RewardedInterstitialAdPreloader.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(
                "Rewarded 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, "Rewarded 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, "Rewarded interstitial preload ad " + preloadId + " is available");
      }
    };
AdRequest adRequest = new AdRequest.Builder(adUnitId).build();
PreloadConfiguration preloadConfig = new PreloadConfiguration(adRequest);
RewardedInterstitialAdPreloader.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 vorabgeladene Konfigurationen.

Optional: Anzeigenverfügbarkeit prüfen

Wenn Sie wissen müssen, ob eine Anzeige verfügbar ist, prüfen Sie die Anzeigenverfügbarkeit. Das folgende Beispiel zeigt, wie Sie prüfen, ob eine vorabgeladene Anzeige verfügbar ist:

Kotlin

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

Java

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

Optional: Puffergröße festlegen

Die Puffergröße steuert die Anzahl der vorabgeladenen Anzeigen, die im Arbeitsspeicher gespeichert werden. Standardmäßig optimiert Google die Puffergröße, um ein Gleichgewicht zwischen Arbeitsspeicherverbrauch und Latenz bei der Anzeigenauslieferung zu schaffen. Sie können eine benutzerdefinierte Puffergröße festlegen, um die Anzahl der im Arbeitsspeicher gespeicherten Anzeigen zu erhöhen.

Das folgende Beispiel zeigt, wie Sie eine Puffergröße von zwei vorabgeladenen Anzeigen 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)
  RewardedInterstitialAdPreloader.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);
  RewardedInterstitialAdPreloader.start(adUnitId, preloadConfig);
}

Limits für den Vorabladungscache

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

  • Standardlimit: Google speichert maximal sechs vorabgeladene 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

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 die Methode destroy mit einer Vorabladungs-ID auf, um das Laden von Anzeigen für eine bestimmte Vorabladungs-ID zu beenden. Durch Aufrufen der Methode destroy werden alle vorabgeladenen 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.
  RewardedInterstitialAdPreloader.destroy(adUnitId)
}

Java

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

Optional: Antwortinformationen lesen

Lesen Sie die Antwortinformationen der nächsten vorabgeladenen Anzeige, ohne die Anzeige aus dem Cache zu entfernen.

Das folgende Beispiel zeigt, wie Sie die Informationen zur nächsten vorabgeladenen Anzeigenantwort lesen:

Kotlin

val responseInfo = RewardedInterstitialAdPreloader.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 = RewardedInterstitialAdPreloader.peekAdResponseInfo(preloadId);
if (responseInfo == null) {
  Log.e(TAG, "Failed to peek ad response info.");
  return;
}

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