Rewarded Ads

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

The new rewarded API is an improvement over the legacy API because it allows you to

• Cache multiple ads. The legacy rewarded API only lets you load one ad at a time, and you can't load a second ad until the first one finishes. The new rewarded API lets you cache multiple ads at the same time.
• Access the reward value at ad load time. The legacy implementation only provides access to the reward when it's time to grant the user the reward. For apps that use the reward value from the Ad Manager UI, this improvement enables you to show the user their reward before they watch the ad.

Migrating from the legacy rewarded API? Make sure to update your mediation adapters to the latest version, as the adapters had to migrate as well.

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.

 Demo

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:

Java

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,
            "/6499/example/rewarded-video");
    }

}

Kotlin

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

class MainActivity : Activity() {

  private lateinit var rewardedAd: RewardedAd

  override fun onCreate(savedInstanceState:Bundle) {
    ...
    rewardedAd = RewardedAd(this,
        "/6499/example/rewarded-video")
  }
}

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:

/6499/example/rewarded-video

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

Note: Make all calls to the Mobile Ads SDK on the main thread.

To load a rewarded ad, call the RewardedAd object's loadAd() method. This method requires instances of PublisherAdRequest and RewardedAdLoadCallback as arguments.

Java

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,
            "/6499/example/rewarded-video");

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

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

Kotlin

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

class MainActivity : Activity() {

  private val rewardedAd: RewardedAd

  override fun onCreate(savedInstanceState:Bundle) {
    rewardedAd = RewardedAd(this, "/6499/example/rewarded-video")
    val adLoadCallback = object: RewardedAdLoadCallback() {
      fun onRewardedAdLoaded() {
        // Ad successfully loaded.
      }
      fun onRewardedAdFailedToLoad(errorCode: Int) {
        // Ad failed to load.
      }
    }
    rewardedAd.loadAd(PublisherAdRequest.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 PublisherAdRequest 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.

Warning: Attempting to load a new ad from the onRewardedAdFailedToLoad() method is strongly discouraged. If you must load an ad from onRewardedAdFailedToLoad(), limit ad load retries to avoid continuous failed ad requests in situations such as limited network connectivity.

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:

Java

myButton.setOnClickListener(new View.OnClickListener() {
    @Override
    public void onClick(View v) {
        if (rewardedAd.isLoaded()) {
            Activity activityContext = MainActivity.this
            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.");
        }
    }
});

Kotlin

myButton.setOnClickListener {
  if (rewardedAd.isLoaded) {
    val activityContext: Activity = this@MainActivity
    val adCallback = object: RewardedAdCallback() {
      override fun onRewardedAdOpened() {
        // Ad opened.
      }
      override fun onRewardedAdClosed() {
        // Ad closed.
      }
      override fun onUserEarnedReward(@NonNull reward: RewardItem) {
        // User earned reward.
      }
      override fun onRewardedAdFailedToShow(errorCode: Int) {
        // 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:

Java

public RewardedAd createAndLoadRewardedAd() {
        RewardedAd rewardedAd = new RewardedAd(this,
                "/6499/example/rewarded-video");
        RewardedAdLoadCallback adLoadCallback = new RewardedAdLoadCallback() {
            @Override
            public void onRewardedAdLoaded() {
                // Ad successfully loaded.
            }

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

@Override
public void onRewardedAdClosed() {
    this.rewardedAd = createAndLoadRewardedAd();
}

Kotlin

fun createAndLoadRewardedAd(): RewardedAd {
  val rewardedAd = RewardedAd(this, "/6499/example/rewarded-video")
  val adLoadCallback = object: RewardedAdLoadCallback() {
    override fun onRewardedAdLoaded() {
      // Ad successfully loaded.
    }
    override fun onRewardedAdFailedToLoad(errorCode: Int) {
      // Ad failed to load.
    }
  }
  rewardedAd.loadAd(PublisherAdRequest.Builder().build(), adLoadCallback)
  return rewardedAd
}
fun 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.

Java

package ...

import com.google.android.gms.ads.PublisherAdRequest;
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(
          "/6499/example/rewarded-video");
        extraCoinsRewardedAd = createAndLoadRewardedAd(
          "/6499/example/rewarded-video");
    }

    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 PublisherAdRequest.Builder().build(), adLoadCallback);
        return rewardedAd;
    }
}

Kotlin

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

class MainActivity: Activity() {

  private val gameOverRewardedAd:RewardedAd
  private val extraCoinsRewardedAd:RewardedAd

  override fun onCreate(savedInstanceState:Bundle) {
    ...
    gameOverRewardedAd = createAndLoadRewardedAd(
      "/6499/example/rewarded-video")
    extraCoinsRewardedAd = createAndLoadRewardedAd(
      "/6499/example/rewarded-video")
  }

  fun createAndLoadRewardedAd(adUnitId:String): RewardedAd {
    val rewardedAd = RewardedAd(this, adUnitId)
    val adLoadCallback = object: RewardedAdLoadCallback() {
      overrride fun onRewardedAdLoaded() {
        // Ad successfully loaded.
      }
      overrride fun onRewardedAdFailedToLoad(errorCode: Int) {
        // Ad failed to load.
      }
    }
    rewardedAd.loadAd(PublisherAdRequest.Builder().build(), adLoadCallback)
    return rewardedAd
  }
}

Next steps

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

• Try another ad format:

  • Interstitial
  • Banner