Anzeigen mit Prämie einrichten

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

Mit Anzeigen mit Prämie können Sie Nutzern, die mit Videoanzeigen, spielbaren Anzeigen und Umfragen interagieren, Belohnungen in Form von In-App-Artikeln bieten.

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

Hinweis

Führen Sie zuerst folgende Schritte aus:

  • Richten Sie GMA Next-Gen SDK ein.
  • Verwenden Sie die Test-ID für Anzeigenblöcke für Anzeigen mit Prämie /21775744923/example/rewarded.
    • Verwenden Sie beim Entwickeln und Testen Ihrer App Testanzeigen anstelle von aktiven Anzeigen. Wenn Sie die Test-Anzeigenblock-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)

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

Das Vorabladen von Anzeigen bietet folgende Vorteile:

  • Referenzverwaltung: Referenzen werden bis zur Anzeigenschaltung beibehalten.
  • Automatisches Neuladen: Eine neue Anzeige wird geladen, wenn eine aus dem Cache abgerufen wird.
  • Verwaltete Wiederholungsversuche: Lädt eine neue Anzeige, 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.
Hinweis: Informationen zum manuellen Laden von Anzeigen finden Sie unter Einzelne Anzeige mit Prämie laden.

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, lädt GMA Next-Gen SDK Anzeigen automatisch vor und wiederholt fehlgeschlagene Anfragen für vorab geladene Konfigurationen.

Im folgenden Beispiel sehen Sie, wie Sie das Vorabladen von Anzeigen starten:

Kotlin

val adRequest = AdRequest.Builder(adUnitId).build()
val preloadConfig = PreloadConfiguration(adRequest)
RewardedAdPreloader.start(adUnitId, preloadConfig)

Java

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

Ersetzen Sie AD_UNIT_ID durch Ihre Anzeigenblock-ID.

Im vorherigen Beispiel wird gezeigt, wie die Anzeigenblock-ID als Preload-ID verwendet wird. Eine Preload-ID ist eine String-Kennung, 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-Kennung.

Vorab geladene Anzeige abrufen und einblenden

Wenn Sie eine Anzeige einblenden möchten, rufen Sie die Methode pollAd auf. GMA Next-Gen SDK ruft 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 Sie ein verfügbares Anzeigenobjekt haben, rufen Sie die Methode show auf, um die Anzeige einzublenden. Verwenden Sie einen Reward-Listener, um Reward-Events zu verarbeiten. Das folgende Beispiel zeigt, wie eine vorab geladene Anzeige abgerufen und präsentiert wird:

Kotlin

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

  // Interact with the ad object as needed.
  Log.d(TAG, "Rewarded ad response info: ${ad.getResponseInfo()}")
  ad.adEventCallback =
    object : RewardedAdEventCallback {
      override fun onAdImpression() {
        Log.d(TAG, "Rewarded 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 RewardedAd ad = RewardedAdPreloader.pollAd(adUnitId);

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

  Log.d(TAG, "Rewarded ad response info: " + ad.getResponseInfo());
  ad.setAdEventCallback(
      new RewardedAdEventCallback() {
        @Override
        public void onAdImpression() {
          Log.d(TAG, "Rewarded 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. Wenn Sie die Informationen zur Anzeigenantwort lesen möchten, ohne sie anzuzeigen, lesen Sie den Abschnitt Antwortinformationen lesen.

Auf Anzeigenereignisse warten

Vor der Auslieferung der Anzeige auf Ad-Events warten. Im folgenden Beispiel werden Callbacks für Anzeigenereignisse registriert:

Kotlin

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

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

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

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

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

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

Java

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

  rewardedAd.setAdEventCallback(
      new RewardedAdEventCallback() {
        @Override
        public void onAdShowedFullScreenContent() {
          // Rewarded ad did show.
        }

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

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

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

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

Optional: SSV-Callbacks (serverseitige Überprüfung) validieren

Wenn für Ihre App zusätzliche Daten in serverseitigen Überprüfungs-Callbacks erforderlich sind, verwenden Sie die Funktion für benutzerdefinierte Daten von Anzeigen. Google-Anzeigenserver übergeben jeden Stringwert, der für ein Anzeigenobjekt festgelegt ist, an den Abfrageparameter custom_data des SSV-Callbacks. Wenn kein benutzerdefinierter Datenwert festgelegt ist, ist der custom_data-Suchparameterwert nicht im SSV-Callback vorhanden.

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

Kotlin

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

Java

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

Ersetzen Sie SAMPLE_CUSTOM_DATA_STRING durch Ihre benutzerdefinierten Daten.

Optional: Auf Preloading-Ereignisse warten

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

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

Kotlin

val preloadCallback =
  object : PreloadCallback {
    override fun onAdFailedToPreload(preloadId: String, adError: LoadAdError) {
      Log.d(TAG, "Rewarded preload ad $preloadId failed to load with error: ${adError.message}")
    }

    override fun onAdsExhausted(preloadId: String) {
      Log.i(TAG, "Rewarded preload ad $preloadId is not available")
    }

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

Java

PreloadCallback preloadCallback =
    new PreloadCallback() {
      @Override
      public void onAdFailedToPreload(String preloadId, LoadAdError adError) {
        Log.d(
            TAG,
            String.format(
                "Rewarded preload ad %s failed to load with error: %s",
                preloadId, adError.getMessage()));
      }

      @Override
      public void onAdsExhausted(String preloadId) {
        Log.i(TAG, "Rewarded preload ad " + preloadId + " is not available");
      }

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

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

Wenn eine Anzeige nicht geladen werden kann, lädt GMA Next-Gen SDK automatisch Anzeigen vor und wiederholt fehlgeschlagene Anfragen für vorab geladene Konfigurationen.

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 RewardedAdPreloader.isAdAvailable(adUnitId)
}

Java

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

Optional: Puffergröße festlegen

Die Puffergröße steuert die Anzahl der vorab geladenen Anzeigen, die im Speicher gehalten werden. Standardmäßig optimiert Google die Puffergröße, um den Arbeitsspeicherverbrauch und die Latenz beim Ausliefern von Anzeigen auszugleichen. Sie können eine benutzerdefinierte Puffergröße festlegen, um die Anzahl der im Speicher behaltenen Anzeigen zu erhöhen. Wir empfehlen eine Puffergröße von zwei vorab geladenen Anzeigen.

Das folgende Beispiel zeigt, wie eine Puffergröße festgelegt wird:

Kotlin

val adRequest = AdRequest.Builder(adUnitId).build()
// Define a PreloadConfiguration and set the buffer size to 2 preloaded ads.
val preloadConfig = PreloadConfiguration(adRequest, bufferSize = 2)
RewardedAdPreloader.start(adUnitId, preloadConfig)

Java

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);
RewardedAdPreloader.start(adUnitId, preloadConfig);

Cache-Limits für das Vorladen

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

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

Optional: Vorabladen von Anzeigen beenden

Wenn Sie für eine bestimmte Preload-ID in der Sitzung keine Anzeigen mehr ausliefern müssen, können Sie das Preloading von Anzeigen beenden. Wenn Sie das Laden von Anzeigen für eine bestimmte Preload-ID beenden möchten, rufen Sie die Methode destroy mit einer Preload-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.
  RewardedAdPreloader.destroy(adUnitId)
}

Java

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

Optional: Antwortinformationen lesen

Die Antwortinformationen der nächsten vorab geladenen Anzeige lesen, ohne die Anzeige aus dem Cache zu entfernen.

Im folgenden Beispiel wird gezeigt, wie Sie die Informationen zur nächsten vorab geladenen Anzeigenantwort lesen:

Kotlin

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

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