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 iOS app.

Prerequisites

  • Google Mobile Ads SDK 8.0.0 or higher
  • Follow the Get Started guide to import the Google Mobile Ads SDK.

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:

/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.

Implementation

The main steps to integrate rewarded ads are:

  1. Load an ad.
  2. Register for callbacks.
  3. Display the ad and handle the reward event.

Load an ad

Loading an ad is accomplished using the static loadWithAdUnitID:request:completionHandler: method on the GADRewardedAd class. The load method requires your ad unit ID, a GAMRequest object, and a completion handler which gets called when ad loading succeeds or fails. The loaded GADRewardedAd object is provided as a parameter in the completion handler. The below example shows how to load a GADRewardedAd in your ViewController class.

Objective-C

@import GoogleMobileAds;
@import UIKit;

@interface ViewController ()

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

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:

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 presented full screen content.
- (void)adDidPresentFullScreenContent:(nonnull id<GADFullScreenPresentingAd>)ad {
    NSLog(@"Ad did 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.

Objective-C

- (void)show {
  ...
  if (self.rewardedAd) {
    [self.rewardedAd presentFromRootViewController:self
                                  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 an adReward 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 the startWithCompletionHandler: 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?

It's a best practice to load an ad inside a GADInitializationCompletionHandler. 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 GADMobileAds.initializationStatus.

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

The description property of a GADAdapterStatus object describes why an adapter is not ready to service ad requests.