Rewarded Ads - New APIs (Beta)

Rewarded ads are ads that users have the option of interacting with in exchange for in-app rewards. This guide shows you how to integrate rewarded ads from AdMob into a Unity app.

Prerequisites

  • Unity plugin 3.16.0 or higher.
  • Complete Get Started. Your Unity app should already have the Google Mobile Ads Unity plugin imported.

Create a rewarded ad object

Rewarded ads are requested and shown by RewardedAd objects. The first step required to show a rewarded ad is to instantiate a RewardedAd object by invoking the constructor with the ad unit ID to be used to load the ad. This is demonstrated in the following code snippet:

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

    public void Start()
    {
        ...

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

Always test with test ads

When building and testing your apps, make sure you use test ads rather than live, production ads. Failure to do so can lead to suspension of your account.

The easiest way to load test ads is to use our dedicated test ad unit IDs for Android and iOS rewarded ads:

Android

ca-app-pub-3940256099942544/5224354917

iOS

ca-app-pub-3940256099942544/1712485313

They have been specially configured to return test ads for every request, and you're free to use them in your own apps while coding, testing, and debugging. Just make sure you replace them with your own ad unit ID before publishing your app.

For more information about how the Mobile Ads SDK's test ads work, see Test Ads.

Load an ad

To load a rewarded ad, call the RewardedAd object's loadAd() method. This method requires an instance of AdRequest as an argument.

using GoogleMobileAds.Api;
...
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);
    }
}

Ad events

To further customize the behavior of your ad, you can hook into a number of events in the ad's lifecycle: loading, opening, closing, and so on. Listen for these events by registering a delegate for the appropriate event handler. The most important event is OnUserEarnedReward, which is called when the user is rewarded for watching a video. You can also implement other ad events, as shown below.

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, AdErrorEventArgs 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);
    }
}

The OnUserEarnedReward event provides special event arguments. It passes an instance of Reward with a Type and Amount describing the reward given to the user:

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

Available ad events

OnAdLoaded
Invoked when an ad has finished loading.
OnAdFailedToLoad
Invoked when an ad fails to load. The Message property of the provided AdErrorEventArgs describes the type of failure that occurred.
OnAdOpening
Invoked when the ad is displayed, covering the device's screen. This is a good place to pause your app audio output or game loop, if necessary.
OnAdFailedToShow
Invoked when an ad fails to display. The Message property of the provided AdErrorEventArgs describes the type of failure that occurred.
OnUserEarnedReward
Invoked when a user should be rewarded for watching a video. The Reward parameter describes the reward to be presented to the user.
OnAdClosed
Invoked when the rewarded video ad is closed due to the user tapping on the close icon or using the back button. If your app paused its audio output or game loop, this is a great place to resume it.

Show the ad

Before displaying a rewarded ad to users, they must be presented with an explicit choice to view rewarded ad content in exchange for a reward. Rewarded ads must always be an opt-in experience.

To show a rewarded ad, check the IsLoaded() method to verify that it's finished loading, then call show(). Here's an example of how to do this:

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

Using OnAdClosed to preload the next rewarded ad

RewardedAd is a one-time-use object. This means once a rewarded ad is shown, the object can't be used to load another ad. To request another rewarded ad, you'll need to create a new RewardedAd object.

A best practice is to load another rewarded ad in the OnAdClosed ad event so that the next rewarded ad starts loading as soon as the previous one is dismissed:

using GoogleMobileAds.Api;
...
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();
    }
}

Loading multiple rewarded ads

To load multiple rewarded ads, follow the steps outlined in the create a rewarded ad object and load an ad sections for each ad you intend to load. The code snippet below demonstrates how to load two rewarded ads for two distinct ad placements.

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

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

    public void CreateAndLoadRewardedAd(string adUnitId)
    {
        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);
    }
}

Additional resources

Samples

Next steps

Visszajelzés küldése a következővel kapcsolatban:

Segítségre van szüksége? Keresse fel súgóoldalunkat.