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 die folgenden Schritte aus, bevor Sie fortfahren:

  • Richten Sie GMA Next-Gen SDK ein.
  • Verwenden Sie die Test-Anzeigenblock-ID für Anzeigen mit Prämie ca-app-pub-3940256099942544/5224354917.
    • 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 ausgeliefert 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

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 Sie die Anzeigenblock-ID als Vorabladungs-ID verwenden. Eine Vorabladungs-ID ist eine String-Kennung, die 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 eine benutzerdefinierte String-Kennung.

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 Anzeige abrufen und ausliefern

Rufen Sie vor dem Ausliefern 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 auszuliefern. Verwenden Sie einen Listener für Prämien, um Prämienereignisse zu verarbeiten. Das folgende Beispiel zeigt, wie Sie eine vorab geladene Anzeige abrufen und ausliefern:

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

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 Vorabladungs-Callbacks 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 ausliefern, lesen Sie die Antwortinformationen, ohne die Anzeige aus dem Cache zu entfernen.

Auf Anzeigenereignisse warten

Warten Sie vor dem Ausliefern der Anzeige auf Anzeigenereignisse. 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: Serverseitige Überprüfung (SSV) von Callbacks validieren

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

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

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

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.

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

Optional: Auf Vorabladungsereignisse warten

Wenn Sie mit dem Vorabladen von Anzeigen beginnen, registrieren Sie sich für Vorabladungsereignisse, 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 Anzeigenereignisse zum Vorabladen 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 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 Fehler-Callbacks keine manuellen Ladeanfragen auf. Rufen Sie in Callback-Methoden für Vorabladungsereignisse nicht die Methoden pollAd, destroy oder start auf. Wenn Sie diese Methoden in Callbacks aufrufen, können rekursive Ladeschleifen ausgelöst werden.

Optional: Anzeigenverfügbarkeit prüfen

Wenn Sie wissen müssen, 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 Arbeitsspeicher gespeichert werden. Standardmäßig optimiert Google die Puffergröße, um den Arbeitsspeicherverbrauch und die Latenz bei der Anzeigenauslieferung 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, reduzieren Sie die Puffergröße.

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

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

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

Java

private void stopPreloading(String adUnitId) {
  // Stops the preloading and destroy preloaded ads.
  RewardedAdPreloader.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 ausliefern, 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 = 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());