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 an Android app.

If you'd like to get an idea of how rewarded ads work, take a look at the demo below. This demo shows the flow of rewarded video ads integrated in to a simple game.

Prerequisites

  • Google Mobile Ads SDK 17.2.0 or higher.
  • Follow the Get Started guide to import the Google Mobile Ads SDK and update your Android manifest.

Create a rewarded ad object

Rewarded ads are requested and shown by RewardedAd objects. The first step is instantiating a RewardedAd. This is done in the onCreate() method of an Activity in the following code snippet:

import com.google.android.gms.ads.rewarded.RewardedAd;

public class MainActivity extends Activity {

    private RewardedAd rewardedAd;

    @Override
    protected void onCreate(Bundle savedInstanceState) {
        ...
        rewardedAd = new RewardedAd(this,
            "ca-app-pub-3940256099942544/5224354917");
    }

}

The constructor requires the following arguments:

  • An Activity context
  • The ad unit ID to be used to load the rewarded ad

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 ID for Android rewarded ads:

ca-app-pub-3940256099942544/5224354917

It's been specially configured to return test ads for every request, and you're free to use it in your own apps while coding, testing, and debugging. Just make sure you replace it 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 instances of AdRequest and RewardedAdLoadCallback as arguments.

import com.google.android.gms.ads.rewarded.RewardedAd;

public class MainActivity extends Activity {

    private RewardedAd rewardedAd;

    @Override
    protected void onCreate(Bundle savedInstanceState) {
        ...
        rewardedAd = new RewardedAd(this,
            "ca-app-pub-3940256099942544/5224354917");

        RewardedAdLoadCallback adLoadCallback = new RewardedAdLoadCallback() {
            @Override
            public void onRewardedAdLoaded() {
                // Ad successfully loaded.
            }

           @Override
            public void onRewardedAdFailedToLoad(int errorCode) {
                // Ad failed to load.
            }
        };
        rewardedAd.loadAd(new AdRequest.Builder().build(), adLoadCallback);
    }
}

The onRewardedAdLoaded() and onRewardedAdFailedToLoad() methods of the RewardedAdLoadCallback provide the result of the ad load operation.

Overridable methods
onRewardedAdLoaded() This method is executed when an ad has finished loading.
onRewardedAdFailedToLoad() This method is invoked when an ad fails to load. It includes an errorCode parameter that indicates what type of failure occurred. The possible values are defined as constants in the AdRequest class:
  • ERROR_CODE_INTERNAL_ERROR - Something happened internally; for instance, an invalid response was received from the ad server.
  • ERROR_CODE_INVALID_REQUEST - The ad request was invalid; for instance, the ad unit ID was incorrect.
  • ERROR_CODE_NETWORK_ERROR - The ad request was unsuccessful due to network connectivity.
  • ERROR_CODE_NO_FILL - The ad request was successful, but no ad was returned due to lack of ad inventory.

Show the ad

Before displaying a rewarded ad to users, you must present the user 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 RewardedAd, use the isLoaded() method to verify that it's finished loading, then call show(). The show() method requires Activity and RewardedAdCallback instances as arguments. The Activity instance should be the activity from which the rewarded ad is presented.

The rewarded ad from the previous code example could be shown in a button's OnClickListener like this:

myButton.setOnClickListener(new View.OnClickListener() {
    @Override
    public void onClick(View v) {
        if (rewardedAd.isLoaded()) {
            Activity activityContext = ...;
            RewardedAdCallback adCallback = new RewardedAdCallback() {
                @Override
                public void onRewardedAdOpened() {
                    // Ad opened.
                }

                @Override
                public void onRewardedAdClosed() {
                    // Ad closed.
                }

                @Override
                public void onUserEarnedReward(@NonNull RewardItem reward) {
                    // User earned reward.
                }

                @Override
                public void onRewardedAdFailedToShow(int errorCode) {
                    // Ad failed to display
                }
            };
            rewardedAd.show(activityContext, adCallback);
        } else {
            Log.d("TAG", "The rewarded ad wasn't loaded yet.");
        }
    }
});

Receive ad event notifications

The RewardedAdCallback provided to the show() method gets notifications of rewarded ad events. Each of the overridable methods in RewardedAdCallback corresponds to an event in the lifecycle of a rewarded ad. For example, the onUserEarnedReward() method is the perfect place to provide the user with their reward. Additional details on each ad event method is provided below.

Overridable methods
onRewardedAdOpened() This method is invoked when the ad is displayed, covering the device's screen.
onRewardedAdClosed() This method is invoked when the rewarded 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.
onUserEarnedReward() The method is invoked when the user should be rewarded for interacting with the ad. Reward details that were configured for your ad unit can be accessed through the getType() and getAmount() methods of the RewardItem parameter.
onRewardedAdFailedToShow() This method is invoked when an ad fails to display. It includes an errorCode parameter that indicates what type of failure occurred. The possible values are defined as constants in the RewardedAdCallback class:
  • ERROR_CODE_INTERNAL_ERROR - Something happened internally.
  • ERROR_CODE_AD_REUSED - The rewarded ad has already been shown. RewardedAd objects are one-time use objects and can only be shown once. Instantiate and load a new RewardedAd to display a new ad.
  • ERROR_CODE_NOT_READY - The ad has not been successfully loaded.
  • ERROR_CODE_APP_NOT_FOREGROUND - The ad can not be shown when the app is not in foreground.

Using RewardedAdCallback to preload the next rewarded ad

RewardedAd is a one-time-use object. This means that 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 onRewardedAdClosed() method on RewardedAdCallback so that the next rewarded ad starts loading as soon as the previous one is dismissed:

public RewardedAd createAndLoadRewardedAd() {
        RewardedAd rewardedAd = new RewardedAd(this,
                "ca-app-pub-3940256099942544/5224354917");
        RewardedAdLoadCallback adLoadCallback = new RewardedAdLoadCallback() {
            @Override
            public void onRewardedAdLoaded() {
                // Ad successfully loaded.
            }

            @Override
            public void onRewardedAdFailedToLoad(int errorCode) {
                // Ad failed to load.
            }
        };
        rewardedAd.loadAd(new AdRequest.Builder().build(), adLoadCallback);
        return rewardedAd;
}

@Override
public void onRewardedAdClosed() {
    this.rewardedAd = 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.

package ...

import com.google.android.gms.ads.AdRequest;
import com.google.android.gms.ads.rewarded.RewardedAd;

public class MainActivity extends Activity {

    private RewardedAd gameOverRewardedAd;
    private RewardedAd extraCoinsRewardedAd;

    @Override
    protected void onCreate(Bundle savedInstanceState) {
        ...
        gameOverRewardedAd = createAndLoadRewardedAd(
          "ca-app-pub-3940256099942544/5224354917");
        extraCoinsRewardedAd = createAndLoadRewardedAd(
          "ca-app-pub-3940256099942544/5224354917");
    }

    public RewardedAd createAndLoadRewardedAd(String adUnitId) {
        RewardedAd rewardedAd = new RewardedAd(this, adUnitId);
        RewardedAdLoadCallback adLoadCallback = new RewardedAdLoadCallback() {
            @Override
            public void onRewardedAdLoaded() {
                // Ad successfully loaded.
            }

            @Override
            public void onRewardedAdFailedToLoad(int errorCode) {
                // Ad failed to load.
            }
        };
        rewardedAd.loadAd(new AdRequest.Builder().build(), adLoadCallback);
        return rewardedAd;
    }
}

FAQ

Can I get the reward details for the RewardedAd?
Yes, if you need the reward amount before the onUserEarnedReward() callback is fired, RewardedAd has a getRewardItem() method that you can check to verify the reward amount after the ad has loaded.
Is there a timeout for the initialization call?
After 10 seconds, the Google Mobile Ads SDK invokes the OnInitializationCompleteListener even if a mediation network still hasn't completed initialization.
What if some mediation networks aren't ready when I get the initialization callback?

It is a best practice to load an ad inside the callback of the OnInitializationCompleteListener. Even if a mediation network is not ready, the Google Mobile Ads SDK will still ask that network for an ad. So if a mediation network finishes initializing after the timeout, it can still service future ad requests in that session.

You can continue to poll the initialization status of all adapters throughout your app session by calling MobileAds.getInitializationStatus().

How do I find out why a particular mediation network isn't ready?

AdapterStatus.getDescription() describes why an adapter is not ready to service ad requests.

Next steps

  • Create your own rewarded video ad unit in the AdMob UI.

  • Try another ad format:

Send feedback about...

Need help? Visit our support page.