所谓激励广告，指的是用户可以选择与之互动来换取应用内奖励的一种广告。本指南介绍了如何在 iOS 应用中植入 Ad Manager 激励广告。
前提条件
- Google 移动广告 SDK 8.0.0 或更高版本。
- 完成入门指南。
务必用测试广告进行测试
在构建和测试应用时，请确保使用的是测试广告，而不是实际投放的广告。否则，可能会导致您的账号被中止。
对于 iOS 激励广告，加载测试广告最简便的方法就是使用下面的专用测试广告单元 ID：
/21775744923/example/rewarded
该测试广告单元 ID 已经过专门配置，可确保每个请求返回的都是测试广告。您可以在自己应用的编码、测试和调试过程中随意使用该测试广告单元 ID。只需确保您会在发布应用前用自己的广告单元 ID 替换该测试广告单元 ID 即可。
如需详细了解移动广告 SDK 的测试广告如何运作，请参阅测试广告。
实现
植入激励广告的主要步骤如下所示：
- 加载广告
- [可选] 验证 SSV 回调
- 注册回调
- 展示广告并处理奖励事件
加载广告
广告的加载是通过对 GADRewardedAd 类使用 load(adUnitID:request) 方法完成的。
Swift
import GoogleMobileAds
import UIKit
class ViewController: UIViewController {
private var rewardedAd: GADRewardedAd?
func loadRewardedAd() async {
do {
rewardedAd = try await GADRewardedAd.load(
withAdUnitID: "/21775744923/example/rewarded", request: GAMRequest())
} catch {
print("Rewarded ad failed to load with error: \(error.localizedDescription)")
}
}
}
SwiftUI
import GoogleMobileAds
class RewardedViewModel: NSObject, ObservableObject, GADFullScreenContentDelegate {
@Published var coins = 0
private var rewardedAd: GADRewardedAd?
func loadAd() async {
do {
rewardedAd = try await GADRewardedAd.load(
withAdUnitID: "ca-app-pub-3940256099942544/1712485313", request: GADRequest())
rewardedAd?.fullScreenContentDelegate = self
} 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:@"/21775744923/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.");
}];
}
[可选] 验证服务器端验证 (SSV) 回调
对于需要服务器端验证回调中额外数据的应用，应使用激励广告的自定义数据功能。在激励广告对象上设置的任何字符串值都将传递给 SSV 回调的 custom_data 查询参数。如果未设置自定义数据值，custom_data 查询参数值不会出现在 SSV 回调中。
以下代码示例演示了如何在请求广告之前对激励广告对象设置自定义数据。
Swift
do {
rewardedAd = try await GADRewardedAd.load(
withAdUnitID: "/21775744923/example/rewarded", request: GAMRequest())
let options = GADServerSideVerificationOptions()
options.customRewardString = "SAMPLE_CUSTOM_DATA_STRING"
rewardedAd.serverSideVerificationOptions = options
} catch {
print("Rewarded ad failed to load with error: \(error.localizedDescription)")
}
Objective-C
[GADRewardedAd
loadWithAdUnitID:@"/21775744923/example/rewarded"
request:[GAMRequest request];
completionHandler:^(GADRewardedAd *ad, NSError *error) {
if (error) {
// Handle Error
return;
}
self.rewardedAd = ad;
GADServerSideVerificationOptions *options =
[[GADServerSideVerificationOptions alloc] init];
options.customRewardString = @"SAMPLE_CUSTOM_DATA_STRING";
ad.serverSideVerificationOptions = options;
}];
注册回调
如需接收有关展示事件的通知，您必须实现 GADFullScreenContentDelegate 协议并将其分配给已返回广告的 fullScreenContentDelegate 属性。GADFullScreenContentDelegate 协议会在广告成功展示或展示失败，以及用户关闭广告时处理回调。以下代码演示了如何实现此协议并将其分配给广告：
Swift
import GoogleMobileAds
import UIKit
class ViewController: UIViewController, GADFullScreenContentDelegate {
private var rewardedAd: GADRewardedAd?
func loadRewardedAd() async {
do {
rewardedAd = try await GADRewardedAd.load(
withAdUnitID: "/21775744923/example/rewarded", request: GAMRequest())
rewardedAd?.fullScreenContentDelegate = self
} catch {
print("Rewarded ad failed to load with error: \(error.localizedDescription)")
}
}
/// 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.")
}
}
SwiftUI
将 fullScreenContentDelegate 属性分配给返回的广告：
rewardedAd?.fullScreenContentDelegate = self
实现该协议：
func adDidRecordImpression(_ ad: GADFullScreenPresentingAd) {
print("\(#function) called")
}
func adDidRecordClick(_ ad: GADFullScreenPresentingAd) {
print("\(#function) called")
}
func ad(
_ ad: GADFullScreenPresentingAd,
didFailToPresentFullScreenContentWithError error: Error
) {
print("\(#function) called")
}
func adWillPresentFullScreenContent(_ ad: GADFullScreenPresentingAd) {
print("\(#function) called")
}
func adWillDismissFullScreenContent(_ ad: GADFullScreenPresentingAd) {
print("\(#function) called")
}
func adDidDismissFullScreenContent(_ ad: GADFullScreenPresentingAd) {
print("\(#function) called")
// Clear the rewarded ad.
rewardedAd = nil
}
Objective-C
@interface ViewController () <GADFullScreenContentDelegate>
@property(nonatomic, strong) GADRewardedAd *rewardedAd;
@end
@implementation ViewController
- (void)loadRewardedAd {
GAMRequest *request = [GAMRequest request];
[GADRewardedAd
loadWithAdUnitID:@"ca-app-pub-3940256099942544/4806952744"
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.");
}
GADRewardedAd 是一次性对象。这意味着，激励广告展示一次后就不能再展示了。最佳做法是在 GADFullScreenContentDelegate 上的 adDidDismissFullScreenContent: 方法中加载另一个激励广告，以便在上一个激励广告关闭后，立即开始加载下一个激励广告。
展示广告并处理奖励事件
在向用户展示激励广告之前，必须为用户提供明确的选项，让用户可以自行选择是否通过观看激励广告内容来换取奖励。激励广告必须始终是一项可由用户自行选择的体验。
展示广告时，您必须提供 GADUserDidEarnRewardHandler 对象，用于处理用户奖励。
以下代码演示了展示激励广告的最佳方法。
Swift
func show() {
guard let rewardedAd = rewardedAd else {
return print("Ad wasn't ready.")
}
// The UIViewController parameter is an optional.
ad.present(fromRootViewController: nil) {
let reward = ad.adReward
print("Reward received with currency \(reward.amount), amount \(reward.amount.doubleValue)")
// TODO: Reward the user.
}
}
SwiftUI
监听视图中的界面事件，以确定何时展示广告。
var body: some View {
VStack(spacing: 20) {
Button("Watch video for additional 10 coins") {
viewModel.showAd()
showWatchVideoButton = false
}
从视图模型中展示激励广告：
func showAd() {
guard let rewardedAd = rewardedAd else {
return print("Ad wasn't ready.")
}
rewardedAd.present(fromRootViewController: nil) {
let reward = rewardedAd.adReward
print("Reward amount: \(reward.amount)")
self.addCoins(reward.amount.intValue)
}
}
Objective-C
- (void)show {
if (self.rewardedAd) {
// The UIViewController parameter is nullable.
[self.rewardedAd presentFromRootViewController:nil
userDidEarnRewardHandler:^{
GADAdReward *reward =
self.rewardedAd.adReward;
// TODO: Reward the user!
}];
} else {
NSLog(@"Ad wasn't ready");
}
}
常见问题解答
- 我可以获取
GADRewardedAd的详细奖励信息吗？ - 可以，如果您需要在
userDidEarnReward回调触发之前获取奖励金额信息，可以查看GADRewardedAd的adReward属性，在广告加载后验证奖励金额。 - 初始化调用是否会超时？
- 10 秒后，即使中介广告联盟仍未完成初始化，Google 移动广告 SDK 还是会调用提供给
startWithCompletionHandler:方法的GADInitializationCompletionHandler。 - 在获得初始化回调时，如果某些中介广告联盟尚未就绪，该怎么办？
我们建议您在
GADInitializationCompletionHandler中加载广告。即使中介广告联盟尚未就绪，Google 移动广告 SDK 仍会向该广告联盟请求广告。因此，如果中介广告联盟在超时后完成初始化，它仍然可以在该会话中为将来的广告请求提供服务。您可以通过调用
GADMobileAds.initializationStatus继续在整个应用会话中轮询所有适配器的初始化状态。- 如何找出特定中介广告联盟未准备就绪的原因？
GADAdapterStatus对象的description属性描述了适配器未准备好为广告请求提供服务的原因。- 系统是否始终会在调用
adDidDismissFullScreenContent:委托方法之前调用userDidEarnRewardHandler完成处理程序？ 对于 Google Ads，所有
userDidEarnRewardHandler调用都发生在adDidDismissFullScreenContent:调用之前。对于通过中介投放的广告，由第三方广告联盟 SDK 的实现情况决定回调顺序。对于为单个委托方法提供奖励信息的广告联盟 SDK，中介适配器会在调用adDidDismissFullScreenContent:之前调用userDidEarnRewardHandler。
GitHub 上的示例
以您的首选语言查看完整的激励广告示例：
后续步骤
详细了解用户隐私权。