激励广告自定义事件

本指南适用于希望使用 AdMob 中介来展示 界面不直接支持的广告联盟所提供的激励广告的发布商。

借助激励广告自定义事件,您可以编写自定义的中介适配器,从而展示第三方广告联盟提供的激励广告。在本指南中,我们将介绍如何编写自定义事件,以通过我们开发的示例 SDK 请求广告。您可以在 GitHub 上找到示例 SDK 的完整源代码。

前提条件

在能够集成自定义事件之前,您需要先集成激励广告格式。 有关集成激励广告格式的说明,请参阅激励广告指南。

创建自定义事件

要定义自定义事件,必须先在 AdMob 界面中创建自定义事件。有关创建自定义事件的说明,请参阅添加自定义事件

定义自定义事件后,该自定义事件适配器会指向您的应用中某个通过实现 GADMediationAdapter 协议来投放激励广告的类。此外,自定义事件还会列出传递给激励广告适配器的服务器参数。

以下屏幕截图显示的是自定义事件示例的部分设置:

该屏幕截图包含以下条目:

类名称
实现自定义事件适配器的类的完全限定名称。
标签
定义广告来源的唯一名称。
参数
传递给自定义事件适配器的可选字符串参数。

实现自定义事件

自定义事件是通过实现 GADMediationAdapter 协议来投放第三方广告的类。下面是实现自定义事件以请求和展示示例广告联盟提供的激励广告的步骤。

实现 GADMediationAdapter

要创建自定义事件,首先要实现 GADMediationAdapter 协议,如下面的 GADMediationAdapterSampleAdNetwork 类所示。

#import <Foundation/Foundation.h>

@import GoogleMobileAds;
@interface GADMediationAdapterSampleAdNetwork : NSObject <GADMediationAdapter>
@end

报告 extras 类

如果自定义事件支持 extras 类为广告请求指定额外参数,则必须使用 networkExtrasClass 方法返回 extras 类。 如果自定义事件不支持发布商提供的 extras 类,则返回 Nil

#import "GADMediationAdapterSampleAdNetwork.h"

@implementation GADMediationAdapterSampleAdNetwork
...
+ (nullable Class<GADAdNetworkExtras>)networkExtrasClass {
  return Nil;
}
...
@end

报告版本号

所有自定义事件都必须向 Google 移动广告 SDK 报告自定义事件本身的版本,以及与该自定义事件对接的第三方 SDK 的版本。报告版本时使用的是 GADVersionNumber

#import "GADMediationAdapterSampleAdNetwork.h"

@implementation GADMediationAdapterSampleAdNetwork
...
+ (GADVersionNumber)adSDKVersion {
  NSString *versionString = @"1.0.0";
  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 = @"1.0.0.0";
  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

请求激励广告

应用发出的加载激励广告的请求会调用自定义事件的 loadRewardedAdForAdConfiguration:completionHandler: 方法。

通过引用一个实现 GADMediationRewardedAd 的对象来调用提供的 completionHandler,可向 Google 移动广告 SDK 报告广告已成功加载。此调用会返回 GADMediationRewardedAdEventDelegate。自定义事件应该保留对此对象的引用,以向 Google 移动广告 SDK 发出广告生命周期事件的通知。有关进一步详细说明,请参阅展示广告部分。

要报告广告加载错误,请使用 NSError 对象调用提供的 completionHandler。

下面是 loadRewardedAdForAdConfiguration:completionHandler: 的实现示例:

#import "GADMediationAdapterSampleAdNetwork.h"

@interface GADMediationAdapterSampleAdNetwork () <GADMediationRewardedAd> {
  /// Reward-based video ads from Sample SDK.
  SampleRewardBasedVideo *_rewardBasedVideoAd;
}
@property(nonatomic, weak, nullable) id<GADMediationRewardedAdEventDelegate> delegate;
@end
@implementation GADMediationAdapterSampleAdNetwork
...
- (void)loadRewardedAdForAdConfiguration:(GADMediationRewardedAdConfiguration *)adConfiguration
                       completionHandler:(GADRewardedLoadCompletionHandler)completionHandler {
  // Look for the "parameter" key to fetch the parameter you defined in the AdMob UI.
  NSString *adUnit = adConfiguration.credentials.settings[@"parameter"];
  SampleAdRequest *request = [[SampleAdRequest alloc] init];
  [SampleAdNetwork loadAdWithRequest:request
                   completionHandler:^(SampleRewardBasedVideo *ad ,NSError *error) {
    if (error) {
      completionHandler(nil, error);
      return;
    }
    _rewardBasedVideoAd = ad;
    self.delegate = completionHandler(self, nil);
  }];
}
...
@end

展示广告

当应用要求 Google 移动广告 SDK 展示激励广告时,该 SDK 会在 GADMediationRewardedAd 的实例上调用 presentFromViewController: 方法。实现此方法以展示激励广告。

- (void)presentFromViewController:(nonnull UIViewController *)viewController {
  if ([_rewardBasedVideoAd checkAdAvailability]) {
    // The reward based video ad is available, present the ad.
    [_rewardBasedVideoAd presentFromRootViewController:viewController];
  } else {
    NSError *error =
      [NSError errorWithDomain:@"GADMediationAdapterSampleAdNetwork"
                          code:0
                      userInfo:@{NSLocalizedDescriptionKey : @"Unable to display ad."}];
    [self.delegate didFailToPresentWithError:error];
  }
}

报告广告事件

展示广告后,自定义事件应该使用广告成功加载时提供的 GADMediationRewardedAdEventDelegate,向 Google 移动广告 SDK 报告相应的广告生命周期事件。

- (void)rewardBasedVideoAdDidOpen:(SampleRewardBasedVideo *)rewardBasedVideo {
  [self.delegate willPresentFullScreenView];
  [self.delegate reportImpression];
}

- (void)rewardBasedVideoAdDidStartPlaying:(SampleRewardBasedVideo *)rewardBasedVideo {
  [self.delegate didStartVideo];
}

- (void)rewardBasedVideoAdDidStopPlaying:(SampleRewardBasedVideo *)rewardBasedVideo {
  [self.delegate didEndVideo];
}

- (void)rewardBasedVideoAdDidClose:(SampleRewardBasedVideo *)rewardBasedVideo {
  [self.delegate willDismissFullScreenView];
}

- (void)rewardBasedVideoAdDidReceiveAdClick:(SampleRewardBasedVideo *)rewardBasedVideo {
  [self.delegate reportClick];
}

- (void)rewardedAd:(nonnull SampleRewardedAd *)rewardedAd userDidEarnReward:(NSUInteger)reward {
  GADAdReward *aReward =
      [[GADAdReward alloc] initWithRewardType:@""
                                 rewardAmount:[NSDecimalNumber numberWithUnsignedInt:reward]];
  [self.delegate 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 发出广告将关闭的通知。