導入獎勵廣告轉接程式

中介服務轉接程式會接收來自 Google Mobile Ads SDK 的訊息和要求，並與第三方聯播網 SDK 通訊，以完成這些請求。

本指南適用於希望為 Google 行動廣告中介服務建立獎勵廣告中介服務轉接程式的廣告聯播網。以下程式碼片段使用範例 SDK 進行示範。您可以在 iOS中介服務專案中找到專為此範例 SDK 建構的轉接程式完整實作。本指南說明如何建構轉接程式。

定義轉接器類別名稱和伺服器參數

透過 AdMob 中介服務平台中介服務的廣告聯播網，通常需要一或多個 ID 來識別發布商。這類 ID 會以伺服器參數表示，並在 AdMob UI 中為中介服務設定第三方廣告聯播網時，所定義。

在開發中介服務轉接程式之前，您必須向 Google 提供轉接程式類別名稱和其他必要參數，才能存取廣告聯播網。

符合 GADMediationAdapter 通訊協定

第一步是讓轉接程式類別實作 GADMediationAdapter 通訊協定：

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

@interface GADMediationAdapterSampleAdNetwork : NSObject <GADMediationAdapter>
@end

這項變更可確保您的類別實作以下所述的幾種方法。

回報額外課程

如果第三方聯播網希望允許發布商在廣告請求中傳送其他選用參數，則必須從 networkExtrasClass 方法傳回 extras 類別。如果第三方不支援發布者提供的額外項目，請傳回 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 Mobile Ads 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 Mobile Ads SDK 時，系統會針對 AdMob 使用者介面中為應用程式設定的所有轉接程式叫用 setUpWithConfiguration:completionHandler:。

GADMediationServerConfiguration 引數會提供相關資訊，說明 AdMob UI 中為應用程式設定的所有刊登位置。然後根據這項資訊初始化廣告聯播網 SDK。廣告聯播網 SDK 初始化後，請叫用 GADMediationAdapterSetUpCompletionBlock 引數。這個區塊可讓您藉由使用 nil 或 NSError 物件叫用完成處理常式，向 Google Mobile Ads 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 Mobile Ads SDK 載入獎勵廣告時，如果廣告聯播網到達中介服務刊登序列，系統就會在轉接程式上叫用 loadRewardedAdForAdConfiguration:completionHandler:。

GADRewardedLoadCompletionHandler 可讓您向 Google Mobile Ads SDK 回報成功的廣告載入情形，方法是提供符合 GADMediationRewardedAd 通訊協定的物件參照，或提供 nil 參照和 NSError 物件，以便載入廣告載入失敗。叫用載入完成處理常式時會傳回 GADMediationRewardedAdEventDelegate，而轉接程式應保留到廣告生命週期中，以通知 Google Mobile Ads 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 Mobile Ads 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 Mobile Ads 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];
}

向 Mobile Ads 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 Mobile Ads SDK 的廣告事件：

廣告事件	說明
willPresentFullScreenView	通知 Google Mobile Ads SDK 即將顯示廣告。
didStartVideo	通知 Google Mobile Ads SDK，指出獎勵廣告已開始播放。
reportImpression	通知 Google Mobile Ads SDK 廣告曝光會帶來一次曝光。
didEndVideo	向 Google Mobile Ads SDK 通知獎勵廣告播放完畢。
didRewardUserWithReward	通知 Google Mobile Ads SDK 使用者已獲得獎勵。
reportClick	通知 Google Mobile Ads SDK 使用者按下了廣告。
willDismissFullScreenView	通知 Google Mobile Ads SDK 即將關閉廣告。
didDismissFullScreenView	通知 Google Mobile Ads SDK 已關閉廣告。