横幅广告和插页式广告的自定义事件

本指南适用于希望在 AdMob 中介内增加对横幅广告和插页式广告自定义事件支持的发布商。

借助自定义事件，您不仅可在广告空间中放置希望使用的任意视图，还可以利用中介间接支持的广告联盟通过您的应用获利。至于自定义事件的实现，既可使用 GADCustomEventBanner 协议，也可以使用 GADCustomEventInterstitial 协议。

前提条件

在为横幅广告或插页式广告集成自定义事件之前，您需要将相应广告格式集成到自己的应用中，以下是相关指南：

示例广告联盟

本指南介绍了如何使用 SampleCustomEventBanner 和 SampleCustomEventInterstital 自定义事件类投放示例广告联盟提供的横幅广告和插页式广告。示例广告联盟 SDK 是一种模拟 SDK，旨在让您了解如何实现真实的自定义事件，其中包含了大多数广告联盟都会提供的一些典型的类。要详细了解这些类，请参阅完整的示例 SDK 实现。

横幅广告自定义事件

在以下示例中，您将首先在 AdMob 中介内创建一个横幅广告自定义事件。这需要通过 AdMob 界面定义一个自定义事件，使之指向您应用中特定的类，然后实现横幅广告自定义事件以返回视图。

定义自定义事件

自定义事件必须在 AdMob 界面中定义。有关如何进行界面导航的说明，请参阅创建自定义事件。

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

下表提供了有关如何填写这些参数的指南。

类名称

输入用于实现自定义事件的类的完全限定名称。

如果您的类是在 Swift 中实现的，则您需要添加其应用/框架模块名称作为类名称的前缀（如 appName.className）。

如果项目中包含多个目标，或者项目名称与目标名称不一致，则需要包含目标名称。如果类名称中包含目标名称，看起来将如下所示：appName_targetName.className。此外，请务必将短划线等任何非字母数字字符替换为下划线。

有关详情，请参阅此示例。

标签

输入相关事件的唯一名称。

参数

如果您想要向自定义事件传递参数，请输入相应的字符串。

请求横幅广告

对于自定义事件横幅广告请求，系统会在自定义事件类实例化后立即调用 requestBannerAd:parameter:label:request: 方法。此方法不会返回任何值。假设自定义事件将开始通过广告联盟异步提取广告。那么，您的自定义事件应以 SDK 代理的形式监听回调情况。

如果您的 SDK 不支持指定广告尺寸或不支持横幅广告，请调用自定义事件代理的 customEventBanner:didFailAd: 方法。serverParameter 和 serverLabel 参数对应的是您在 AdMob 界面中创建自定义事件时定义的参数和标签字段。

下面是使用示例广告联盟的 requestBannerAd:parameter:label:request: 的实现示例：

Swift

func requestBannerAd(adSize: GADAdSize, parameter serverParameter: String!,
    label serverLabel: String!, request: GADCustomEventRequest!) {
  // Create a banner view with the appropriate size.
  bannerAd = SampleBanner(frame: CGRectMake(
      0, 0, adSize.size.width, adSize.size.height))
  bannerAd.delegate = self
  bannerAd.adUnit = serverParameter
  let adRequest = SampleAdRequest()
  adRequest.testMode = request.isTesting
  adRequest.keywords = request.userKeywords
  bannerAd.fetchAd(adRequest)
}

Objective-C

- (void)requestBannerAd:(GADAdSize)adSize
              parameter:(NSString *)serverParameter
                  label:(NSString *)serverLabel
                request:(GADCustomEventRequest *)request {
  // Create the bannerView with the appropriate size.
  self.bannerAd =
      [[SampleBanner alloc] initWithFrame:CGRectMake(0,
                                                     0,
                                                     adSize.size.width,
                                                     adSize.size.height)];

  self.bannerAd.delegate = self;
  self.bannerAd.adUnit = serverParameter;
  SampleAdRequest *adRequest = [[SampleAdRequest alloc] init];
  adRequest.testMode = request.isTesting;
  adRequest.keywords = request.userKeywords;
  [self.bannerAd fetchAd:adRequest];
}

针对自定义事件请求发送广告联盟额外信息

要随请求发送广告联盟额外信息供您的自定义事件处理，您可以使用 GADRequest registerAdNetworkExtras: 函数。您必须创建（符合 GADAdNetworkExtras 协议的）GADCustomEventExtras 实例，以便系统填充 GADCustomEventRequest.additionalParameters 属性。要传入您的额外信息，请调用 GADCustomEventExtras setExtras:forLabel:，这样，系统就会以字典和您在 AdMob 界面中定义的自定义事件标签的形式传入额外信息。

以下代码段说明了如何为之前定义的 SampleCustomEvent 标签传递 SampleExtra 参数：

Swift

let request = GADRequest()
let extras = GADCustomEventExtras()
extras.setExtras(["SampleExtra": true], forLabel: "SampleCustomEvent")
request.register(extras)

Objective-C

GADRequest *request = [GADRequest request];
GADCustomEventExtras *extras = [[GADCustomEventExtras alloc] init];
[extras setExtras:@{@"SampleExtra": @(YES)} forLabel:@"SampleCustomEvent"];
[request registerAdNetworkExtras:extras];

如果您没有为自定义事件请求注册 GADCustomEventExtras 的实例，则 GADCustomEventRequest 的 additionalParameters 属性将为 nil。

通知 AdMob 中介

为您的广告联盟实现广告监听器，并调用自定义事件代理上的相关回调，以将消息发送回中介。下面的示例通过实现示例广告联盟的 SampleBannerAdDelegate 接口来发送这些消息：

Swift

/// Type property for Sample Ad Network custom event error domain.
static let customEventErrorDomain = "com.google.CustomEvent"

// Sent when banner ad has loaded.
func bannerDidLoad(banner: SampleBanner!) {
  delegate.customEventBanner(self, didReceiveAd: banner)
}

// Sent when banner has failed to load.
func banner(banner: SampleBanner!, didFailToLoadAdWithErrorCode error: SampleErrorCode) {
  let nsError = NSError(domain: SampleCustomEventBanner.customEventErrorDomain,
      code: error.rawValue, userInfo: nil)
  delegate.customEventBanner(self, didFailAd: nsError)
}

// Sent when a banner is clicked and an external application is launched
func bannerWillLeaveApplication(banner: SampleBanner!) {
  delegate.customEventBannerWasClicked(self)
  delegate.customEventBannerWillLeaveApplication(self)
}

Objective-C

/// Constant for Sample Ad Network custom event error domain.
static NSString *const customEventErrorDomain = @"com.google.CustomEvent";

// Sent when banner ad has loaded.
- (void)bannerDidLoad:(SampleBanner *)banner {
  [self.delegate customEventBanner:self didReceiveAd:banner];
}

// Sent when banner has failed to load.
- (void)banner:(SampleBanner *)banner
    didFailToLoadAdWithErrorCode:(SampleErrorCode)errorCode {
  NSError *error = [NSError errorWithDomain:customEventErrorDomain
                                       code:errorCode
                                   userInfo:nil];
  [self.delegate customEventBanner:self didFailAd:error];
}

// Sent when a banner is clicked and an external application is launched.
- (void)bannerWillLeaveApplication:(SampleBanner *)banner {
  [self.delegate customEventBannerWasClicked:self];
  [self.delegate customEventBannerWillLeaveApplication:self];
}

AdMob 中介支持以下回调：

横幅广告

方法	调用时机
`customEventBanner:didReceiveAd:`	横幅广告请求成功时。
`customEventBanner:didFailAd:`	横幅广告请求失败时。
`customEventBannerWillPresentModal:`	横幅广告将呈现全屏模式视图时。
`customEventBannerWillDismissModal:`	横幅广告将关闭全屏模式视图时。
`customEventBannerDidDismissModal:`	横幅广告确实关闭了全屏模式视图时。
`customEventBannerWillLeaveApplication:`	横幅广告引起用户离开应用时。
`customEventBannerWasClicked:`	用户点击横幅广告时。

插页式广告

方法	调用时机
`customEventInterstitial:DidReceiveAd:`	插页式广告请求成功时。
`customEventInterstitial:didFailAd:`	插页式广告请求失败时。
`customEventInterstitialWillPresent:`	插页式广告将向用户展示且呈现全屏模式视图时。
`customEventInterstitialWillDismiss:`	插页式广告将关闭全屏模式视图时。
`customEventInterstitialDidDismiss:`	插页式广告确实关闭了全屏模式视图时。
`customEventInterstitialWillLeaveApplication:`	插页式广告引起用户离开应用时。
`customEventInterstitialWasClicked:`	用户点击插页式广告时。

有关详情，请参阅自定义事件横幅广告的实现示例。

插页式广告自定义事件

插页式广告自定义事件的实现与横幅广告自定义事件类似。两者的主要区别是：您创建的插页式广告自定义事件类应实现 GADCustomEventInterstitial 协议，而不是 GADCustomEventBanner 协议。

定义自定义事件

自定义事件必须在 AdMob 界面中定义。有关如何进行界面导航的说明，请参阅创建自定义事件。

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

下表提供了有关如何填写这些参数的指南。

类名称

输入用于实现自定义事件的类的完全限定名称。

如果您的类是在 Swift 中实现的，则您需要添加其应用/框架模块名称作为类名称的前缀（如 appName.className）。

有关详情，请参阅此示例。

标签

输入相关事件的唯一名称。

参数

如果您想要向自定义事件传递参数，请输入相应的字符串。

请求插页式广告

对于自定义事件插页式广告请求，系统会在自定义事件类实例化后立即调用 requestInterstitialAdWithParameter:label:request: 方法。此方法不会返回任何值。假设自定义事件将开始通过广告联盟异步提取广告。

那么，您的自定义事件应以 SDK 代理的形式监听回调情况。serverParameter 和 serverLabel 参数对应的是您在 AdMob 界面中创建自定义事件时定义的参数和标签字段。

下面是使用示例广告联盟的 requestInterstitialAdWithParameter:label:request: 的实现示例：

Swift

func requestInterstitialAdWithParameter(serverParameter: String!,
    label serverLabel: String!, request: GADCustomEventRequest!) {
  interstitial = SampleInterstitial()
  interstitial.delegate = self
  interstitial.adUnit = serverParameter
  let adRequest = SampleAdRequest()
  adRequest.testMode = request.isTesting
  adRequest.keywords = request.userKeywords
  interstitial.fetchAd(adRequest)
}

Objective-C

- (void)requestInterstitialAdWithParameter:(NSString *)serverParameter
                                     label:(NSString *)serverLabel
                                   request:(GADCustomEventRequest *)request {
  self.interstitial = [[SampleInterstitial alloc] init];
  self.interstitial.delegate = self;
  self.interstitial.adUnit = serverParameter;
  SampleAdRequest *adRequest = [[SampleAdRequest alloc] init];
  adRequest.testMode = request.isTesting;
  adRequest.keywords = request.userKeywords;
  [self.interstitial fetchAd:adRequest];
}

GADCustomEventInterstitial 自定义事件协议要求您实现 presentFromRootViewController: 方法。当您指示移动广告 SDK 展示插页式广告时，中介会调用此方法，如下所示：

Swift

func presentFromRootViewController(rootViewController: UIViewController!) {
  if interstitial.interstitialLoaded {
    interstitial.show()
  }
}

Objective-C

- (void)presentFromRootViewController:(UIViewController *)rootViewController {
  if ([self.interstitial isInterstitialLoaded]) {
    [self.interstitial show];
  }
}

针对自定义事件请求发送广告联盟额外信息

以下代码段说明了如何为之前定义的 SampleCustomEvent 标签传递 SampleExtra 参数：

Swift

let request = GADRequest()
let extras = GADCustomEventExtras()
extras.setExtras(["SampleExtra": true], forLabel: "SampleCustomEvent")
request.register(extras)

Objective-C

GADRequest *request = [GADRequest request];
GADCustomEventExtras *extras = [[GADCustomEventExtras alloc] init];
[extras setExtras:@{@"SampleExtra": @(YES)} forLabel:@"SampleCustomEvent"];
[request registerAdNetworkExtras:extras];

如果您没有为自定义事件请求注册 GADCustomEventExtras 的实例，则 GADCustomEventRequest 的 additionalParameters 属性将为 nil。

通知 AdMob 中介

与横幅广告自定义事件一样，您需要为广告联盟实现广告监听器，以将消息发送回中介。以下示例显示了示例广告联盟的 SampleInterstitialAdDelegate 接口的实现方法：

Swift

/// Type property for Sample Ad Network custom event error domain.
static let customEventErrorDomain = "com.google.CustomEvent"

// Sent when an interstitial ad has loaded.
func interstitialDidLoad(interstitial: SampleInterstitial!) {
  delegate.customEventInterstitialDidReceiveAd(self)
}

// Sent when interstitial ad has failed to load.
func interstitial(interstitial: SampleInterstitial!,
    didFailToLoadAdWithErrorCode errorCode: SampleErrorCode) {
  let nsError = NSError(domain: SampleCustomEventInterstitial.customEventErrorDomain,
      code: errorCode.rawValue, userInfo: nil)
  delegate.customEventInterstitial(self, didFailAd: nsError)
}

// Sent when an interstitial is about to be shown.
func interstitialWillPresentScreen(interstitial: SampleInterstitial!) {
  delegate.customEventInterstitialWillPresent(self)
}

// Sent when an interstitial is about to be dismissed.
func interstitialWillDismissScreen(interstitial: SampleInterstitial!) {
  delegate.customEventInterstitialWillDismiss(self)
}

// Sent when an interstitial has been dismissed.
func interstitialDidDismissScreen(interstitial: SampleInterstitial!) {
  delegate.customEventInterstitialDidDismiss(self)
}

// Sent when an interstitial is clicked and an external application is launched.
func interstitialWillLeaveApplication(interstitial: SampleInterstitial!) {
  delegate.customEventInterstitialWasClicked(self)
  delegate.customEventInterstitialWillLeaveApplication(self)
}

Objective-C

/// Constant for Sample Ad Network custom event error domain.
static NSString *const customEventErrorDomain = @"com.google.CustomEvent";

// Sent when an interstitial ad has loaded.
- (void)interstitialDidLoad:(SampleInterstitial *)interstitial {
  [self.delegate customEventInterstitialDidReceiveAd:self];
}

// Sent when an interstitial ad has failed to load.
- (void)interstitial:(SampleInterstitial *)interstitial
    didFailToLoadAdWithErrorCode:(SampleErrorCode)errorCode {
  NSError *error = [NSError errorWithDomain:customEventErrorDomain
                                       code:errorCode
                                   userInfo:nil];
  [self.delegate customEventInterstitial:self didFailAd:error];
}

// Sent when an interstitial is about to be shown.
- (void)interstitialWillPresentScreen:(SampleInterstitial *)interstitial {
  [self.delegate customEventInterstitialWillPresent:self];
}

// Sent when an interstitial is about to be dismissed.
- (void)interstitialWillDismissScreen:(SampleInterstitial *)interstitial {
  [self.delegate customEventInterstitialWillDismiss:self];
}

// Sent when an interstitial has been dismissed.
- (void)interstitialDidDismissScreen:(SampleInterstitial *)interstitial {
  [self.delegate customEventInterstitialDidDismiss:self];
}

// Sent when an interstitial is clicked and an external application is launched.
- (void)interstitialWillLeaveApplication:(SampleInterstitial *)interstitial {
  [self.delegate customEventInterstitialWasClicked:self];
  [self.delegate customEventInterstitialWillLeaveApplication:self];
}

将消息发送回中介，有助于它继续中介广告瀑布流。

有关详情，请参阅插页式广告自定义事件的实现示例。