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:

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 initWithGADMAdNetworkConnector: 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 initWithGADMAdNetworkConnector: method is shown below:

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

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

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

Custom events

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:

- (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:

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

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.

- (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:

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:

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

Additional targeting parameters

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

// 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:

@interface SampleAdNetworkExtras : NSObject <GADAdNetworkExtras>
/// 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:

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

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