Implementing a Rewarded Video Adapter

This guide is intended for those looking to use the AdMob mediation platform to display rewarded video throughput from a third-party ad network.

AdMob supported ad networks and custom events

Ad networks that are directly supported by the AdMob mediation platform implement standard mediation adapters. Ad networks that are not directly supported by AdMob can still be used to request and display rewarded videos by implementing custom event adapters. The differences between standard mediation adapters and custom event adapters are outlined below.

Define server parameters

Ad networks mediated through the AdMob mediation platform may need one or more identifiers in order to identify a publisher. These identifiers are represented as server parameters and are defined when configuring a third-party ad network for mediation in the AdMob interface. If you are building a custom event adapter, follow the creating a custom event step below. If you are building an adapter, your ad network and corresponding server parameters are already defined in the AdMob interface.

Create a custom event

To define a custom event, you must first create it in the AdMob interface. See Create a custom event for instructions. Once the custom event is defined, it points to a class within your app that implements GADMRewardBasedVideoAdNetworkAdapter to serve a rewarded video. The custom event also lists a server parameter that is passed to your rewarded video adapter.

Here is a screenshot showing some sample custom event settings:

The entries in the example screen shown above represent the following:

Class Name	The fully qualified name of the class that implements the custom event.
Label	A unique name for the event.
Parameter	An optional argument passed to your custom event.

Implement a mediation adapter

This guide demonstrates the steps required to implement an adapter. You can use the sample ad network SDK to get an idea of what adapter code may look like in practice.

Initialize the adapter

On an app's initial rewarded video ad request, the Google Mobile Ads SDK invokes the initWithRewardBasedVideoAdNetworkConnector: method of your adapter. Your adapter should maintain a weak reference to the GADMRewardBasedVideoAdNetworkConnector provided by this method. The adapter interacts with the Google Mobile Ads SDK using this GADMRewardBasedVideoAdNetworkConnector object. From here on, this object is referred to as the connector.

A sample implementation of the initWithRewardBasedVideoAdNetworkConnector: method is shown below:

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)connector {
  if (!connector) {
    return nil;
  }

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

After initialization, the Google Mobile Ads SDK calls the setUp method of the adapter to inform the adapter that it should prepare to display rewarded videos. Your adapter is responsible for implementing this method to initialize the third-party ad network. The adapter may also start preloading rewarded video throughput at this point. The connector provides access to server parameters that may be required to complete the initialization. There is a slight difference in how these parameters can be accessed if you're developing a mediation adapter or a custom event adapter.

For a mediation adapter, the keys for server parameters are preconfigured and you can extract the server parameters individually. For custom events, there is a single parameter that can be accessed via the CUSTOM_EVENT_SERVER_PARAMETER key:

Mediation adapter

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"];

Custom events

Swift

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

Objective-C

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

If initialization succeeds, the adapter should call adapterDidSetUpRewardBasedVideoAd: on the connector. If adapter initialization fails, the adapter should invoke adapter:didFailToSetUpRewardBasedVideoAdWithError: on the connector. In the event that initialization fails, the Google Mobile Ads SDK reattempts to initialize the adapter each time a rewarded video ad request is made. A sample implementation of the setUp method is shown below:

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];
}

Load rewarded video throughput

Once the adapter invokes the adapterDidSetUpRewardBasedVideoAd: connector method, the Google Mobile Ads SDK can call the requestRewardBasedVideoAd method of your adapter. This method requests rewarded video throughput. The adapter calls adapterDidReceiveRewardBasedVideoAd: on the connector once it has a rewarded video to show. If no videos are available, the adapter calls adapter:didFailToLoadRewardBasedVideoAdWithError on the connector.

For rewarded videos, many ad networks employ an API where there is no notion of ad requests. Once the ad network has been initialized, you can check if there is inventory for the current user and an ad is ready. If this criteria is met, you can show the ad to the user. A sample implementation of the requestRewardBasedVideoAd for such an ad network is shown below:

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 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];
  }
}

Note: On the first ad request, requestRewardBasedVideoAd may be called on the adapter immediately after its invocation of the adapterDidSetUpRewardBasedVideoAd: connector method. If an ad network is still loading ads at this time, immediately reporting an ad failing to load can result in a large proportion of no fills on that initial rewarded video ad request. In this case, it is recommended that adapters track when the loading of ads is in and delay responding to the Google Mobile Ads SDK until ads have either successfully loaded or failed to load. The Google Mobile Ads SDK has a timeout in place in case the adapter doesn't respond fast enough.

Show the rewarded video throughput

The Google Mobile Ads SDK may call the presentRewardBasedVideoAdWithRootViewController: method of your adapter any time after the adapter notifies the Google Mobile Ads SDK of a successful ad load. The presentRewardBasedVideoAdWithRootViewController: method is only called once per successful loadAd callback. Upon invocation of this method, the adapter should play the rewarded video.

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.");
  }
}

Forward ad events to Google Mobile Ads SDK

Your adapter is required to notify the Google Mobile Ads SDK when any of the following ad events occur by invoking the appropriate connector method:

Connector method	When to call
adapterDidOpenRewardBasedVideoAd:	A full screen overlay covers the app content
adapterDidStartPlayingRewardBasedVideoAd:	The video ad starts
adapterDidGetAdClick:	The video ad is clicked
adapterWillLeaveApplication:	The user leaves the application due to the video ad (for example, to go to the browser)
adapter:didRewardUserWithReward:	The video ad rewards the user
adapterDidCloseRewardBasedVideoAd:	The video ad is closed

Typically, ad networks have a similar set of callbacks that can be forwarded to the Google Mobile Ads SDK. The sample SDK has a SampleRewardBasedVideoDelegate class with callbacks for rewarded video. The example below demonstrates how to forward these callbacks to the 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 strongConnector = _rewardBasedVideoAdConnector;
  id strongAdapter = _rewardBasedVideoAdAdapter;
  [strongConnector adapterDidSetUpRewardBasedVideoAd:strongAdapter];
}

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

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

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

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

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

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

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

- (void)rewardBasedVideoAd:(SampleRewardBasedVideo *)rewardBasedVideo
      rewardUserWithReward:(int)reward {
  id strongConnector = _rewardBasedVideoAdConnector;
  id 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 strongConnector = _rewardBasedVideoAdConnector;
  id strongAdapter = _rewardBasedVideoAdAdapter;
  NSError *adapterError = [NSError errorWithDomain:kAdapterErrorDomain code:error userInfo:nil];
  [strongConnector adapter:strongAdapter
didFailToLoadRewardBasedVideoAdwithError:adapterError];
}

Additional targeting parameters

The connector contains some common targeting information, such as testMode, userKeywords, and childDirectedTreatment, that you can reference for ad targeting:

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;

Accept custom parameters to your adapter

The ad network your adapter is mediating to may support extra targeting parameters or inputs that are not covered by the options provided in the connector. If this applies to your adapter, you can ask publishers to provide extra parameters by implementing a class that conforms to the GADAdNetworkExtras protocol.

The SampleAdNetworkExtras class is shown below as an example:

Swift

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

Objective-C

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

@end

Publishers must pass an instance of your GADAdNetworkExtras subclass when making an ad request. This instance of your GADAdNetworkExtras subclass can be accessed through the connector. Here is how the adapter can extract the extra parameters provided by the publisher and use them to build the ad request to the third-party ad network:

Swift

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

Objective-C

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

If your adapter doesn't use mediation extras, the networkExtrasClass method should return Nil.