Anzeigen mit Prämie

Anzeigen mit Prämie haben die Möglichkeit, mit Nutzern zu interagieren, um In-App-Prämien zu erhalten. In diesem Leitfaden wird erläutert, wie Sie AdMob-Anzeigen mit Prämie in eine Unity-App einbinden. Kundenerfolgsgeschichten: Fallstudie 1, Fallstudie 2

Für das Google Mobile Ads SDK wurden neue und verbesserte APIs für Anzeigen mit Prämie eingeführt. Die neue API mit Prämie ist eine Verbesserung gegenüber der alten API, weil sie nun

• Mehrere Anzeigen im Cache speichern Mit der alten Implementierung können Sie jeweils nur eine Anzeige laden und eine zweite Anzeige erst dann laden, wenn die erste Anzeige fertig ist. Mit den neuen APIs für Anzeigen mit Prämie können Sie mehrere Anzeigen gleichzeitig im Cache speichern.
• Sie können den Wert der Prämie während des Ladevorgangs abrufen. Die alte Implementierung bietet nur dann Zugriff auf die Prämie, wenn der Nutzer die Prämie erhält. Bei Apps, für die der Prämienwert über die AdMob-Benutzeroberfläche verwendet wird, können Sie Nutzern diese Prämie zeigen, bevor sie die Anzeige ansehen.
• Initialisierung der Vermittlungspartner. Wenn Sie die Vermittlung mit Prämie nutzen, wird die Initialisierung der Vermittlungsadapter durch die neuen APIs vor dem ersten Laden der Anzeige unterstützt. Die Legacy-API mit Prämie initialisiert keine Adapter. Bei den Vermittlungsadaptern ist außerdem die Wahrscheinlichkeit einer Zeitüberschreitung bei der ersten Anfrage einer Sitzung höher.

Vorbereitung

• Unity-Plug-in 3.16.0 oder höher
• Jetzt starten In Ihrer Unity-App sollte das Google Mobile Ads Unity-Plug-in bereits importiert sein.

Anzeigenobjekt mit Prämie erstellen

Anzeigen mit Prämie werden von RewardedAd-Objekten angefordert und ausgeliefert. Der erste Schritt, der zum Ausliefern einer Anzeige mit Prämie erforderlich ist, ist die Instanziierung eines RewardedAd-Objekts. Dazu wird der Konstruktor mit der Anzeigenblock-ID aufgerufen, die zum Laden der Anzeige verwendet werden soll. Das wird im folgenden Code-Snippet veranschaulicht:

Mit dem neuen Ad Placements-Beta lassen sich Anzeigen leichter mit dem Unity-Editor einbinden.

using UnityEngine.Events;
using UnityEngine;
using GoogleMobileAds.Api;
using GoogleMobileAds.Common;
using UnityEngine.UI;
using System;
using System.Collections.Generic;

public class GoogleMobileAdsDemoScript : MonoBehaviour
{
    private RewardedAd rewardedAd;
    ...

    public void Start()
    {
        ...

        this.rewardedAd = new RewardedAd(adUnitId);
    }
}

Immer mit Testanzeigen testen

Verwenden Sie beim Erstellen und Testen Ihrer Apps keine Testanzeigen, sondern Testanzeigen. Fehlen sie, kann Ihr Konto gesperrt werden.

Am einfachsten laden Sie Testanzeigen, indem Sie die entsprechenden Anzeigenblock-IDs für Android- und iOS-Anzeigen mit Prämie verwenden:

Android

ca-app-pub-3940256099942544/5224354917

iOS

ca-app-pub-3940256099942544/1712485313

Sie wurden speziell dafür entwickelt, für jede Anfrage Testanzeigen zurückzugeben. Außerdem können Sie sie beim Programmieren, Testen und Debuggen in Ihren eigenen Apps verwenden. Sie müssen sie nur durch Ihre eigene Anzeigenblock-ID ersetzen, bevor Sie Ihre App veröffentlichen.

Weitere Informationen zur Funktionsweise von Testanzeigen des Mobile Ads SDKs finden Sie unter Testanzeigen.

Anzeige laden

Um eine Anzeige mit Prämie zu laden, rufen Sie die loadAd()-Methode des RewardedAd-Objekts auf. Für diese Methode ist eine Instanz von AdRequest als Argument erforderlich.

...
public class GoogleMobileAdsDemoScript : MonoBehaviour
{
    private RewardedAd rewardedAd;
    ...

    public void Start()
    {
        ...

        this.rewardedAd = new RewardedAd(adUnitId);

        // Create an empty ad request.
        AdRequest request = new AdRequest.Builder().Build();
        // Load the rewarded ad with the request.
        this.rewardedAd.LoadAd(request);
    }
}

Anzeigenereignisse

Du kannst die Funktionsweise deiner Anzeige weiter anpassen, indem du verschiedene Ereignisse im Lebenszyklus der Anzeige nutzt: Laden, Öffnen, Schließen usw. Behalten Sie diese Ereignisse im Blick, indem Sie einen Bevollmächtigten für den entsprechenden Ereignis-Handler registrieren. Das wichtigste Ereignis ist OnUserEarnedReward. Es wird aufgerufen, wenn sich der Nutzer für das Ansehen eines Videos belohnt. Du kannst auch andere Anzeigenereignisse implementieren (siehe unten).

using GoogleMobileAds.Api;
...
public class GoogleMobileAdsDemoScript : MonoBehaviour
{
    private RewardedAd rewardedAd;
    ...

    public void Start()
    {
        string adUnitId;
        #if UNITY_ANDROID
            adUnitId = "ca-app-pub-3940256099942544/5224354917";
        #elif UNITY_IPHONE
            adUnitId = "ca-app-pub-3940256099942544/1712485313";
        #else
            adUnitId = "unexpected_platform";
        #endif

        this.rewardedAd = new RewardedAd(adUnitId);

        // Called when an ad request has successfully loaded.
        this.rewardedAd.OnAdLoaded += HandleRewardedAdLoaded;
        // Called when an ad request failed to load.
        this.rewardedAd.OnAdFailedToLoad += HandleRewardedAdFailedToLoad;
        // Called when an ad is shown.
        this.rewardedAd.OnAdOpening += HandleRewardedAdOpening;
        // Called when an ad request failed to show.
        this.rewardedAd.OnAdFailedToShow += HandleRewardedAdFailedToShow;
        // Called when the user should be rewarded for interacting with the ad.
        this.rewardedAd.OnUserEarnedReward += HandleUserEarnedReward;
        // Called when the ad is closed.
        this.rewardedAd.OnAdClosed += HandleRewardedAdClosed;

        // Create an empty ad request.
        AdRequest request = new AdRequest.Builder().Build();
        // Load the rewarded ad with the request.
        this.rewardedAd.LoadAd(request);
    }

    public void HandleRewardedAdLoaded(object sender, EventArgs args)
    {
        MonoBehaviour.print("HandleRewardedAdLoaded event received");
    }

    public void HandleRewardedAdFailedToLoad(object sender, AdFailedToLoadEventArgs args)
    {
        MonoBehaviour.print(
            "HandleRewardedAdFailedToLoad event received with message: "
                             + args.Message);
    }

    public void HandleRewardedAdOpening(object sender, EventArgs args)
    {
        MonoBehaviour.print("HandleRewardedAdOpening event received");
    }

    public void HandleRewardedAdFailedToShow(object sender, AdErrorEventArgs args)
    {
        MonoBehaviour.print(
            "HandleRewardedAdFailedToShow event received with message: "
                             + args.Message);
    }

    public void HandleRewardedAdClosed(object sender, EventArgs args)
    {
        MonoBehaviour.print("HandleRewardedAdClosed event received");
    }

    public void HandleUserEarnedReward(object sender, Reward args)
    {
        string type = args.Type;
        double amount = args.Amount;
        MonoBehaviour.print(
            "HandleRewardedAdRewarded event received for "
                        + amount.ToString() + " " + type);
    }
}

Das Ereignis OnUserEarnedReward bietet Argumente für besondere Ereignisse. Sie übergibt eine Instanz von Reward mit einer Type- und einer Amount-Anweisung, die dem Nutzer die Prämie beschreibt:

public void HandleUserEarnedReward(object sender, Reward args)
{
    string type = args.Type;
    double amount = args.Amount;
     MonoBehaviour.print(
          "HandleRewardedAdRewarded event received for "
              + amount.ToString() + " " + type);
}

Warnung:Es wird nicht empfohlen, eine neue Anzeige aus dem Block für den Abschluss einer Anzeigenanfrage zu laden, wenn keine Anzeige geladen werden konnte. Wenn Sie eine Anzeige aus dem Block der Anzeigenanfrage anfordern, müssen Sie die Anzahl der Wiederholungsversuche begrenzen, um Anzeigenanfragen mit unterschiedlichen Fehlern wie Netzwerkbeschränkungen zu vermeiden.

Verfügbare Anzeigenereignisse

OnAdLoaded

Wird aufgerufen, wenn eine Anzeige vollständig geladen wurde.

OnAdFailedToLoad

Wird aufgerufen, wenn eine Anzeige nicht geladen werden kann. Mit dem Attribut Message des bereitgestellten AdErrorEventArgs wird die Art des aufgetretenen Fehlers beschrieben.

OnAdOpening

Wird aufgerufen, wenn die Anzeige ausgeliefert wird und den Bildschirm des Geräts verdeckt Hier können Sie die Audioausgabe oder die Spielschleife Ihrer App pausieren.

OnAdFailedToShow

Wird aufgerufen, wenn eine Anzeige nicht ausgeliefert werden kann. Mit dem Attribut Message des bereitgestellten AdErrorEventArgs wird die Art des aufgetretenen Fehlers beschrieben.

OnUserEarnedReward

Wird aufgerufen, wenn ein Nutzer für das Ansehen eines Videos belohnt werden soll. Der Parameter Reward beschreibt die Prämie, die dem Nutzer angezeigt wird.

OnAdClosed

Wird aufgerufen, wenn die Videoanzeige mit Prämie geschlossen wird, weil der Nutzer auf das Symbol zum Schließen oder auf die Schaltfläche „Zurück“ tippt. Wenn deine App die Audioausgabe oder Spielschleife pausiert hat, ist dies eine gute Stelle, um sie fortzusetzen.

Anzeige einblenden

Bevor Nutzern Anzeigen mit Prämie präsentiert werden, müssen sie eine explizite Auswahl stellen, damit sie sich den Content mit Prämie ansehen können. Anzeigen mit Prämie müssen immer aktiviert werden.

Wenn du eine Anzeige mit Prämie sehen möchtest, kannst du mit der IsLoaded()-Methode prüfen, ob das Laden abgeschlossen wurde. Rufe dann show() auf. Hier ein Beispiel dafür:

private void UserChoseToWatchAd()
{
  if (this.rewardedAd.IsLoaded()) {
    this.rewardedAd.Show();
  }
}

Mit OnAdClosed die nächste Anzeige mit Prämie vorab laden

RewardedAd ist ein einmaliges Objekt. Wird eine Anzeige mit Prämie präsentiert, kann das Objekt also nicht zum Laden einer weiteren Anzeige verwendet werden. Wenn Sie eine weitere Anzeige mit Prämie anfordern möchten, müssen Sie ein neues RewardedAd-Objekt erstellen.

Als Best Practice wird empfohlen, eine andere Anzeige mit Prämie im Anzeigenereignis OnAdClosed zu laden, damit die nächste Anzeige mit Prämie geladen wird, sobald die vorherige Anzeige geschlossen wird:

...
public class GoogleMobileAdsDemoScript : MonoBehaviour
{
    private RewardedAd rewardedAd;
    ...

    public void CreateAndLoadRewardedAd()
    {
        #if UNITY_ANDROID
            string adUnitId = "ca-app-pub-3940256099942544/5224354917";
        #elif UNITY_IPHONE
            string adUnitId = "ca-app-pub-3940256099942544/1712485313";
        #else
            string adUnitId = "unexpected_platform";
        #endif

        this.rewardedAd = new RewardedAd(adUnitId);

        this.rewardedAd.OnAdLoaded += HandleRewardedAdLoaded;
        this.rewardedAd.OnUserEarnedReward += HandleUserEarnedReward;
        this.rewardedAd.OnAdClosed += HandleRewardedAdClosed;

        // Create an empty ad request.
        AdRequest request = new AdRequest.Builder().Build();
        // Load the rewarded ad with the request.
        this.rewardedAd.LoadAd(request);
    }

...

    public void HandleRewardedAdClosed(object sender, EventArgs args)
    {
        this.CreateAndLoadRewardedAd();
    }
}

Mehrere Anzeigen mit Prämie werden geladen

Wenn du mehrere Anzeigen mit Prämie laden möchtest, führe die Schritte in den Abschnitten Anzeigenobjekt mit Prämie erstellen und Anzeigen laden für jede Anzeige aus, die du laden möchtest. Das Code-Snippet unten zeigt, wie zwei Anzeigen mit Prämie für zwei verschiedene Anzeigen-Placements geladen werden.

...
public class GoogleMobileAdsDemoScript : MonoBehaviour
{
    private RewardedAd gameOverRewardedAd;
    private RewardedAd extraCoinsRewardedAd;
    ...
    public void Start()
    {
        ...

        this.gameOverRewardedAd = CreateAndLoadRewardedAd(adUnitId);
        this.extraCoinsRewardedAd = CreateAndLoadRewardedAd(adUnitId);
    }

    public RewardedAd CreateAndLoadRewardedAd(string adUnitId)
    {
        RewardedAd rewardedAd = new RewardedAd(adUnitId);

        rewardedAd.OnAdLoaded += HandleRewardedAdLoaded;
        rewardedAd.OnUserEarnedReward += HandleUserEarnedReward;
        rewardedAd.OnAdClosed += HandleRewardedAdClosed;

        // Create an empty ad request.
        AdRequest request = new AdRequest.Builder().Build();
        // Load the rewarded ad with the request.
        rewardedAd.LoadAd(request);
        return rewardedAd;
    }
}

Beispiele

• Beispiel für HelloWorld Mindestens eine Implementierung aller Anzeigenformate