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 iOS app.
Prerequisites
- Google Mobile Ads SDK 8.0.0 or higher.
- Complete the Get started guide.
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 iOS rewarded ads:
/21775744923/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.
Implementation
The primary steps to integrate rewarded ads are as follows:
- Load an ad
- [Optional] Validate SSV callbacks
- Register for callbacks
- Display the ad and handle the reward event
Load an ad
Loading an ad is accomplished using the load(adUnitID:request)
method on the GADRewardedAd
class.
Swift
import GoogleMobileAds
import UIKit
class ViewController: UIViewController {
private var rewardedAd: GADRewardedAd?
func loadRewardedAd() {
do {
rewardedAd = try await GADRewardedAd.load(
withAdUnitID: "/21775744923/example/rewarded", request: GAMRequest())
} catch {
print("Rewarded ad failed to load with error: \(error.localizedDescription)")
}
}
}
SwiftUI
import GoogleMobileAds
class RewardedViewModel: NSObject, ObservableObject, GADFullScreenContentDelegate {
@Published var coins = 0
private var rewardedAd: GADRewardedAd?
func loadAd() async {
do {
rewardedAd = try await GADRewardedAd.load(
withAdUnitID: "ca-app-pub-3940256099942544/1712485313", request: GADRequest())
rewardedAd?.fullScreenContentDelegate = self
} catch {
print("Failed to load rewarded ad with error: \(error.localizedDescription)")
}
}
Objective-C
@import GoogleMobileAds;
@import UIKit;
@interface ViewController ()
@property(nonatomic, strong) GADRewardedAd *rewardedAd;
@end
@implementation ViewController
- (void)loadRewardedAd {
GAMRequest *request = [GAMRequest request];
[GADRewardedAd
loadWithAdUnitID:@"/21775744923/example/rewarded"
request:request
completionHandler:^(GADRewardedAd *ad, NSError *error) {
if (error) {
NSLog(@"Rewarded ad failed to load with error: %@", [error localizedDescription]);
return;
}
self.rewardedAd = ad;
NSLog(@"Rewarded ad loaded.");
}];
}
[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 custom data on a rewarded ad object before requesting an ad.
Swift
do {
rewardedAd = try await GADRewardedAd.load(
withAdUnitID: "/21775744923/example/rewarded", request: GAMRequest())
let options = GADServerSideVerificationOptions()
options.customRewardString = "SAMPLE_CUSTOM_DATA_STRING"
rewardedAd.serverSideVerificationOptions = options
} catch {
print("Rewarded ad failed to load with error: \(error.localizedDescription)")
}
Objective-C
[GADRewardedAd
loadWithAdUnitID:@"/21775744923/example/rewarded"
request:[GAMRequest request];
completionHandler:^(GADRewardedAd *ad, NSError *error) {
if (error) {
// Handle Error
return;
}
self.rewardedAd = ad;
GADServerSideVerificationOptions *options =
[[GADServerSideVerificationOptions alloc] init];
options.customRewardString = @"SAMPLE_CUSTOM_DATA_STRING";
ad.serverSideVerificationOptions = options;
}];
Register for callbacks
In order to receive notifications for presentation events, you must implement
the GADFullScreenContentDelegate
protocol and assign it to the
fullScreenContentDelegate
property of the returned ad. The
GADFullScreenContentDelegate
protocol handles callbacks for when the ad
presents successfully or unsuccessfully, and when it is dismissed. The following
code shows how to implement the protocol and assign it to the ad:
Swift
import GoogleMobileAds
import UIKit
class ViewController: UIViewController, GADFullScreenContentDelegate {
private var rewardedAd: GADRewardedAd?
func loadRewardedAd() {
do {
rewardedAd = try await GADRewardedAd.load(
withAdUnitID: "/21775744923/example/rewarded", request: GAMRequest())
rewardedAd?.fullScreenContentDelegate = self
} catch {
print("Rewarded ad failed to load with error: \(error.localizedDescription)")
}
}
/// Tells the delegate that the ad failed to present full screen content.
func ad(_ ad: GADFullScreenPresentingAd, didFailToPresentFullScreenContentWithError error: Error) {
print("Ad did fail to present full screen content.")
}
/// Tells the delegate that the ad will present full screen content.
func adWillPresentFullScreenContent(_ ad: GADFullScreenPresentingAd) {
print("Ad will present full screen content.")
}
/// Tells the delegate that the ad dismissed full screen content.
func adDidDismissFullScreenContent(_ ad: GADFullScreenPresentingAd) {
print("Ad did dismiss full screen content.")
}
}
SwiftUI
Assign the fullScreenContentDelegate
property to the returned ad:
rewardedAd?.fullScreenContentDelegate = self
Implement the protocol:
func adDidRecordImpression(_ ad: GADFullScreenPresentingAd) {
print("\(#function) called")
}
func adDidRecordClick(_ ad: GADFullScreenPresentingAd) {
print("\(#function) called")
}
func ad(
_ ad: GADFullScreenPresentingAd,
didFailToPresentFullScreenContentWithError error: Error
) {
print("\(#function) called")
}
func adWillPresentFullScreenContent(_ ad: GADFullScreenPresentingAd) {
print("\(#function) called")
}
func adWillDismissFullScreenContent(_ ad: GADFullScreenPresentingAd) {
print("\(#function) called")
}
func adDidDismissFullScreenContent(_ ad: GADFullScreenPresentingAd) {
print("\(#function) called")
// Clear the rewarded ad.
rewardedAd = nil
}
Objective-C
@interface ViewController () <GADFullScreenContentDelegate>
@property(nonatomic, strong) GADRewardedAd *rewardedAd;
@end
@implementation ViewController
- (void)loadRewardedAd {
GAMRequest *request = [GAMRequest request];
[GADRewardedAd
loadWithAdUnitID:@"ca-app-pub-3940256099942544/4806952744"
request:request
completionHandler:^(GADRewardedAd *ad, NSError *error) {
if (error) {
NSLog(@"Rewarded ad failed to load with error: %@", [error localizedDescription]);
return;
}
self.rewardedAd = ad;
NSLog(@"Rewarded ad loaded.");
self.rewardedAd.fullScreenContentDelegate = self;
}];
}
/// Tells the delegate that the ad failed to present full screen content.
- (void)ad:(nonnull id<GADFullScreenPresentingAd>)ad
didFailToPresentFullScreenContentWithError:(nonnull NSError *)error {
NSLog(@"Ad did fail to present full screen content.");
}
/// Tells the delegate that the ad will present full screen content.
- (void)adWillPresentFullScreenContent:(nonnull id<GADFullScreenPresentingAd>)ad {
NSLog(@"Ad will present full screen content.");
}
/// Tells the delegate that the ad dismissed full screen content.
- (void)adDidDismissFullScreenContent:(nonnull id<GADFullScreenPresentingAd>)ad {
NSLog(@"Ad did dismiss full screen content.");
}
GADRewardedAd
is a one-time-use object. This means that once a rewarded ad is
shown, it cannot be shown again. A best practice is to load another rewarded ad
in the adDidDismissFullScreenContent:
method on GADFullScreenContentDelegate
so that the next rewarded ad starts loading as soon as the previous one is
dismissed.
Display the ad and handle the reward event
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.
When presenting your ad, you must provide a GADUserDidEarnRewardHandler
object
to handle the reward for the user.
The following code presents the best method for displaying a rewarded ad.
Swift
func show() {
guard let rewardedAd = rewardedAd else {
return print("Ad wasn't ready.")
}
// The UIViewController parameter is an optional.
ad.present(fromRootViewController: nil) {
let reward = ad.adReward
print("Reward received with currency \(reward.amount), amount \(reward.amount.doubleValue)")
// TODO: Reward the user.
}
}
SwiftUI
Listen to UI events in the view to determine when to show the ad.
var body: some View {
VStack(spacing: 20) {
Button("Watch video for additional 10 coins") {
viewModel.showAd()
showWatchVideoButton = false
}
Present the rewarded ad from the view model:
func showAd() {
guard let rewardedAd = rewardedAd else {
return print("Ad wasn't ready.")
}
rewardedAd.present(fromRootViewController: nil) {
let reward = rewardedAd.adReward
print("Reward amount: \(reward.amount)")
self.addCoins(reward.amount.intValue)
}
}
Objective-C
- (void)show {
if (self.rewardedAd) {
// The UIViewController parameter is nullable.
[self.rewardedAd presentFromRootViewController:nil
userDidEarnRewardHandler:^{
GADAdReward *reward =
self.rewardedAd.adReward;
// TODO: Reward the user!
}];
} else {
NSLog(@"Ad wasn't ready");
}
}
FAQ
- Can I get the reward details for the
GADRewardedAd
? - Yes, if you need the reward amount before the
userDidEarnReward
callback is fired,GADRewardedAd
has anadReward
property 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
GADInitializationCompletionHandler
provided to thestartWithCompletionHandler:
method, even if a mediation network still hasn't completed initialization. - What if some mediation networks aren't ready when I get the initialization callback?
We recommend loading an ad inside the
GADInitializationCompletionHandler
. Even if a mediation network is not ready, the Google Mobile Ads SDK still asks 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
GADMobileAds.initializationStatus
.- How do I find out why a particular mediation network isn't ready?
The
description
property of aGADAdapterStatus
object describes why an adapter is not ready to service ad requests.- Does the
userDidEarnRewardHandler
completion handler always get called before theadDidDismissFullScreenContent:
delegate method? For Google ads, all
userDidEarnRewardHandler
calls occur beforeadDidDismissFullScreenContent:
. For ads served through mediation, the third-party ad network SDK's implementation determines the callback order. For ad network SDKs that provide a single delegate method with reward information, the mediation adapter invokesuserDidEarnRewardHandler
beforeadDidDismissFullScreenContent:
.
Examples on GitHub
View the full rewarded ads examples in your preferred language:
Next steps
Learn more about user privacy.