Rewarded ads

Prerequisites

• Complete the Get started guide.

Implementation

The primary steps to integrate rewarded interstitial 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 static load(with:request:) (Swift) / loadWithAdUnitID:request:completionHandler: (Objective-C) method on the rewarded-ad class. The load method requires your ad unit ID, an ad-request object, and a completion handler which gets called when ad loading succeeds or fails. The loaded rewarded-ad object is provided as a parameter in the completion handler. The below example shows how to load a rewarded ad in your ViewController class.

In the current Google Mobile Ads SDK for iOS (12.x), the Swift API drops the GAD prefix: GADRewardedAd is exposed in Swift as RewardedAd, and GAMRequest as AdManagerRequest. The Objective-C class names remain unchanged.

Swift

import GoogleMobileAds
import UIKit

class ViewController: UIViewController {

  private var rewardedAd: RewardedAd?

  func loadRewardedAd() async {
    do {
      rewardedAd = try await RewardedAd.load(
        with: "/361045431/example/rewarded",
        request: AdManagerRequest())
      print("Rewarded ad loaded.")
    } 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:@"/361045431/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.");
      }];
}

For testing during development you can use Google's sample rewarded ad unit ID ca-app-pub-3940256099942544/1712485313.

[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 {
  let ad = try await RewardedInterstitialAd.load(
    with: "/361045431/example/rewarded",
    request: AdManagerRequest())
  let options = ServerSideVerificationOptions()
  options.customRewardString = "SAMPLE_CUSTOM_DATA_STRING"
  ad.serverSideVerificationOptions = options
  rewardedInterstitialAd = ad
} catch {
  // Handle error
}

Objective-C

GAMRequest *request = [GAMRequest request];
[GADRewardedInterstitialAd
     loadWithAdUnitID:@"/361045431/example/rewarded"
              request:request
    completionHandler:^(GADRewardedInterstitialAd *ad, NSError *error) {
      if (error) {
        // Handle Error
        return;
      }
      self.rewardedInterstitialAd = ad;
      GADServerSideVerificationOptions *options =
          [[GADServerSideVerificationOptions alloc] init];
      options.customRewardString = @"SAMPLE_CUSTOM_DATA_STRING";
      ad.serverSideVerificationOptions = options;
    }];

Key Point: The custom reward string is percent escaped and might require decoding when parsed from the SSV callback.

Register for callbacks

In order to receive notifications for presentation events, you must implement the full-screen content delegate protocol (FullScreenContentDelegate in Swift, GADFullScreenContentDelegate in Objective-C) and assign it to the fullScreenContentDelegate property of the returned ad. The 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

class ViewController: UIViewController, FullScreenContentDelegate {

  private var rewardedAd: RewardedAd?

  func loadRewardedAd() async {
    do {
      rewardedAd = try await RewardedAd.load(
        with: "/361045431/example/rewarded",
        request: AdManagerRequest())
      rewardedAd?.fullScreenContentDelegate = self
      print("Rewarded ad loaded.")
    } catch {
      print("Failed to load rewarded ad with error: \(error.localizedDescription)")
    }
  }

  /// Tells the delegate that the ad failed to present full screen content.
  func ad(_ ad: FullScreenPresentingAd, 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: FullScreenPresentingAd) {
    print("Ad will present full screen content.")
  }

  /// Tells the delegate that the ad dismissed full screen content.
  func adDidDismissFullScreenContent(_ ad: FullScreenPresentingAd) {
    print("Ad did dismiss full screen content.")
  }
}

Objective-C

@interface ViewController ()<GADFullScreenContentDelegate>

@property(nonatomic, strong) GADRewardedAd *rewardedAd;

@end

@implementation ViewController
- (void)loadRewardedAd {
  GAMRequest *request = [GAMRequest request];
  [GADRewardedAd
       loadWithAdUnitID:@"/361045431/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.");
        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.");
}

A rewarded-ad 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 callback 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 user-did-earn-reward handler to handle the reward for the user.

The following code presents the best method for displaying a rewarded ad.

Swift

func show() {
  guard let ad = rewardedAd else {
    print("Ad wasn't ready")
    return
  }
  ad.present(from: self) {
    let reward = ad.adReward
    print("Reward received with currency \(reward.type), amount \(reward.amount.doubleValue)")
    // TODO: Reward the user.
  }
}

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