Rewarded (legacy API)

Warning: This guide covers the rewarded API as it existed prior to 19.7.0. Please read the migration guide for more details on the changes introduced in version 19.7.0 and finalized in 20.0.0.

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

}

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")
  }
}

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

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

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

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

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")
    val adLoadCallback = object: RewardedAdLoadCallback() {
      fun onRewardedAdLoaded() {
        // Ad successfully loaded.
      }
      fun onRewardedAdFailedToLoad(adError: LoadAdError) {
        // 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 error parameter of type LoadAdError that indicates what type of failure occurred. For more information, refer to the Debugging Ad Load Errors documentation.

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(AdError adError) {
                    // 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(adError: AdError) {
        // 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 adError parameter that indicates what type of failure occurred. The possible values of the error code (adError.getCode()) are defined as constants in the RewardedAdCallback class.

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");
        RewardedAdLoadCallback adLoadCallback = new RewardedAdLoadCallback() {
            @Override
            public void onRewardedAdLoaded() {
                // Ad successfully loaded.
            }

            @Override
            public void onRewardedAdFailedToLoad(LoadAdError adError) {
                // 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")
  val adLoadCallback = object: RewardedAdLoadCallback() {
    override fun onRewardedAdLoaded() {
      // Ad successfully loaded.
    }
    override fun onRewardedAdFailedToLoad(adError: LoadAdError) {
      // 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");
        extraCoinsRewardedAd = createAndLoadRewardedAd(
          "/6499/example/rewarded");
    }

    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(LoadAdError adError) {
                // 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 lateinit var gameOverRewardedAd: RewardedAd
  private lateinit var extraCoinsRewardedAd: RewardedAd

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

  fun createAndLoadRewardedAd(adUnitId:String): RewardedAd {
    val rewardedAd = RewardedAd(this, adUnitId)
    val adLoadCallback = object: RewardedAdLoadCallback() {
      override fun onRewardedAdLoaded() {
        // Ad successfully loaded.
      }
      override fun onRewardedAdFailedToLoad(adError: LoadAdError) {
        // 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