Skip to main content
Version: v1.0

Rewarded ads

Prerequisites​

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

import GoogleMobileAds
import UIKit

class ViewController: UIViewController {

  private var rewardedAd: GADRewardedAd?

  func loadRewardedAd() {
    let request = GAMRequest()
    GADRewardedAd.load(withAdUnitID:"/361045431/example/rewarded",
                       request: request,
                       completionHandler: { [self] ad, error in
      if let error = error {
        print("Failed to load rewarded ad with error: \(error.localizedDescription)")
        return
      }
      rewardedAd = ad
      print("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.

GADRewardedInterstitialAd.load(withAdUnitID:"/361045431/example/rewarded",
                       request: request,
                       completionHandler: { [self] ad, error in
      if let error != error {
      rewardedInterstitialAd = ad
      let options = GADServerSideVerificationOptions()
      options.customRewardString = "SAMPLE_CUSTOM_DATA_STRING"
      rewardedInterstitialAd.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 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:

class ViewController: UIViewController, GADFullScreenContentDelegate {

  private var rewardedAd: GADRewardedAd?

  func loadRewardedAd() {
    let request = GAMRequest()
    GADRewarded.load(withAdUnitID:"/361045431/example/rewarded",
                     request: request,
                     completionHandler: { [self] ad, error in
      if let error = error {
        print("Failed to load rewarded ad with error: \(error.localizedDescription)")
        return
      }
      rewardedAd = ad
      print("Rewarded ad loaded.")
      rewardedAd?.fullScreenContentDelegate = self
    }
    )
  }

  /// 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.")
  }
}

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.

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