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. Read some customer success stories: case study 1, case study 2.
Prerequisites
- Unity plugin 3.16.0 or higher.
- Complete the Get started guide.
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 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); } }
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.
...
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);
}
}
[Optional] Validate server-side verification (SSV) callbacks
Apps that require extra data in server-side verification
callbacks should use the custom data feature of rewarded ads. Any string value
set on a rewarded ad object is passed to the custom_data
query parameter of
the SSV callback. If no custom data value is set, the custom_data
query
parameter value won't be present in the SSV callback.
The following code sample demonstrates how to set the SSV options after the rewarded ad is loaded.
void HandleRewardedAdLoaded(RewardedAd ad, AdFailedToLoadEventArgs error)
{
// Create and pass the SSV options to the rewarded ad.
var options = new ServerSideVerificationOptions
.Builder()
.SetCustomData("SAMPLE_CUSTOM_DATA_STRING")
.Build()
ad.SetServerSideVerificationOptions(options);
}
If you want to set the custom reward string, you must do so before showing the ad.
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, 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); } }
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 providedAdErrorEventArgs
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 providedAdErrorEventArgs
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:
... 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.
...
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;
}
}
Samples
- HelloWorld example a minimal implementation of all ad formats