獎勵廣告自訂事件

必要條件

完成自訂事件設定。

要求顯示獎勵廣告

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

如要請求獎勵廣告，請建立或修改導入 GADMediationAdapter 和 loadRewarded:adConfiguration:completionHandler: 的類別。如果已有擴充 GADMediationAdapter 的類別，請在該處實作 loadRewarded:adConfiguration:completionHandler:。此外，請建立新類別來導入 GADMediationRewardedAd。

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

Swift

import GoogleMobileAds

class SampleCustomEvent: NSObject, MediationAdapter {

  fileprivate var rewardedAd: SampleCustomEventRewarded?
  ...

  func loadRewarded(
    for adConfiguration: MediationRewardedAdConfiguration,
    completionHandler: @escaping GADMediationRewardedLoadCompletionHandler
  ) {
    self.rewardedAd = SampleCustomEventRewarded()
    self.rewardedAd?.loadRewarded(
      for: adConfiguration, completionHandler: completionHandler)
  }
}

Objective-C

#import "SampleCustomEvent.h"

@implementation SampleCustomEvent
...

SampleCustomEventRewarded *sampleRewarded;

- (void)loadRewardedForAdConfiguration:
            (GADMediationRewardedAdConfiguration *)adConfiguration
                     completionHandler:
                         (GADMediationRewardedLoadCompletionHandler)
                             completionHandler {
  sampleRewarded = [[SampleCustomEventRewarded alloc] init];
  [sampleRewarded loadRewardedForAdConfiguration:adConfiguration
                               completionHandler:completionHandler];
}

SampleCustomEventRewarded 負責處理以下工作：

  • 載入獎勵廣告。

  • 導入 GADMediationRewardedAd 通訊協定。

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

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

Swift

class SampleCustomEventRewarded: NSObject, MediationRewardedAd {
  /// The Sample Ad Network rewarded ad.
  var nativeAd: SampleRewarded?

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

  /// Completion handler called after ad load.
  var completionHandler: GADMediationRewardedLoadCompletionHandler?

  func loadRewarded(
    for adConfiguration: MediationRewardedAdConfiguration,
    completionHandler: @escaping GADMediationRewardedLoadCompletionHandler
  ) {
    rewarded = SampleRewarded.init(
      adUnitID: adConfiguration.credentials.settings["parameter"] as? String)
    rewarded?.delegate = self
    let adRequest = SampleAdRequest()
    adRequest.testMode = adConfiguration.isTestRequest
    self.completionHandler = completionHandler
    rewarded?.fetchAd(adRequest)
  }
}

Objective-C

#import "SampleCustomEventRewarded.h"

@interface SampleCustomEventRewarded () <SampleRewardedAdDelegate,
                                         GADMediationRewardedAd> {
  /// The sample rewarded ad.
  SampleRewarded *_rewardedAd;

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

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

- (void)loadRewardedAdForAdConfiguration:(GADMediationRewardedAdConfiguration *)adConfiguration
                       completionHandler:
                           (GADMediationRewardedLoadCompletionHandler)completionHandler {
  __block atomic_flag completionHandlerCalled = ATOMIC_FLAG_INIT;
  __block GADMediationRewardedLoadCompletionHandler originalCompletionHandler =
      [completionHandler copy];

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

    id<GADMediationRewardedAdEventDelegate> 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"];
  _rewardedAd = [[SampleRewardedAd alloc] initWithAdUnitID:adUnit];
  _rewardedAd.delegate = self;
  SampleAdRequest *adRequest = [[SampleAdRequest alloc] init];
  adRequest.testMode = adConfiguration.isTestRequest;
  [_rewardedAd fetchAd:adRequest];
}

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

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

Swift

func rewardedDidLoad(_ interstitial: SampleRewarded) {
  if let handler = completionHandler {
    delegate = handler(self, nil)
  }
}

func rewarded(
  rewarded: SampleRewarded, didFailToLoadAdWith errorCode: SampleErrorCode
) {
  let error =
    SampleCustomEventUtils.SampleCustomEventErrorWithCodeAndDescription(
      code: SampleCustomEventErrorCode
        .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)rewardedDidLoad:(SampleRewarded *)rewarded {
  _adEventDelegate = _loadCompletionHandler(self, nil);
}

- (void)rewarded:(SampleInterstitial *)rewarded
    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);
}

GADMediationrewardedAd 須導入 present(viewController:) 方法才能顯示廣告：

Swift

func present(from viewController: UIViewController) {
  if let rewarded = rewarded, rewarded.isRewardedLoaded {
    rewarded.show()
  }
}

Objective-C

- (void)presentFromViewController:(UIViewController *)viewController {
  if ([_rewardedAd isRewardedLoaded]) {
    [_rewardedAd show];
  } else {
    NSError *error = SampleCustomEventErrorWithCodeAndDescription(
        SampleCustomEventErrorAdNotLoaded,
        [NSString stringWithFormat:
                      @"The rewarded ad failed to present because the ad was not loaded."]);
    [_adEventDelegate didFailToPresentWithError:error]
  }
}

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

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

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

Swift

func rewardedAdDidPresent(_ rewarded: SampleRewardedAd) {
  delegate?.willPresentFullScreenVideo()
  delegate?.didStartVideo()
}

func rewardedAdUserDidEarnReward(_ rewarded: SampleRewardedAd) {
  AdReward aReward = AdReward("", rewarded)
  delegate.didRewardUser()
}

Objective-C

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

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

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