動画リワード アダプタの実装

このガイドは、AdMob メディエーション プラットフォームを使用して第三者広告ネットワークから動画リワード スループットを表示することを検討されている方を対象としています。

AdMob でサポートされている広告ネットワークとカスタム イベント

AdMob メディエーション プラットフォームで直接サポートされている広告ネットワークでは、標準のメディエーション アダプタを実装します。AdMob で直接サポートされていない広告ネットワークで動画リワードをリクエストして表示するには、カスタム イベント アダプタを実装する必要があります。標準のメディエーション アダプタとカスタム イベント アダプタの違いについては、以下で概説していきます。

サーバー パラメータの定義

AdMob メディエーション プラットフォームでメディエーションされる広告ネットワークでは、パブリッシャーを識別するために 1 つ以上の ID が必要となる場合があります。これらの ID はサーバー パラメータとして表され、AdMob 管理画面でメディエーションに使用する第三者広告ネットワークを設定する際に定義されます。カスタム イベント アダプタを構築する場合は、以下の手順に沿ってカスタム イベントを作成してください。標準のアダプタを構築する場合は、広告ネットワークと対応するサーバー パラメータがすでに AdMob 管理画面で定義された状態になっています。

カスタム イベントの作成

カスタム イベントを定義するには、まず AdMob 管理画面でカスタム イベントを作成する必要があります。手順については、カスタム イベントを作成するをご確認ください。定義が終了したら、そのカスタム イベントで、GADMRewardBasedVideoAdNetworkAdapter を実装しているアプリ内のクラスをポイントして、動画リワードを配信します。同様に、そのカスタム イベントで、動画リワード アダプタに渡されるサーバー パラメータも登録します。

カスタム イベントの設定サンプルのスクリーンショットを次に示します。

上の画面サンプル内の各エントリは次の内容を表しています。

クラス名 カスタム イベントを実装するクラスの完全修飾名です。
ラベル イベントに固有の名前です。
パラメータ カスタム イベントに渡されるオプションの引数です。

メディエーション アダプタの実装

このガイドでは、アダプタの実装に必要な手順を一つひとつ見ていきます。サンプル広告ネットワーク SDK を使用すると、実際のアダプタコードがどのようなものになるか把握することができます。

アダプタの初期化

アプリで最初の動画リワード広告がリクエストされると、Google Mobile Ads SDK はアダプタの initWithRewardBasedVideoAdNetworkConnector: メソッドを呼び出します。アダプタでは、このメソッドで提供される GADMRewardBasedVideoAdNetworkConnector に対する弱参照を維持する必要があります。アダプタは、この GADMRewardBasedVideoAdNetworkConnector オブジェクトを使用して Google Mobile Ads SDK とやり取りします。以降このオブジェクトをコネクタと呼びます。

initWithRewardBasedVideoAdNetworkConnector: メソッドの実装サンプルを以下に示します。

Swift

required init!(rewardBasedVideoAdNetworkConnector connector: GADMRewardBasedVideoAdNetworkConnector!) {
  guard let connector = connector else {
    return nil
  }
  super.init()

  rewardBasedVideoAdConnector = connector
  adapterDelegate = SampleAdapterDelegate(rewardBasedVideoAdAdapter: self,
  rewardBasedVideoAdconnector: connector)
}

Objective-C

- (instancetype)initWithRewardBasedVideoAdNetworkConnector:
      (id<GADMRewardBasedVideoAdNetworkConnector>)connector {
  if (!connector) {
    return nil;
  }

  self = [super init];
  if (self) {
    _rewardBasedVideoAdConnector = connector;
    _adapterDelegate = [[SampleAdapterDelegate alloc]
        initWithRewardBasedVideoAdAdapter:self
              rewardBasedVideoAdconnector:connector];
  }
  return self;
}

初期化が終わると、Google Mobile Ads SDK はアダプタの setUp メソッドを呼び出し、動画リワードを表示する準備を始めるようアダプタに通知します。アダプタでは、このメソッドの実装と第三者広告ネットワークの初期化が行われます。この時点で、動画リワード スループットのプリロードもアダプタで開始される場合があります。コネクタは、初期化の完了に必要となる(場合によります)サーバー パラメータにアクセスする手段になります。アダプタがメディエーション アダプタかカスタム イベント アダプタかによって、これらのパラメータにアクセスする方法は少し異なります。

メディエーション アダプタの場合は、サーバー パラメータのキーがあらかじめ設定されており、サーバー パラメータを個別に抽出することができます。カスタム イベント アダプタの場合は、CUSTOM_EVENT_SERVER_PARAMETER キーを介してアクセスできるパラメータが 1 つあります。

メディエーション アダプタ

Swift

let parameter1 = connector.credentials()["SERVER_PARAMETER_KEY1"] as? String
let parameter2 = connector.credentials()["SERVER_PARAMETER_KEY2"] as? String

Objective-C

NSString *parameter1 = [self.connector.credentials objectForKey:@"SERVER_PARAMETER_KEY1"];
NSString *parameter2 = [self.connector.credentials objectForKey:@"SERVER_PARAMETER_KEY2"];

カスタム イベント アダプタ

Swift

let parameter = connector.credentials()[GADCustomEventParametersServer] as? String

Objective-C

NSString *parameter = [self.connector.credentials objectForKey:GADCustomEventParametersServer];

初期化に成功した場合は、アダプタでコネクタの adapterDidSetUpRewardBasedVideoAd: を呼び出す必要があります。初期化できなかった場合は、アダプタでコネクタの adapter:didFailToSetUpRewardBasedVideoAdWithError: を呼び出す必要があります。初期化に失敗した場合は、動画リワード広告がリクエストされるたびに、Google Mobile Ads SDK でアダプタの初期化が再試行されます。setUp メソッドの実装サンプルを以下に示します。

Swift

func setUp() {
  rewardBasedVideoAd = SampleRewardBasedVideo.sharedInstance()
  if let delegate = adapterDelegate {
    rewardBasedVideoAd?.delegate = delegate
  }
  let adUnit = rewardBasedVideoAdConnector?.credentials()?["ad_unit"] as? String
  rewardBasedVideoAd?.adUnitID = adUnit
  let request = SampleAdRequest()
  // Set up request parameters.
  request.testMode = connector?.testMode() ?? false
  request.keywords = connector?.userKeywords() as! [String]
  rewardBasedVideoAd?.initialize(with: request, adUnitID: adUnit)
}

Objective-C

- (void)setUp {
  _rewardBasedVideoAd = [SampleRewardBasedVideo sharedInstance];
  _rewardBasedVideoAd.delegate = _adapterDelegate;
  NSString *adUnit = [_rewardBasedVideoAdConnector credentials][@"ad_unit"];
  _rewardBasedVideoAd.adUnit = adUnit;

  SampleAdRequest *request = [[SampleAdRequest alloc] init];
  // Set up request parameters.
  request.testMode = _connector.testMode;
  request.keywords = _connector.userKeywords;

  [_rewardBasedVideoAd initializeWithAdRequest:request adUnitID:adUnit];
}

動画リワード スループットの読み込み

アダプタが adapterDidSetUpRewardBasedVideoAd: コネクタ メソッドを呼び出すと、Google Mobile Ads SDK でアダプタの requestRewardBasedVideoAd メソッドを呼び出すことができます。このメソッドは動画リワード スループットをリクエストします。アダプタは、表示する動画リワード広告を取得すると、コネクタの adapterDidReceiveRewardBasedVideoAd: を呼び出します。表示可能な動画がない場合、アダプタはコネクタの adapter:didFailToLoadRewardBasedVideoAdWithError を呼び出します。

動画リワードに関して、多くの広告ネットワークでは広告リクエストという概念がない API が使用されています。広告ネットワークの初期化が完了したら、現在のユーザーに適した広告枠があり、広告を掲載する準備ができているかどうかを確認してください。この条件を満たしている場合は、ユーザーに広告を表示できます。このような広告ネットワークに適した requestRewardBasedVideoAd の実装サンプルを次に示します。

Swift

func requestRewardBasedVideoAd() {
  guard let strongConnector = rewardBasedVideoAdConnector else {
    return
  }

  if rewardBasedVideoAd?.checkAdAvailability() == true {
    strongConnector.adapterDidReceiveRewardBasedVideoAd(self)
  }
  else {
    let description = "Failed to load ad."
    let userInfo = [NSLocalizedDescriptionKey: description,
                    NSLocalizedFailureReasonErrorKey: description]
    let error = NSError(domain: "com.google.mediation.sample", code: 0, userInfo: userInfo)
    strongConnector.adapter(self, didFailToLoadRewardBasedVideoAdwithError: error)
  }
}

Objective-C

- (void)requestRewardBasedVideoAd {
  id<GADMRewardBasedVideoAdNetworkConnector> strongConnector = _rewardBasedVideoAdConnector;
  if ([_rewardBasedVideoAd checkAdAvailability]) {
    [strongConnector adapterDidReceiveRewardBasedVideoAd:self];
  } else {
    NSString *description = @"Failed to load ad.";
    NSDictionary *userInfo =
        @{NSLocalizedDescriptionKey : description,
        NSLocalizedFailureReasonErrorKey : description};
    NSError *error =
        [NSError errorWithDomain:@"com.google.mediation.sample" code:0 userInfo:userInfo];
    [strongConnector adapter:self didFailToLoadRewardBasedVideoAdwithError:error];
  }
}

動画リワード スループットの表示

Google Mobile Ads SDK では、広告の読み込み成功の通知をアダプタから受け取ると、その後任意のタイミングでアダプタの presentRewardBasedVideoAdWithRootViewController: メソッドを呼び出すことができます。presentRewardBasedVideoAdWithRootViewController: メソッドは、loadAd コールバックが成功するごとに 1 回だけ呼び出されます。このメソッドが呼び出されたら、アダプタで動画リワードを再生します。

Swift

func presentRewardBasedVideoAd(withRootViewController viewController: UIViewController) {
  if rewardBasedVideoAd?.checkAdAvailability() == true {
    // The reward based video ad is available, present the ad.
    rewardBasedVideoAd?.present(fromRootViewController: viewController)
  }
  else {
    // Because publishers are expected to check that an ad is available before
    // trying to show one, the above conditional should always hold true. If for
    // any reason the adapter is not ready to present an ad, however, it should
    // log an error with reason for failure.
    print("No ads to show.")
  }
}

Objective-C

- (void)presentRewardBasedVideoAdWithRootViewController:(UIViewController *)viewController {
  if ([_rewardBasedVideoAd checkAdAvailability]) {
    // The reward based video ad is available, present the ad.
    [_rewardBasedVideoAd presentFromRootViewController:viewController];
  } else {
    // Because publishers are expected to check that an ad is available before
    // trying to show one, the above conditional should always hold true. If for
    // any reason the adapter is not ready to present an ad, however, it should
    // log an error with reason for failure.
    NSLog(@"No ads to show.");
  }
}

Google Mobile Ads SDK に対する広告イベントの転送

以下のいずれかの広告イベントが発生した場合は、アダプタで適切なコネクタ メソッドを起動して Google Mobile Ads SDK に通知する必要があります。

コネクタ メソッド 呼び出すタイミング
adapterDidOpenRewardBasedVideoAd: 全画面オーバーレイがアプリ コンテンツを覆ったとき
adapterDidStartPlayingRewardBasedVideoAd: 動画広告が始まったとき
adapterDidGetAdClick: 動画広告がクリックされたとき
adapterWillLeaveApplication: 動画広告が原因でユーザーがアプリを離れたとき(ブラウザに移動するなど)
adapter:didRewardUserWithReward: 動画広告でユーザーに報酬が提供されたとき
adapterDidCloseRewardBasedVideoAd: 動画広告が閉じられたとき

広告ネットワークには通常、Google Mobile Ads SDK に転送できる似通ったコールバックのセットがあります。サンプル SDK にも、動画リワード用のコールバックを含む SampleRewardBasedVideoDelegate クラスがあります。以下のサンプルは、こうしたコールバックを Google Mobile Ads SDK に転送する方法を示しています。

Swift

weak var rewardBasedVideoAdConnector : GADMRewardBasedVideoAdNetworkConnector?
weak var rewardBasedVideoAdAdapter : GADMRewardBasedVideoAdNetworkAdapter?

// MARK: SampleRewardBasedVideoDelegate methods
func rewardBasedVideoAdInitialized(_ rewardBasedVideo: SampleRewardBasedVideo) {
    guard let strongConnector = rewardBasedVideoAdConnector,
      let strongAdapter = rewardBasedVideoAdAdapter else {
        return
    }
    strongConnector.adapterDidSetUpRewardBasedVideoAd(strongAdapter)
}

func rewardBasedVideoAdDidReceiveAd(_ rewardBasedVideo: SampleRewardBasedVideo) {
  guard let strongConnector = rewardBasedVideoAdConnector,
    let strongAdapter = rewardBasedVideoAdAdapter else {
      return
  }
    strongConnector.adapterDidReceiveRewardBasedVideoAd(strongAdapter)
}

func rewardBasedVideoAdDidOpen(_ rewardBasedVideo: SampleRewardBasedVideo) {
  guard let strongConnector = rewardBasedVideoAdConnector,
    let strongAdapter = rewardBasedVideoAdAdapter else {
      return
  }
    strongConnector.adapterDidOpenRewardBasedVideoAd(strongAdapter)
}

func rewardBasedVideoAdDidStartPlaying(_ rewardBasedVideo: SampleRewardBasedVideo) {
  guard let strongConnector = rewardBasedVideoAdConnector,
    let strongAdapter = rewardBasedVideoAdAdapter else {
      return
  }
    strongConnector.adapterDidStartPlayingRewardBasedVideoAd(strongAdapter)
}
func rewardBasedVideoAdDidClose(_ rewardBasedVideo: SampleRewardBasedVideo) {
  guard let strongConnector = rewardBasedVideoAdConnector,
    let strongAdapter = rewardBasedVideoAdAdapter else {
      return
  }
  strongConnector.adapterDidCloseRewardBasedVideoAd(strongAdapter)
}

func rewardBasedVideoAdWillLeaveApplication(_ rewardBasedVideo: SampleRewardBasedVideo) {
  guard let strongConnector = rewardBasedVideoAdConnector,
    let strongAdapter = rewardBasedVideoAdAdapter else {
      return
  }
  strongConnector.adapterWillLeaveApplication(strongAdapter)
}

func rewardBasedVideoAdDidReceiveAdClick(_ rewardBasedVideo: SampleRewardBasedVideo) {
  guard let strongConnector = rewardBasedVideoAdConnector,
    let strongAdapter = rewardBasedVideoAdAdapter else {
      return
  }
  strongConnector.adapterDidGetAdClick(strongAdapter)
}

func rewardBasedVideoAdDidReceiveAdClick(_ rewardBasedVideo: SampleRewardBasedVideo) {
  guard let strongConnector = rewardBasedVideoAdConnector,
    let strongAdapter = rewardBasedVideoAdAdapter else {
      return
  }
  strongConnector.adapterDidGetAdClick(strongAdapter)
}

func rewardBasedVideoAd(_ rewardBasedVideo: SampleRewardBasedVideo,
                        rewardUserWithReward reward: Int) {
  guard let strongConnector = rewardBasedVideoAdConnector,
    let strongAdapter = rewardBasedVideoAdAdapter else {
      return
  }
  // An empty string is passed to the reward type parameter because the Sample
  // SDK doesn't use a reward type and the reward type parameter cannot be nil.
  let rewardItem = GADAdReward(rewardType: "", rewardAmount: NSDecimalNumber(value:reward))
    strongConnector.adapter(strongAdapter, didRewardUserWith: rewardItem)
}

func rewardBasedVideoAd(_ rewardBasedVideo: SampleRewardBasedVideo,
                        didFailToLoadWithError error: SampleErrorCode) {
  guard let strongConnector = rewardBasedVideoAdConnector,
    let strongAdapter = rewardBasedVideoAdAdapter else {
      return
  }
  let adapterError = NSError(domain: "kAdapterErrorDomain",
                      code: error.rawValue, userInfo: nil)
    strongConnector.adapter(strongAdapter,
                        didFailToLoadRewardBasedVideoAdwithError: adapterError)
}

Objective-C

#pragma mark SampleRewardBasedVideoDelegate methods

- (void)rewardBasedVideoAdInitialized:(SampleRewardBasedVideo *)rewardBasedVideo {
  id<GADMRewardBasedVideoAdNetworkConnector> strongConnector = _rewardBasedVideoAdConnector;
  id<GADMRewardBasedVideoAdNetworkAdapter> strongAdapter = _rewardBasedVideoAdAdapter;
  [strongConnector adapterDidSetUpRewardBasedVideoAd:strongAdapter];
}

- (void)rewardBasedVideoAdDidReceiveAd:(SampleRewardBasedVideo *)rewardBasedVideo {
  id<GADMRewardBasedVideoAdNetworkConnector> strongConnector = _rewardBasedVideoAdConnector;
  id<GADMRewardBasedVideoAdNetworkAdapter> strongAdapter = _rewardBasedVideoAdAdapter;
  [strongConnector adapterDidReceiveRewardBasedVideoAd:strongAdapter];
}

- (void)rewardBasedVideoAdDidOpen:(SampleRewardBasedVideo *)rewardBasedVideo {
  id<GADMRewardBasedVideoAdNetworkConnector> strongConnector = _rewardBasedVideoAdConnector;
  id<GADMRewardBasedVideoAdNetworkAdapter> strongAdapter = _rewardBasedVideoAdAdapter;
  [strongConnector adapterDidOpenRewardBasedVideoAd:strongAdapter];
}

- (void)rewardBasedVideoAdDidStartPlaying:(SampleRewardBasedVideo *)rewardBasedVideo {
  id<GADMRewardBasedVideoAdNetworkConnector> strongConnector = _rewardBasedVideoAdConnector;
  id<GADMRewardBasedVideoAdNetworkAdapter> strongAdapter = _rewardBasedVideoAdAdapter;
  [strongConnector adapterDidStartPlayingRewardBasedVideoAd:strongAdapter];
}

- (void)rewardBasedVideoAdDidClose:(SampleRewardBasedVideo *)rewardBasedVideo {
  id<GADMRewardBasedVideoAdNetworkConnector> strongConnector = _rewardBasedVideoAdConnector;
  id<GADMRewardBasedVideoAdNetworkAdapter> strongAdapter = _rewardBasedVideoAdAdapter;
  [strongConnector adapterDidCloseRewardBasedVideoAd:strongAdapter];
}

- (void)rewardBasedVideoAdWillLeaveApplication:(SampleRewardBasedVideo *)rewardBasedVideo {
  id<GADMRewardBasedVideoAdNetworkConnector> strongConnector = _rewardBasedVideoAdConnector;
  id<GADMRewardBasedVideoAdNetworkAdapter> strongAdapter = _rewardBasedVideoAdAdapter;
  [strongConnector adapterWillLeaveApplication:strongAdapter];
}

- (void)rewardBasedVideoAdDidReceiveAdClick:(SampleRewardBasedVideo *)rewardBasedVideo {
  id<GADMRewardBasedVideoAdNetworkConnector> strongConnector = _rewardBasedVideoAdConnector;
  id<GADMRewardBasedVideoAdNetworkAdapter> strongAdapter = _rewardBasedVideoAdAdapter;
  [strongConnector adapterDidGetAdClick:strongAdapter];
}

- (void)rewardBasedVideoAdDidReceiveAdClick:(SampleRewardBasedVideo *)rewardBasedVideo {
  id<GADMRewardBasedVideoAdNetworkConnector> strongConnector = _rewardBasedVideoAdConnector;
  id<GADMRewardBasedVideoAdNetworkAdapter> strongAdapter = _rewardBasedVideoAdAdapter;
  [strongConnector adapterDidGetAdClick:strongAdapter];
}

- (void)rewardBasedVideoAd:(SampleRewardBasedVideo *)rewardBasedVideo
      rewardUserWithReward:(int)reward {
  id<GADMRewardBasedVideoAdNetworkConnector> strongConnector = _rewardBasedVideoAdConnector;
  id<GADMRewardBasedVideoAdNetworkAdapter> strongAdapter = _rewardBasedVideoAdAdapter;
  // An empty string is passed to the reward type parameter because the Sample
  // SDK doesn't use a reward type and the reward type parameter cannot be nil.
  GADAdReward *rewardItem =
      [[GADAdReward alloc] initWithRewardType:@""
                                 rewardAmount:[NSDecimalNumber numberWithInteger:reward]];
  [strongConnector adapter:strongAdapter didRewardUserWithReward:rewardItem];
}

- (void)rewardBasedVideoAd:(SampleRewardBasedVideo *)rewardBasedVideo
      didFailToLoadWithError:(SampleErrorCode)error {
  id<GADMRewardBasedVideoAdNetworkConnector> strongConnector = _rewardBasedVideoAdConnector;
  id<GADMRewardBasedVideoAdNetworkAdapter> strongAdapter = _rewardBasedVideoAdAdapter;
  NSError *adapterError = [NSError errorWithDomain:kAdapterErrorDomain code:error userInfo:nil];
  [strongConnector adapter:strongAdapter
didFailToLoadRewardBasedVideoAdwithError:adapterError];
}

ターゲット設定の追加パラメータ

コネクタには、広告のターゲットを設定する際に参照できる、ターゲット設定の一般情報(testModeuserKeywordschildDirectedTreatment など)が含まれています。

Swift

// Set up request parameters.
let request = SampleAdRequest()
request.testMode = connector?.testMode() ?? false
request.keywords = connector?.userKeywords() as? [String]

Objective-C

// Setup request parameters.
SampleAdRequest *request = [[SampleAdRequest alloc] init];
request.testMode = self.connector.testMode;
request.keywords = self.connector.userKeywords;

アダプタへのカスタム パラメータの導入

アダプタでメディエーションの対象としている広告ネットワークによっては、コネクタで提供されるオプションで対応できない、特別なターゲット設定パラメータや入力値がサポートされている場合があります。このような場合には、GADAdNetworkExtras プロトコルに準拠したクラスを実装することで、特別なパラメータを提供するようパブリッシャーにリクエストすることができます。

以下に、SampleAdNetworkExtras クラスのサンプルを示します。

Swift

class SampleAdNetworkExtras: NSObject, GADAdNetworkExtras {
  /// Should ad volume audio be muted.
  var isMuteAudio = false
}

Objective-C

@interface SampleAdNetworkExtras : NSObject <GADAdNetworkExtras>
/// Should ad volume audio be muted.
@property(nonatomic, assign) BOOL muteAudio;

@end

この場合、パブリッシャーは広告リクエストを行うときに GADAdNetworkExtras サブクラスのインスタンスを渡す必要があります。この GADAdNetworkExtras サブクラスのインスタンスには、コネクタを通じてアクセスできます。以下に、パブリッシャーから提供された特別なパラメータをアダプタで取得して、それを使って第三者広告ネットワークに対する広告リクエストを作成する方法を示します。

Swift

public static func networkExtrasClass() -> GADAdNetworkExtras.Type {
  return SampleAdNetworkExtras.self
}

Objective-C

+ (Class<GADAdNetworkExtras>)networkExtrasClass {
  return [SampleAdNetworkExtras class];
}

メディエーションの特別なパラメータがアダプタで使用されていない場合は、networkExtrasClass メソッドで Nil が返されます。

フィードバックを送信...

ご不明な点がありましたら、Google のサポートページをご覧ください。