实现激励广告适配器

中介适配器接收来自 Google 移动广告 SDK 的消息和请求，并与第三方广告联盟 SDK 通信以完成这些请求。

本指南适用于希望为 Google 移动广告中介构建激励广告中介适配器的广告联盟。下面的代码段中使用了示例 SDK 进行演示。您可以在我们的 iOS中介项目中找到为此示例 SDK 构建的适配器的完整实现。本指南介绍了如何构建适配器。

定义适配器类名称和服务器参数

对于通过 AdMob 中介平台进行中介的广告联盟，通常需要使用一个或多个标识符来识别发布商。这些标识符以服务器参数的形式表示。当您在 AdMob 界面中配置用于中介的第三方广告联盟时，可以定义这些标识符。

在开发中介适配器之前，您必须向 Google 提供您的适配器类名称和其他必需参数，以获得广告网络的访问权限。

符合 GADMediationAdapter 协议

第一步是让适配器类实现 GADMediationAdapter 协议：

#import <Foundation/Foundation.h>
#import <GoogleMobileAds/GoogleMobileAds.h>
#import <SampleAdSDK/SampleAdSDK.h>

@interface GADMediationAdapterSampleAdNetwork : NSObject <GADMediationAdapter>
@end

此变更可确保您的类实现下面讨论的多种方法。

报告 extras 类

如果第三方广告联盟希望允许发布商为广告请求传递其他可选参数，则必须从 networkExtrasClass 方法返回 extras 类。如果第三方不支持发布商提供的 extra，则返回 Nil。

#import <GoogleMobileAds/GoogleMobileAds.h>

@interface SampleExtras : NSObject<GADAdNetworkExtras>

/// Use this to indicate if debug mode is on for logging.
@property(nonatomic) BOOL debugLogging;

/// Use this to indicate whether to mute audio for video ads.
@property(nonatomic) BOOL muteAudio;

@end

#import "GADMediationAdapterSampleAdNetwork.h"

@implementation GADMediationAdapterSampleAdNetwork
...
+ (Class<GADAdNetworkExtras>)networkExtrasClass {
  return [SampleExtras class];
}
...
@end

报告版本号

适配器必须向 Google 移动广告 SDK 报告适配器本身和第三方 SDK 的版本。使用 GADVersionNumber报告版本。

Google 标明版本的开源适配器使用 4 位数的适配器版本模式，但 GADVersionNumber只允许有 3 位数。如需解决此问题，建议将最后两位数字组合为补丁版本，如下所示：

#import "GADMediationAdapterSampleAdNetwork.h"

@implementation GADMediationAdapterSampleAdNetwork
...
+ (GADVersionNumber)adSDKVersion {
  NSString *versionString = SampleSDKVersion;
  NSArray *versionComponents = [versionString componentsSeparatedByString:@"."];

  GADVersionNumber version = {0};
  if (versionComponents.count >= 3) {
    version.majorVersion = [versionComponents[0] integerValue];
    version.minorVersion = [versionComponents[1] integerValue];
    version.patchVersion = [versionComponents[2] integerValue];
  }
  return version;
}

+ (GADVersionNumber)version {
  NSString *versionString = SampleAdapterVersion;
  NSArray *versionComponents = [versionString componentsSeparatedByString:@"."];

  GADVersionNumber version = {0};
  if (versionComponents.count >= 4) {
    version.majorVersion = [versionComponents[0] integerValue];
    version.minorVersion = [versionComponents[1] integerValue];
    // Adapter versions have 2 patch versions. Multiply the first patch by 100.
    version.patchVersion =
        [versionComponents[2] integerValue] * 100 + [versionComponents[3] integerValue];
  }
  return version;
}
...
@end

初始化适配器

当应用初始化 Google 移动广告 SDK 时，系统会对在 AdMob 界面中为该应用配置的所有适配器调用 setUpWithConfiguration:completionHandler:。

GADMediationServerConfiguration 参数会提供在 AdMob 界面中为该应用配置的所有展示位置的相关信息。使用此信息来初始化广告联盟 SDK。初始化广告联盟 SDK 后，调用 GADMediationAdapterSetUpCompletionBlock 参数。利用此代码块，您可以使用 nil 或 NSError 对象调用完成处理程序，从而向 Google 移动广告 SDK 报告初始化是成功还是失败。

#import "SampleAdapter.h"

@implementation SampleAdapter
...
+ (void)setUpWithConfiguration:(GADMediationServerConfiguration *)configuration
             completionHandler:(GADMediationAdapterSetUpCompletionBlock)completionHandler {
  // Since the Sample SDK doesn't need to be initialized, the completion
  //handler is called directly here.
  completionHandler(nil);
}
...
@end

请求激励广告

当应用通过 Google 移动广告 SDK 加载激励广告时，如果您的广告联盟在中介广告瀑布流中进入，系统会在适配器上调用 loadRewardedAdForAdConfiguration:completionHandler:。

借助 GADRewardedLoadCompletionHandler，您可以通过提供对符合 GADMediationRewardedAd 协议的对象的引用，向 Google 移动广告 SDK 报告广告加载成功；或者通过提供 nil 引用和 NSError 对象，报告广告加载失败。调用加载完成处理程序会返回一个 GADMediationRewardedAdEventDelegate，适配器在广告生命周期内应保留该 GADMediationRewardedAdEventDelegate，以通知 Google 移动广告 SDK 后续发生的任何事件。

#import "SampleAdapter.h"

@interface SampleAdapter () <GADMediationRewardedAd> {
  /// Rewarded ads from Sample SDK.
  SampleRewardedAd *_rewardedAd;

  /// Handles any callback when the sample rewarded ad finishes loading.
  GADMediationRewardedLoadCompletionHandler _loadCompletionHandler;

  /// Delegate for receiving rewarded ad notifications.
  __weak id<GADMediationRewardedAdEventDelegate> _rewardedAdDelegate;
}
@end

@implementation SampleAdapter
...
- (void)loadRewardedAdForAdConfiguration:(GADMediationRewardedAdConfiguration *)adConfiguration
                       completionHandler:
                           (GADMediationRewardedLoadCompletionHandler)completionHandler {
  _loadCompletionHandler = completionHandler;

  NSString *adUnit = adConfiguration.credentials.settings[SampleSDKAdUnitIDKey];
  SampleExtras *extras = adConfiguration.extras;

  _rewardedAd = [[SampleRewardedAd alloc] initWithAdUnitID:adUnit];
  _rewardedAd.enableDebugLogging = extras.enableDebugLogging;

  /// Check the extras to see if the request should be customized.
  SampleAdRequest *request = [[SampleAdRequest alloc] init];
  request.mute = extras.muteAudio;

  /// Set the delegate on the rewarded ad to listen for callbacks from the Sample SDK.
  _rewardedAd.delegate = self;
  [_rewardedAd fetchAd:request];
}
...
@end

中继广告加载事件

适配器负责监听第三方 SDK 回调并将其映射到相应的 Google 移动广告 SDK 回调。

通过使用广告或错误调用 loadCompletionHandler 来报告第三方广告加载事件的成功或失败。如果通过广告调用完成处理程序且没有出现错误，则会返回广告事件委托对象。保留对此委托的引用，以便适配器稍后可以中继展示事件。

- (void)rewardedAdDidReceiveAd:(nonnull SampleRewardedAd *)rewardedAd {
  _rewardedAdDelegate = _loadCompletionHandler(self, nil);
}

- (void)rewardedAdDidFailToLoadWithError:(SampleErrorCode)errorCode {
  _loadCompletionHandler(nil, [NSError errorWithDomain:kAdapterErrorDomain
                                                  code:GADErrorNoFill
                                              userInfo:nil]);
}

展示广告

当应用要求 Google 移动广告 SDK 展示激励广告时，该 SDK 会在调用加载完成处理程序时提供的 GADMediationRewardedAd 实例上调用 presentFromViewController: 方法。您应在此处展示激励广告：

- (void)presentFromViewController:(nonnull UIViewController *)viewController {
  if (!_rewardedAd.isReady) {
    NSError *error =
        [NSError errorWithDomain:kAdapterErrorDomain
                            code:0
                        userInfo:@{NSLocalizedDescriptionKey : @"Unable to display ad."}];
    [_rewardedAdDelegate didFailToPresentWithError:error];
    return;
  }
  [_rewardedAd presentFromRootViewController:viewController];
}

向移动广告 SDK 报告广告事件

展示广告后，适配器应使用广告事件成功加载时返回的广告事件代理来报告广告呈现生命周期事件。

- (void)rewardedAdDidPresent:(nonnull SampleRewardedAd *)rewardedAd {
  [_rewardedAdDelegate willPresentFullScreenView];
  [_rewardedAdDelegate didStartVideo];
  [_rewardedAdDelegate reportImpression];
}

- (void)rewardedAdDidDismiss:(nonnull SampleRewardedAd *)rewardedAd {
  [_rewardedAdDelegate willDismissFullScreenView];
  [_rewardedAdDelegate didEndVideo];
  [_rewardedAdDelegate didDismissFullScreenView];
}
- (void)rewardedAd:(nonnull SampleRewardedAd *)rewardedAd userDidEarnReward:(NSUInteger)reward {
  GADAdReward *aReward =
      [[GADAdReward alloc] initWithRewardType:@"GADMediationAdapterSampleAdNetwork"
                                 rewardAmount:[NSDecimalNumber numberWithUnsignedInt:reward]];
  [_rewardedAdDelegate didRewardUserWithReward:aReward];
}

下面详细说明了应向 Google 移动广告 SDK 报告的广告事件：

广告事件 说明
willPresentFullScreenView 向 Google 移动广告 SDK 发出广告将展示的通知。
didStartVideo 向 Google 移动广告 SDK 发出激励广告开始播放的通知。
reportImpression 向 Google 移动广告 SDK 发出广告展示了一次的通知。
didEndVideo 向 Google 移动广告 SDK 发出激励广告已播放完毕的通知。
didRewardUserWithReward 向 Google 移动广告 SDK 发出用户已获得奖励的通知。
reportClick 向 Google 移动广告 SDK 发出用户已点击广告的通知。
willDismissFullScreenView 向 Google 移动广告 SDK 发出广告将关闭的通知。
didDismissFullScreenView 向 Google 移动广告 SDK 发出广告已关闭的通知。