Interstitial-Anzeigen mit Prämie einrichten

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

Interstitial-Anzeigen mit Prämie sind ein Format, bei dem Sie Prämien für das Ansehen von 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 Interstitial-Anzeigen mit Prämie anzusehen. Weitere Informationen finden Sie im Leitfaden für Interstitials mit Prämie.

In diesem Leitfaden wird beschrieben, wie Sie Interstitial-Anzeigen 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 Interstitial-Anzeigen mit Prämie ca-app-pub-3940256099942544/5354046379.
    • Verwenden Sie beim Erstellen und Testen Ihrer App Testanzeigen anstelle von Live-Anzeigen. Wenn Sie die Testanzeigenblock-ID nicht verwenden, kann Google Ihr Konto sperren.
    • Ersetzen Sie diese ID durch Ihre Anzeigenblock-ID, bevor Sie Ihre App veröffentlichen.
    • Weitere Informationen zu GMA Next-Gen SDK-Testanzeigen finden Sie unter Testanzeigen aktivieren.

Vorabladen von Anzeigen (Beta)

Das Vorabladen von Anzeigen in GMA Next-Gen SDK automatisiert das Laden und Caching von Anzeigen.

Das Vorabladen von Anzeigen bietet folgende Vorteile:

  • Referenzverwaltung: Referenzen werden beibehalten, bis Anzeigen ausgeliefert werden.
  • Automatisches Aktualisieren: Es wird eine neue Anzeige geladen, wenn eine Anzeige aus dem Cache abgerufen wird.
  • Verwaltete Wiederholungsversuche: Es wird eine neue Anzeige geladen, wenn das Laden einer Anzeige fehlschlägt.
  • Ablaufbehandlung: Anzeigen werden vor dem Ablauf aktualisiert.
  • Cache-Optimierung: Die Cache-Reihenfolge wird optimiert, um die Anzeige mit der höchsten Priorität auszuliefern.

Vorabladen von Anzeigen starten

Wenn Sie mit dem Vorabladen von Anzeigen beginnen möchten, rufen Sie die Methode start einmal auf, wenn Sie GMA Next-Gen SDK initialisieren. Nachdem Sie die Methode start aufgerufen haben, werden Anzeigen automatisch von GMA Next-Gen SDK vorab geladen und fehlgeschlagene Anfragen für vorab geladene Konfigurationen werden wiederholt.

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 die ID Ihres Anzeigenblocks.

Im vorherigen Beispiel wird die Anzeigenblock-ID als Vorablade-ID verwendet. Eine Vorablade-ID ist eine String-ID, die Sie erstellen, um eine Konfiguration für das Vorabladen von Anzeigen zu identifizieren. Wenn für Ihre App mehrere Targeting-Konfigurationen für dieselbe Anzeigenblock-ID erforderlich sind, übergeben Sie eine benutzerdefinierte String-ID.

Beim Vorabladen von Anzeigen können Targeting-Parameter oder Anzeigenanfragen nicht geändert werden. Wenn Sie die Targeting-Parameter zwischen Anfragen ändern müssen, verwenden Sie die einzelne Ladung.

Vorab geladene Anzeige abrufen und ausliefern

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

Wenn ein Anzeigenobjekt verfügbar ist, rufen Sie die Methode show auf, um die Anzeige zu präsentieren. Verwenden Sie einen Prämien-Listener, um Ereignisse mit Prämie zu verarbeiten. Das folgende Beispiel zeigt, wie eine vorab geladene Anzeige abgerufen und angezeigt wird:

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

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 Preload-Callbacks oder nach dem Prüfen der Methode isAdAvailable auf, um eine Anzeige zu halten. Wenn Sie die Anzeigenmetadaten prüfen müssen, bevor die Anzeige ausgeliefert wird, lesen Sie die Antwortinformationen, ohne die Anzeige aus dem Cache zu entfernen.

Auf Anzeigenereignisse warten

Bevor die Anzeige ausgeliefert wird, müssen Sie auf Anzeigenereignisse warten. Im folgenden Beispiel werden Callbacks für Anzeigenereignisse registriert:

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: Callbacks für die serverseitige Überprüfung (SSV) validieren

Wenn Sie Nutzer- und Anwendungskontext in serverseitigen Überprüfungs-Callbacks übergeben möchten, legen Sie die Überprüfungsoptionen für das Anzeigenobjekt fest, bevor die Anzeige eingeblendet wird. Da SSV-Callbacks von Google ohne Sitzungsstatus auf Ihrem Server eingehen, hängen Sie die folgenden optionalen Strings an. Google leitet diese Strings unverändert als signierte Suchparameter im SSV-Callback weiter.

  • user_id-Suchparameter: Identifiziert den Nutzer, dem die Prämie gutgeschrieben werden soll, z. B. eine interne Konto-ID.
  • custom_data-Abfrageparameter: Enthält App-Daten, z. B. die Platzierung der Prämie, das Spiellevel oder eine vom Server generierte Nonce.

Wenn Sie keinen Wert festlegen, lässt Google diesen Suchparameter im SSV-Callback weg.

Im folgenden Beispiel werden benutzerdefinierte Daten für ein Anzeigenobjekt festgelegt, bevor die Anzeige eingeblendet wird:

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.

Wichtiger Hinweis: Der Abfrageparameter custom_data ist prozentcodiert. Bevor Sie den Wert parsen, müssen Sie den String auf Ihrem Server URL-decodieren und die Callback-Signatur überprüfen, bevor Sie den Suchparametern user_id oder custom_data vertrauen.

Optional: Auf Vorablade-Ereignisse warten

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

Im folgenden Beispiel wird gezeigt, wie Sie sich für das Vorabladen von Anzeigenereignissen 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 eine Anzeige nicht geladen werden kann, lädt GMA Next-Gen SDK automatisch Anzeigen vorab und wiederholt fehlgeschlagene Anfragen für vorab geladene Konfigurationen. Rufen Sie keine manuellen Ladeanfragen in Fehler-Callbacks auf. Rufen Sie in Callback-Methoden für Vorablade-Ereignisse nicht die Methoden pollAd, destroy oder start auf. Wenn Sie diese Methoden in Callbacks aufrufen, kann das zu rekursiven Ladeschleifen führen.

Optional: Verfügbarkeit von Anzeigen prüfen

Wenn Sie wissen möchten, ob eine Anzeige verfügbar ist, prüfen Sie die Anzeigenverfügbarkeit. Im folgenden Beispiel wird geprüft, ob eine vorab geladene 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 bestimmt die Anzahl der vorab geladenen Anzeigen, die im Arbeitsspeicher gehalten werden. Standardmäßig optimiert Google die Puffergröße, um den Arbeitsspeicherverbrauch und die Latenz bei der Anzeigenbereitstellung auszugleichen. 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, sollten Sie die Puffergröße reduzieren.

Im folgenden Beispiel wird gezeigt, wie eine Puffergröße festgelegt wird:

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

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

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

Optional: Vorabladen von Anzeigen beenden

Lassen Sie das Vorabladen aktiviert, während in Ihrer App Anzeigen ausgeliefert werden. Verwenden Sie während dieser Zeit nicht die Methode destroy. Wenn Sie in der Sitzung keine Anzeigen für eine bestimmte Vorablade-ID mehr ausliefern müssen, können Sie das Vorabladen von Anzeigen beenden. Wenn Sie das Laden von Anzeigen für eine bestimmte Vorablade-ID beenden möchten, rufen Sie die Methode destroy mit einer Vorablade-ID auf. Wenn Sie die Methode destroy aufrufen, werden alle vorab geladenen Anzeigen, die mit der Vorab-Lade-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: Informationen zur Antwort lesen

Die Antwortinformationen der nächsten vorab geladenen Anzeige lesen, ohne die Anzeige aus dem Cache zu entfernen. Wenn Sie Anzeigenmetadaten prüfen müssen, bevor Sie eine Anzeige einblenden, lesen Sie die Antwortinformationen, anstatt die Methode pollAd aufzurufen.

Im folgenden Beispiel wird gezeigt, wie Sie die Informationen zur nächsten vorab geladenen 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());