Rewarded Ads - New APIs (Beta)

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 AdMob into an iOS app.

Prerequisites

Initialize mobile ads

Before loading ads, have your app initialize the Mobile Ads SDK by calling startWithCompletionHandler: with a GADInitializationCompletionHandler. This needs to be done only once, ideally at app launch.

@import GoogleMobileAds;
...
@implementation AppDelegate

- (BOOL)application:(UIApplication *)application
    didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {

  // Initialize Google Mobile Ads SDK
  [[GADMobileAds sharedInstance]
      startWithCompletionHandler:^(GADInitializationStatus *_Nonnull status){
          // TODO: Load an ad. Optionally check initialization status.
      }];

  return YES;
}

@end

If your app uses mediation, this call will also initialize your mediation partners' SDKs.

Upon initialization completion, the provided GADInitializationCompletionHandler is executed and the GADInitializationStatus argument is a immutable snapshot of the Google Mobile Ads SDK's initialization status.

The adapterStatusesByClassName property on a GADInitializationStatus object provides the initialization status of each mediation ad network available to the Google Mobile Ads SDK, keyed by the adapter class name. The code below initializes the Google Mobile Ads SDK and checks the initialization state of the Sample Ad Network.

@import GoogleMobileAds;
...
@implementation AppDelegate

- (BOOL)application:(UIApplication *)application
    didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {

  // Initialize Google Mobile Ads SDK
  [[GADMobileAds sharedInstance]
      startWithCompletionHandler:^(GADInitializationStatus *_Nonnull status) {
        GADAdapterInitializationState adapterState =
            status.adapterStatusesByClassName[@"SampleAdapter"].state;

        if (adapterState == GADAdapterInitializationStateReady) {
          // Sample adapter was successfully initialized.
        } else {
          // Sample adapter is not ready.
        }
      }];

  return YES;
}

@end

Create a rewarded ad object

Rewarded ads are requested and shown by GADRewardedAd objects. The first step in using one is to instantiate it and set its ad unit ID. For example, here's how to create a GADRewardedAd in the viewDidLoad: method of a UIViewController:

@import GoogleMobileAds;
@import UIKit;

@interface ViewController ()

@property(nonatomic, strong) GADRewardedAd *rewardedAd;

@end

@implementation ViewController
- (void)viewDidLoad {
  [super viewDidLoad];

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

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:

ca-app-pub-3940256099942544/1712485313

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.

Load an ad

To load a rewarded ad, call loadRequest:completionHandler: on a GADRewardedAd object:

@import GoogleMobileAds;
@import UIKit;

@interface ViewController ()

@property(nonatomic, strong) GADRewardedAd *rewardedAd;

@end

@implementation ViewController

- (void)viewDidLoad {
  [super viewDidLoad];

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

This code loads a rewarded ad with the provided GADRequest and completion block. Upon successful completion of the ad request, the completion block will be executed with a nil GADRequestError parameter. If ad load failed, the non-nil error object provides failure information.

Show the ad

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.

To show a rewarded ad, check the isReady property on GADRewardedAd to verify that it's finished loading, then call presentFromRootViewController:delegate:. Here's an example of how to do this in one of the action methods in a UIViewController:

@import GoogleMobileAds;

@import UIKit;

@interface ViewController () <GADRewardedAdDelegate>

@property(nonatomic, strong) GADRewardedAd *rewardedAd;

@end

@implementation ViewController
- (IBAction)doSomething:(id)sender {
  ...
  if (self.rewardedAd.isReady) {
    [self.rewardedAd presentFromRootViewController:self delegate:self];
  } else {
    NSLog(@"Ad wasn't ready");
  }
}

Receive ad event notifications

The GADRewardedAdDelegate provided in the presentFromRootViewController:delegate: method gets called when rewarded ad events occur. Each of the methods in GADRewardedAdDelegate corresponds to an event in the lifecycle of a rewarded ad. The rewardedAd:userDidEarnReward: method requires an implementation but all other methods for the class are marked as optional, so you only need to implement the methods you want. This example implements each method and logs a message to the console:

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

/// Tells the delegate that the rewarded ad was presented.
- (void)rewardedAdDidPresent:(GADRewardedAd *)rewardedAd {
  NSLog(@"rewardedAdDidPresent:");
}

/// Tells the delegate that the rewarded ad failed to present.
- (void)rewardedAd:(GADRewardedAd *)rewardedAd didFailToPresentWithError:(NSError *)error {
  NSLog(@"rewardedAd:didFailToPresentWithError");
}

/// Tells the delegate that the rewarded ad was dismissed.
- (void)rewardedAdDidDismiss:(GADRewardedAd *)rewardedAd {
  NSLog(@"rewardedAdDidDismiss:");
}

Using GADRewardedAdDelegate to preload the next rewarded ad

GADRewardedAd is a one-time-use object. This means that once a rewarded ad is shown, the object can't be used to load another ad. To request another rewarded, you'll need to create a new GADRewardedAd object.

A best practice is to load another rewarded ad in the rewardedAdDidDismiss: method on GADRewardedAdDelegate so that the next rewarded ad starts loading as soon as the previous one is dismissed:

- (void)viewDidLoad {
  [super viewDidLoad];
  self.rewardedAd = [self createAndLoadRewardedAd];
}

- (GADRewardedAd *)createAndLoadRewardedAd {
  GADRewardedAd *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.
    }
  }];
  return rewardedAd;
}

- (void)rewardedAdDidDismiss:(GADRewardedAd *)rewardedAd {
  self.rewardedAd = [self createAndLoadRewardedAd];
}

Loading multiple rewarded ads

To load multiple rewarded ads, follow the steps outlined in the create a rewarded ad object and load an ad sections for each ad you intend to load. The code snippet below demonstrates how to load two rewarded ads for two distinct ad placements.

- (void)viewDidLoad {
  [super viewDidLoad];
  GADRewardedAd *gameOverRewardedAd = [self
    createAndLoadRewardedAdForAdUnit:@"ca-app-pub-3940256099942544/1712485313"];
  GADRewardedAd *extraCoinsRewardedAd = [self
    createAndLoadRewardedAdForAdUnit:@"ca-app-pub-3940256099942544/1712485313"];
}

- (GADRewardedAd *)createAndLoadRewardedAdForAdUnit:(NSString *) adUnitId {
  GADRewardedAd *rewardedAd = [[GADRewardedAd alloc] initWithAdUnitID:adUnitId];
  GADRequest *request = [GADRequest request];
  [rewardedAd loadRequest:request completionHandler:^(GADRequestError * _Nullable error) {
    if (error) {
      // Handle ad failed to load case.
    } else {
      // Ad successfully loaded.
    }
  }];
  return rewardedAd;
}

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

Kirim masukan tentang...

Butuh bantuan? Kunjungi halaman dukungan kami.