Migration to the new Rewarded Ad API

In iOS SDK 7.41.0, the Mobile Ads SDK started offering a new rewarded ads API. As of 7.57.0, the legacy API is deprecated. This guide is intended to help publishers update to the new rewarded ads API.

Load ad

The legacy API used a singleton to load a rewarded ad whereas the new API lets you create multiple GADRewardedAd objects and call its load method.

Additionally, the new API lets you load multiple ads at once, which was not possible using the legacy GADRewardBasedVideoAd singleton. Refer to the Rewarded Ads guide for details on loading multiple ads.

Legacy API

Swift

GADRewardBasedVideoAd.sharedInstance().delegate = self
GADRewardBasedVideoAd.sharedInstance().load(GADRequest(),
    withAdUnitID: "ca-app-pub-3940256099942544/1712485313")
...

func rewardBasedVideoAdDidReceive(_ rewardBasedVideoAd:GADRewardBasedVideoAd) {
  // Ad successfully loaded.
}

func rewardBasedVideoAd(_ rewardBasedVideoAd: GADRewardBasedVideoAd,
                didFailToLoadWithError error: Error) {
  // Handle ad failed to load case.
}

Objective-C

[GADRewardBasedVideoAd sharedInstance].delegate = self;
[[GADRewardBasedVideoAd sharedInstance] loadRequest:[GADRequest request]
                                       withAdUnitID:@"ca-app-pub-3940256099942544/1712485313"];
...
- (void)rewardBasedVideoAdDidReceiveAd:(GADRewardBasedVideoAd *)rewardBasedVideoAd {
  NSLog(@"Reward based video ad is received.");
}
- (void)rewardBasedVideoAd:(GADRewardBasedVideoAd *)rewardBasedVideoAd
    didFailToLoadWithError:(NSError *)error {
  NSLog(@"Reward based video ad failed to load.");
}

New API

Swift

var rewardedAd: GADRewardedAd?
override func viewDidLoad() {
  super.viewDidLoad()
  rewardedAd = GADRewardedAd(adUnitID: "ca-app-pub-3940256099942544/1712485313")
  rewardedAd?.load(GADRequest()) { error in
    if let error = error {
      // Handle ad failed to load case.
    } else {
      // Ad successfully loaded.
    }
  }
}

Objective-C

...
  self.rewardedAd = [[GADRewardedAd alloc]
      initWithAdUnitID:@"ca-app-pub-3940256099942544/1712485313"];

  GADRequest *request = [GADRequest request];
  [self.rewardedAd loadRequest:request completionHandler:^(GADRequestError * _Nullable error) {
    if (error) {
      // Handle ad failed to load case.
    } else {
      // Ad successfully loaded.
    }
  }];
...

Display ad

Displaying an ad with the new API is very similar to the legacy API. The major difference is the new API no longer uses a singleton.

Legacy API

Swift

if GADRewardBasedVideoAd.sharedInstance().isReady == true {
  GADRewardBasedVideoAd.sharedInstance().present(fromRootViewController: self)
}

Objective-C

if ([[GADRewardBasedVideoAd sharedInstance] isReady]) {
  [[GADRewardBasedVideoAd sharedInstance] presentFromRootViewController:self];
}

New API

Swift

if rewardedAd?.isReady == true {
   rewardedAd?.present(fromRootViewController: self, delegate:self)
}

Objective-C

if (self.rewardedAd.isReady) {
  [self.rewardedAd presentFromRootViewController:self delegate:self];
} else {
  NSLog(@"Ad wasn't ready");
}

The legacy API had presentation events in the same delegate as loaded events. With the new API, you provide a delegate for presentation events into the presentFromRootViewController:delegate: method.

Handle ad events

The GADRewardBasedVideoAdDelegate protocol is deprecated in favor of the GADRewardedAdDelegate protocol.

Presentation callbacks

The new rewarded API introduces a callback for presentation failures. Additionally, the new API removes the rewardBasedVideoAdWillLeaveApplication: callback because iOS already has the applicationWillResignActive: method to notify you when your app is about to become inactive.

Legacy API

Swift

func rewardBasedVideoAdDidOpen(_ rewardBasedVideoAd: GADRewardBasedVideoAd) {
  print("Opened reward based video ad.")
}

Objective-C

- (void)rewardBasedVideoAdDidOpen:(GADRewardBasedVideoAd *)rewardBasedVideoAd {
  NSLog(@"Opened reward based video ad.");
}

New API

Swift

func rewardedAdDidPresent(_ rewardedAd: GADRewardedAd) {
  print("Rewarded ad presented.")
}

func rewardedAd(_ rewardedAd: GADRewardedAd, didFailToPresentWithError error: Error) {
  print("Rewarded ad failed to present.")
}

Objective-C

- (void)rewardedAdDidPresent:(GADRewardedAd *)rewardedAd {
  NSLog(@"rewardedAdDidPresent:");
}

- (void)rewardedAd:(GADRewardedAd *)rewardedAd didFailToPresentWithError:(NSError *)error {
  NSLog(@"rewardedAd:didFailToPresentWithError");
}

Dismissal events

The rewarded dismiss callback maps 1:1 to the new rewarded API.

Legacy API

Swift

func rewardBasedVideoAdDidClose(_ rewardBasedVideoAd: GADRewardBasedVideoAd) {
  print("Reward based video ad is closed.")
}

Objective-C

- (void)rewardBasedVideoAdDidClose:(GADRewardBasedVideoAd *)rewardBasedVideoAd {
  NSLog(@"Reward based video ad is closed.");
}

New API

Swift

func rewardedAdDidDismiss(_ rewardedAd: GADRewardedAd) {
  print("Rewarded ad dismissed.")
}

Objective-C

- (void)rewardedAdDidDismiss:(GADRewardedAd *)rewardedAd {
  NSLog(@"rewardedAdDidDismiss:");
}

Reward events

The reward callack maps 1:1 to the new rewarded API.

Legacy API

Swift

func rewardBasedVideoAd(_ rewardBasedVideoAd: GADRewardBasedVideoAd,
    didRewardUserWith reward: GADAdReward) {
  print("Reward received with currency: \(reward.type), amount \(reward.amount).")
}

Objective-C

- (void)rewardBasedVideoAd:(GADRewardBasedVideoAd *)rewardBasedVideoAd
    didRewardUserWithReward:(GADAdReward *)reward {
  NSString *rewardMessage =
      [NSString stringWithFormat:@"Reward received with currency %@ , amount %lf",
          reward.type,
          [reward.amount doubleValue]];
  NSLog(rewardMessage);
}

New API

Swift

func rewardedAd(_ rewardedAd: GADRewardedAd, userDidEarn reward: GADAdReward) {
  print("Reward received with currency: \(reward.type), amount \(reward.amount).")
}

Objective-C

- (void)rewardedAd:(GADRewardedAd *)rewardedAd userDidEarnReward:(GADAdReward *)reward {
  // TODO: Reward the user.
  NSLog(@"rewardedAd:userDidEarnReward:");
}

The new API also allows you to get a reference to the reward object anytime after it's been granted by using the reward property on GADRewardedAd.

Mediation Adapters

If you're using mediation, make sure you're using an adapter version greater than or equal to the minimum required for the new Rewarded API. The list of minimum adapter versions is as follows:

Network Minimum adapter version
AdColony 3.3.7.0
AppLovin 6.3.0.0
Chartboost 7.5.0.0
Facebook Audience Network 5.2.0.1
InMobi 7.2.7.0
ironSource 6.8.0.1
maio 1.4.6.0
MoPub 5.6.0.1
myTarget 5.0.4.0
nend 5.1.1.0
Tapjoy 12.2.1.0
Unity 3.0.0.3
Vungle 6.3.2.1