導入獎勵廣告轉接程式

重要事項： 使用與中介服務服務相關的 Google Mobile Ads SDK 時，必須遵守《中介服務服務條款》。

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

本指南適用於想要為 Google 行動廣告中介服務建構獎勵中介服務轉接程式的廣告聯播網。下方程式碼片段會用範例 SDK 進行示範。您可以在 iOS中介服務專案中，找到專為這個範例 SDK 建構的轉接程式完整導入方式。本指南說明如何建構轉接程式。

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

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

在開發中介服務轉接程式之前，您必須將轉接程式類別名稱和其他必要參數提供給 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 UI 中為應用程式設定的所有轉接程式叫用 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 已關閉廣告。