橫幅廣告自訂事件

必要條件

完成自訂事件設定。

請求橫幅廣告

當刊登序列中介服務鏈執行到自訂事件委刊項，系統會以您在建立自訂事件時指定的類別名稱，呼叫 loadBanner:adConfiguration:completionHandler: 方法。在本例中，該方法位於 SampleCustomEvent，會接著呼叫 SampleCustomEventBanner 中的 loadBanner:adConfiguration:completionHandler: 方法。

如要請求橫幅廣告，請建立或修改導入 GADMediationAdapter 和 loadBanner:adConfiguration:completionHandler: 的類別。如果已存在擴充 GADMediationAdapter 的類別，請在該處實作 loadBanner:adConfiguration:completionHandler:。此外，請建立新類別來導入 GADMediationBannerAd。

在我們的自訂事件範例中，SampleCustomEvent 會實作 GADMediationAdapter 介面，然後委派給 SampleCustomEventBanner。

Swift

import GoogleMobileAds

class SampleCustomEvent: NSObject, MediationAdapter {

  fileprivate var bannerAd: SampleCustomEventBanner?
  ...

  func loadBanner(
    for adConfiguration: MediationBannerAdConfiguration,
    completionHandler: @escaping GADMediationBannerLoadCompletionHandler
  ) {
    self.bannerAd = SampleCustomEventBanner()
    self.bannerAd?.loadBanner(
      for: adConfiguration, completionHandler: completionHandler)
  }
}

Objective-C

#import "SampleCustomEvent.h"

@implementation SampleCustomEvent
...

SampleCustomEventBanner *sampleBanner;

- (void)loadBannerForAdConfiguration:
            (GADMediationBannerAdConfiguration *)adConfiguration
                   completionHandler:(GADMediationBannerLoadCompletionHandler)
                                         completionHandler {
  sampleBanner = [[SampleCustomEventBanner alloc] init];
  [sampleBanner loadBannerForAdConfiguration:adConfiguration
                           completionHandler:completionHandler];
}

SampleCustomEventBanner 負責處理以下工作：

  • 載入橫幅廣告，並於載入完畢時叫用 GADMediationBannerLoadCompletionHandler 方法。

  • 導入 GADMediationBannerAd 通訊協定。

  • 接收廣告事件回呼，並回報給 Google Mobile Ads SDK。

在 Ad Manager UI 中定義的選用參數會包含在廣告設定。 使用 adConfiguration.credentials.settings[@"parameter"] 即可存取。這項參數通常是廣告單元 ID，廣告聯播網 SDK 在例項化廣告物件時會用到。

Swift

class SampleCustomEventBanner: NSObject, MediationBannerAd {
  /// The Sample Ad Network banner ad.
  var bannerAd: SampleBanner?

  /// The ad event delegate to forward ad rendering events to Google Mobile Ads SDK.
  var delegate: MediationBannerAdEventDelegate?

  /// Completion handler called after ad load
  var completionHandler: GADMediationBannerLoadCompletionHandler?

  func loadBanner(
    for adConfiguration: MediationBannerAdConfiguration,
    completionHandler: @escaping GADMediationBannerLoadCompletionHandler
  ) {
    // Create the bannerView with the appropriate size.
    let adSize = adConfiguration.adSize
    bannerAd = SampleBanner(
      frame: CGRect(x: 0, y: 0, width: adSize.size.width, height: adSize.size.height))
    bannerAd?.delegate = self
    bannerAd?.adUnit = adConfiguration.credentials.settings["parameter"] as? String
    let adRequest = SampleAdRequest()
    adRequest.testMode = adConfiguration.isTestRequest
    self.completionHandler = completionHandler
    bannerAd?.fetchAd(adRequest)
  }
}

Objective-C

#import "SampleCustomEventBanner.h"

@interface SampleCustomEventBanner () <SampleBannerAdDelegate,
                                       GADMediationBannerAd> {
  /// The sample banner ad.
  SampleBanner *_bannerAd;

  /// The completion handler to call when the ad loading succeeds or fails.
  GADMediationBannerLoadCompletionHandler _loadCompletionHandler;

  /// The ad event delegate to forward ad rendering events to the Google Mobile
  /// Ads SDK.
  id <GADMediationBannerAdEventDelegate> _adEventDelegate;
}
@end

@implementation SampleCustomEventBanner

- (void)loadBannerForAdConfiguration:
            (GADMediationBannerAdConfiguration *)adConfiguration
                   completionHandler:(GADMediationBannerLoadCompletionHandler)
                                         completionHandler {
  __block atomic_flag completionHandlerCalled = ATOMIC_FLAG_INIT;
  __block GADMediationBannerLoadCompletionHandler originalCompletionHandler =
      [completionHandler copy];

  _loadCompletionHandler = ^id<GADMediationBannerAdEventDelegate>(
      _Nullable id<GADMediationBannerAd> ad, NSError *_Nullable error) {
    // Only allow completion handler to be called once.
    if (atomic_flag_test_and_set(&completionHandlerCalled)) {
      return nil;
    }

    id<GADMediationBannerAdEventDelegate> delegate = nil;
    if (originalCompletionHandler) {
      // Call original handler and hold on to its return value.
      delegate = originalCompletionHandler(ad, error);
    }

    // Release reference to handler. Objects retained by the handler will also
    // be released.
    originalCompletionHandler = nil;

    return delegate;
  };

  NSString *adUnit = adConfiguration.credentials.settings[@"parameter"];
  _bannerAd = [[SampleBanner alloc]
      initWithFrame:CGRectMake(0, 0, adConfiguration.adSize.size.width,
                               adConfiguration.adSize.size.height)];
  _bannerAd.adUnit = adUnit;
  _bannerAd.delegate = self;
  SampleAdRequest *adRequest = [[SampleAdRequest alloc] init];
  adRequest.testMode = adConfiguration.isTestRequest;
  [_bannerAd fetchAd:adRequest];
}

無論廣告擷取成功或發生錯誤，您都會呼叫 GADMediationBannerLoadCompletionHandler。如果成功，請透過實作 GADMediationBannerAd 的類別，為錯誤參數傳遞 nil 值；如果失敗，請傳遞您遇到的錯誤。

這些方法通常是在轉接程式導入的第三方 SDK 回呼中執行。以本例來說，範例 SDK 的 SampleBannerAdDelegate 含有相關回呼：

Swift

func bannerDidLoad(_ banner: SampleBanner) {
  if let handler = completionHandler {
    delegate = handler(self, nil)
  }
}

func banner(
  _ banner: SampleBanner, didFailToLoadAdWith errorCode: SampleErrorCode
) {
  let error =
    SampleCustomEventUtilsSwift.SampleCustomEventErrorWithCodeAndDescription(
      code: SampleCustomEventErrorCodeSwift
        .SampleCustomEventErrorAdLoadFailureCallback,
      description:
        "Sample SDK returned an ad load failure callback with error code: \(errorCode)"
    )
  if let handler = completionHandler {
    delegate = handler(nil, error)
  }
}

Objective-C

- (void)bannerDidLoad:(SampleBanner *)banner {
  _adEventDelegate = _loadCompletionHandler(self, nil);
}

- (void)banner:(SampleBanner *)banner
    didFailToLoadAdWithErrorCode:(SampleErrorCode)errorCode {
  NSError *error = SampleCustomEventErrorWithCodeAndDescription(
      SampleCustomEventErrorAdLoadFailureCallback,
      [NSString stringWithFormat:@"Sample SDK returned an ad load failure "
                                 @"callback with error code: %@",
                                 errorCode]);
  _adEventDelegate = _loadCompletionHandler(nil, error);
}

GADMediationBannerAd 須導入 UIView 屬性：

Swift

var view: UIView {
  return bannerAd ?? UIView()
}

Objective-C

- (nonnull UIView *)view {
  return _bannerAd;
}

將中介服務事件轉送至 Google Mobile Ads SDK

使用已載入的廣告呼叫 GADMediationBannerLoadCompletionHandler 後，轉接程式可使用傳回的 GADMediationBannerAdEventDelegate 委派物件，將呈現事件從第三方 SDK 轉送至 Google Mobile Ads SDK。SampleCustomEventBanner 類別會實作 SampleBannerAdDelegate 通訊協定，將回呼從範例廣告聯播網轉送到 Google Mobile Ads SDK。

自訂事件應盡量將這些回呼轉送至 Google Mobile Ads SDK，這樣應用程式才能收到相應的事件通知。以下是回呼使用範例：

Swift

func bannerWillLeaveApplication(_ banner: SampleBanner) {
  delegate?.reportClick()
}

Objective-C

- (void)bannerWillLeaveApplication:(SampleBanner *)banner {
  [_adEventDelegate reportClick];
}

到這裡就完成橫幅廣告的自訂事件導入設定！GitHub 上有完整的範例可參考。範例可直接用於支援的廣告聯播網，您也可修改現有範例，顯示自訂事件橫幅廣告。