迁移到全屏广告 API（Beta 版）

Google 移动广告 SDK v7.67.0 推出了插页式广告 API 和激励广告 API（Beta 版），这些 API 共用常规的全屏广告样式，从而可实现更好的一致性。这些 API 由 GADInterstitialAdBeta 和 GADRewardedAdBeta 表示，并将于 2021 年年初取代 GADInterstitial 和 GADRewardedAd。本指南将为您介绍如何迁移至插页式广告和激励广告的 Beta 版。

全新 API（Beta 版）的优势

新版全屏广告 API 与当前的全屏广告 API 有两大主要区别：

  1. 静态类方法 load。

    目前加载/展示全屏广告的方法如下：

    1. 创建广告对象实例并保留对该实例的引用。
    2. 分配一个处理加载和显示回调的代理。
    3. 加载广告。
    4. 使用 isReady 检查广告是否已加载。
    5. 展示广告。

    在新版 API 中，该方法略有变化。加载回调不再是代理所需处理的工作。相反，这些回调会作为完成处理程序传入 load 方法。

    加载/展示全屏广告的新方法如下：

    1. 针对广告类调用静态加载方法，并提供加载完成处理程序。
    2. 在加载完成回调中，保留对返回的已加载广告的引用。
    3. 分配一个处理显示回调的代理。
    4. 展示广告。

    新方法具有以下优点：

    • 您将不会再有对未加载的广告的引用。
    • 广告加载时，您无需保留广告对象。

  2. 广告事件一致。

    事件类型 现有 API API（Beta 版）
    加载事件 GADInterstitialDelegate 或者 GADRewardedAdDelegate GADInterstitialAdBetaLoadCompletionHandler 或者 GADRewardedAdBetaLoadCompletionHandler
    展示事件 GADFullScreenContentDelegate

    目前，要监听任何广告事件，您都要注册一个对插页式广告的代理属性实现 GADInterstitialDelegate 协议的类，或者注册一个对激励广告的代理属性实现 GADRewardedAdDelegate 协议的类，具体哪个类取决于您使用的广告格式。同一代理具有与广告加载和展示生命周期都相关的方法。

    对于新版 API 来说，加载和展示事件可以区分开来。现在，您可以在展示广告之前随时注册 GADFullScreenContentDelegate，而无需在加载广告前先设置单一代理。各种广告格式特有的广告加载事件将转变为加载方法中传递的单个加载完成处理程序。

插页式广告

加载广告

以下代码段展示了如何加载插页式广告，以及如何在广告成功加载或加载失败时监听事件。

当前 API

Swift

import GoogleMobileAds
import UIKit

class ViewController: UIViewController, GADInterstitialDelegate {

  var interstitial: GADInterstitial!

  override func viewDidLoad() {
    super.viewDidLoad()
    interstitial = GADInterstitial(adUnitID: "ca-app-pub-3940256099942544/4411468910")
    interstitial.delegate = self
    let request = GADRequest()
    interstitial.load(request)
  }

  /// Tells the delegate an ad request succeeded.
  func interstitialDidReceiveAd(_ ad: GADInterstitial) {
    print("Interstitial ad loaded.")
  }

  /// Tells the delegate an ad request failed.
  func interstitial(_ ad: GADInterstitial, didFailToReceiveAdWithError error: GADRequestError) {
    print("Interstitial ad failed to load with error: \(error.localizedDescription)")
  }
}

Objective-C

@import GoogleMobileAds;
@import UIKit;

@interface ViewController () 

@property(nonatomic, strong) GADInterstitial *interstitial;

@end

@implementation ViewController

- (void)viewDidLoad {
  [super viewDidLoad];
  self.interstitial = [[GADInterstitial alloc]
      initWithAdUnitID:@"ca-app-pub-3940256099942544/4411468910"];
  self.interstitial.delegate = self;
  GADRequest *request = [GADRequest request];
  [self.interstitial loadRequest:request];
}

/// Tells the delegate an ad request succeeded.
- (void)interstitialDidReceiveAd:(GADInterstitial *)ad {
  NSLog(@"Insterstitial ad loaded.");
}

/// Tells the delegate an ad request failed.
- (void)interstitial:(GADInterstitial *)ad
    didFailToReceiveAdWithError:(GADRequestError *)error {
  NSLog(@"Interstitial ad failed to load with error: %@", [error localizedDescription]);
}

API（Beta 版）

Swift

import GoogleMobileAds
import UIKit

class ViewController: UIViewController, GADFullScreenContentDelegate {

  var interstitial: GADInterstitialAdBeta?

  override func viewDidLoad() {
    super.viewDidLoad()
    let request = GADRequest()
    GADInterstitialAdBeta.load(withAdUnitID:"ca-app-pub-8123415297019784/4985798738",
                               request: request,
                               completionHandler: { (ad, error) in
                                if let error = error {
                                  print("Failed to load interstitial ad with error: \(error.localizedDescription)")
                                  return
                                }
                                self.interstitial = ad
                                self.interstitial.fullScreenContentDelegate = self
    })
  }
}

Objective-C

@import GoogleMobileAds;
@import UIKit;

@interface ViewController () 

@property(nonatomic, strong) GADInterstitialAdBeta *interstitial;

@end

@implementation ViewController

- (void)viewDidLoad {
  [super viewDidLoad];
  GADRequest *request = [GADRequest request];
  [GADInterstitialAdBeta loadWithAdUnitID:@"ca-app-pub-3940256099942544/4411468910"
                                  request:request
                        completionHandler:^(GADInterstitialAdBeta *ad, NSError *error) {
    if (error) {
      NSLog(@"Failed to load interstitial ad with error: %@", [error localizedDescription]);
      return;
    }
    self.interstitial = ad;
    self.interstitial.fullScreenContentDelegate = self;
  }];
}

展示广告

当前 API

Swift

func showInterstitial() {
  ...
  if interstitial.isReady {
    interstitial.present(fromRootViewController: self)
  } else {
    print("Ad wasn't ready")
  }
}

Objective-C

- (void)showInterstitial: {
  ...
  if (self.interstitial.isReady) {
    [self.interstitial presentFromRootViewController:self];
  } else {
    NSLog(@"Ad wasn't ready");
  }
}

API（Beta 版）

Swift

func showInterstitial() {
  ...
  if let ad = interstitial {
    ad.present(fromRootViewController: self)
  } else {
    print("Ad wasn't ready")
  }
}

Objective-C

- (void)showInterstitial: {
  ...
  if (self.interstitial) {
    [self.interstitial presentFromRootViewController:self];
  } else {
    NSLog(@"Ad wasn't ready");
  }
}

展示广告事件

以下代码段展示了如何在广告成功展示或展示失败，以及用户关闭广告时处理回调。

当前 API

Swift

override func viewDidLoad() {
  super.viewDidLoad()
  interstitial = GADInterstitial(adUnitID: "ca-app-pub-3940256099942544/4411468910")
  interstitial.delegate = self
  ...
}

/// Tells the delegate that an interstitial will be presented.
func interstitialWillPresentScreen(_ ad: GADInterstitial) {
  print("Interstitial ad will be presented.")
}

/// Tells the delegate the interstitial is to be animated off the screen.
func interstitialWillDismissScreen(_ ad: GADInterstitial) {
  print("Interstitial ad will be dismissed.")
}

/// Tells the delegate the interstitial had been animated off the screen.
func interstitialDidDismissScreen(_ ad: GADInterstitial) {
  print("Interstitial ad dismissed.")
}

/// Tells the delegate that a user click will open another app
/// (such as the App Store), backgrounding the current app.
func interstitialWillLeaveApplication(_ ad: GADInterstitial) {
  print("Interstitial ad will leave application.")
}

Objective-C

- (void)viewDidLoad {
  [super viewDidLoad];
  self.interstitial = [[GADInterstitial alloc] initWithAdUnitID:"ca-app-pub-3940256099942544/4411468910"];
  self.interstitial.delegate = self;
  ...
}

/// Tells the delegate that an interstitial will be presented.
- (void)interstitialWillPresentScreen:(GADInterstitial *)ad {
  NSLog(@"Interstitial ad will be presented.");
}

/// Tells the delegate the interstitial is to be animated off the screen.
- (void)interstitialWillDismissScreen:(GADInterstitial *)ad {
  NSLog(@"Interstitial ad will be dismissed.");
}

/// Tells the delegate the interstitial had been animated off the screen.
- (void)interstitialDidDismissScreen:(GADInterstitial *)ad {
  NSLog(@"Interstitial ad dismissed.");
}

/// Tells the delegate that a user click will open another app
/// (such as the App Store), backgrounding the current app.
- (void)interstitialWillLeaveApplication:(GADInterstitial *)ad {
  NSLog(@"Interstitial ad will leave application.");
}

API（Beta 版）

Swift

override func viewDidLoad() {
  super.viewDidLoad()
  let request = GADRequest()
  GADInterstitialAdBeta.load(withAdUnitID:"ca-app-pub-8123415297019784/4985798738",
                             request: request,
                             completionHandler: { (ad, error) in
                              if let error = error {
                                print(error.localizedDescription)
                                return
                              }
                              self.interstitial = ad
                              self.interstitial.fullScreenContentDelegate = self
  })
}

func adDidPresentFullScreenContent(_ ad: GADFullScreenPresentingAd) {
  print("Ad did present full screen content.")
}

func ad(_ ad: GADFullScreenPresentingAd, didFailToPresentFullScreenContentWithError error: Error) {
  print("Ad failed to present full screen content with error \(error.localizedDescription).")
}

func adDidDismissFullScreenContent(_ ad: GADFullScreenPresentingAd) {
  print("Ad did dismiss full screen content.")
}

Objective-C

- (void)viewDidLoad {
  [super viewDidLoad];
  GADRequest *request = [GADRequest request];
  [GADInterstitialAdBeta loadWithAdUnitID:@"ca-app-pub-3940256099942544/4411468910"
                                  request:request
                        completionHandler:^(GADInterstitialAdBeta *ad, NSError *error) {
    if (error) {
      NSLog(@"interstitial:didFailToReceiveAdWithError: %@", [error localizedDescription])
      return;
    }
    self.interstitial = ad;
    self.interstitial.fullScreenContentDelegate = self;
  }];
}

- (void)adDidPresentFullScreenContent:(id)ad {
  NSLog(@"Ad did present full screen content.");
}

- (void)ad:(id)ad didFailToPresentFullScreenContentWithError:(NSError *)error {
  NSLog(@"Ad failed to present full screen content with error %@.", [error localizedDescription]);
}

- (void)adDidDismissFullScreenContent:(id)ad {
  NSLog(@"Ad did dismiss full screen content.");
}

激励广告

加载广告

当前 API

Swift

import GoogleMobileAds
import UIKit

class ViewController: UIViewController, GADRewardedAdDelegate {
  /// The rewarded ad.
  var rewardedAd: GADRewardedAd?

  override func viewDidLoad() {
    super.viewDidLoad()
    rewardedAd = GADRewardedAd(adUnitID: "ca-app-pub-3940256099942544/1712485313")
    rewardedAd.delegate = self
    rewardedAd?.load(GADRequest()) { error in
      if let error = error {
        print("Rewarded ad failed to load with error: \(error.localizedDescription)")
      } else {
        print("Rewarded ad loaded.")
      }
    }
  }
}

Objective-C

@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"];
  self.rewardedAd.delegate = self;
  GADRequest *request = [GADRequest request];
  [self.rewardedAd loadRequest:request completionHandler:^(GADRequestError * _Nullable error) {
    if (error) {
      NSLog(@"Rewarded ad failed to load with error: %@", [error localizedDescription]);
    } else {
      NSLog(@"Rewarded ad loaded.");
    }
  }];
}

API（Beta 版）

Swift

import GoogleMobileAds
import UIKit

class ViewController: UIViewController, GADFullScreenContentDelegate {
  /// The rewarded ad.
  var rewardedAd: GADRewardedAdBeta?

  override func viewDidLoad() {
  super.viewDidLoad()
  let request = GADRequest()
  GADRewardedAdBeta.load(withAdUnitID: "ca-app-pub-8123415297019784/9501821136",
                         request: request, completionHandler: { (ad, error) in
                          if let error = error {
                            print("Rewarded ad failed to load with error: \(error.localizedDescription)")

                            return
                          }
                          self.rewardedAd = ad
                          self.rewardedAd?.fullScreenContentDelegate = self
    })
  }
}

Objective-C

@import GoogleMobileAds;
@import UIKit;

@interface ViewController () 

@property(nonatomic, strong) GADRewardedAdBeta *rewardedAd;

@end

@implementation ViewController

- (void)viewDidLoad {
  [super viewDidLoad];

  GADRequest *request = [GADRequest request];
  [GADRewardedAdBeta loadWithAdUnitID:@"ca-app-pub-3940256099942544/1712485313"
                              request:request
                    completionHandler:^(GADRewardedAdBeta *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;
}

展示广告和处理奖励

激励广告要求您在用户获得奖励时处理该事件。借助 GADRewardedAd API，您可以将 rewardedAd:userDidEarnReward: 作为 GADRewardedAdDelegate 协议的一部分实现；如果使用 GADRewardedAdBeta API，则需要实现 GADUserDidEarnRewardHandler 才能展示广告。

当前 API

Swift

func showRewardedAd() {
  ...
  if rewardedAd.isReady {
    rewardedAd.present(fromRootViewController: self delegate:self)
  } else {
    print("Ad wasn't ready")
  }
}

/// Tells the delegate that the user earned a reward.
func rewardedAd(_ rewardedAd: GADRewardedAd, userDidEarnReward: GADAdReward) {
  // TODO: Reward the user.
}

Objective-C

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

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

API（Beta 版）

Swift

func showRewardedAd() {
  ...
  if let ad = rewardedAd {
      ad.present(fromRootViewController: self,
                 userDidEarnRewardHandler: {
                  let reward = ad.adReward
                  // TODO: Reward the user.
      })
  } else {
    print("Ad wasn't ready")
  }
}

Objective-C

- (void)showRewardedAd: {
  ...
  if (self.rewardedAd) {
    [self.rewardedAd presentFromRootViewController:self
                          userDidEarnRewardHandler:^ {
      GADAdReward *reward = self.rewardedAd.adReward;
      // TODO: Reward the user.
    }];
  } else {
    NSLog(@"Ad wasn't ready");
  }
}

展示广告事件

借助 GADRewardedAd API，您可以将 GADRewardedAdDelegate 传递给展示广告的方法。借助 GADRewardedAdBeta API，您可以将 GADFullscreenContentDelegate 设为广告的属性，然后再展示广告。

当前 API

Swift

func showRewardedAd() {
  ...
  if rewardedAd.isReady {
    rewardedAd.present(fromRootViewController: self delegate:self)
  } else {
    print("Ad wasn't ready")
  }
}

/// Tells the delegate that the rewarded ad was presented.
func rewardedAdDidPresent(_ rewardedAd: GADRewardedAd) {
  print("Rewarded ad presented.")
}
/// Tells the delegate that the rewarded ad was dismissed.
func rewardedAdDidDismiss(_ rewardedAd: GADRewardedAd) {
  print("Rewarded ad dismissed.")
}
/// Tells the delegate that the rewarded ad failed to present.
func rewardedAd(_ rewardedAd: GADRewardedAd, didFailToPresentWithError error: Error) {
  print("Rewarded ad failed to present with error: \(error.localizedDescription).")
}

Objective-C

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

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

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

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

API（Beta 版）

Swift

override func viewDidLoad() {
  super.viewDidLoad()
  let request = GADRequest()
  GADRewardedAdBeta.load(withAdUnitID: "ca-app-pub-8123415297019784/9501821136",
                         request: request, completionHandler: { (ad, error) in
                          if let error = error {
                            print(error.localizedDescription)
                            return
                          }
                          self.rewardedAd = ad
                          self.rewardedAd?.fullScreenContentDelegate = self
    })
  }

  /// Tells the delegate that the rewarded ad was presented.
  func adDidPresentFullScreenContent(_ ad: GADFullScreenPresentingAd) {
    print("Rewarded ad presented.")
  }
  /// Tells the delegate that the rewarded ad was dismissed.
  func adDidDismissFullScreenContent(_ ad: GADFullScreenPresentingAd) {
    print("Rewarded ad dismissed.")
  }
  /// Tells the delegate that the rewarded ad failed to present.
  func ad(_ ad: GADFullScreenPresentingAd,
      didFailToPresentFullScreenContentWithError error: Error) {
    print("Rewarded ad failed to present with error: \(error.localizedDescription).")
  }

Objective-C

- (void)viewDidLoad {
  [super viewDidLoad];

  GADRequest *request = [GADRequest request];
  [GADRewardedAdBeta loadWithAdUnitID:@"ca-app-pub-3940256099942544/1712485313"
                              request:request
                    completionHandler:^(GADRewardedAdBeta *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 rewarded ad was presented.
- (void)adDidPresentFullScreenContent:(id)ad {
  NSLog(@"Rewarded ad presented.");
}

/// Tells the delegate that the rewarded ad failed to present.
- (void)ad:(id)ad
    didFailToPresentFullScreenContentWithError:(NSError *)error {
  NSLog(@"Rewarded ad failed to present with error: %@",
       [error localizedDescription]);
}

/// Tells the delegate that the rewarded ad was dismissed.
- (void)adDidDismissFullScreenContent:(id)ad {
  NSLog(@"Rewarded ad dismissed.");
}