Implementing a Rewarded Ad Adapter

A mediation adapter receives messages and requests from the Google Mobile Ads SDK and communicates with a third-party network SDK in order to fulfill those requests.

This guide is intended for ad networks looking to build a rewarded ad mediation adapter for Google Mobile Ads Mediation. A Sample SDK is used in the code snippets below for demonstration purposes. You can find a complete implementation of an adapter built for this sample SDK in our iOS Mediation project. This guide explains how to build the adapter.

Define adapter class name and server parameters

Ad networks mediated through the AdMob mediation platform typically require one or more identifiers 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 UI.

Prior to developing a mediation adapter, you must coordinate with Google on what your adapter class name will be, as well as what parameters are needed, so Google can whitelist your ad network.

Conform to GADMediationAdapter protocol

The first step is to make your adapter class implement the GADMediationAdapter protocol:

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

@interface GADMediationAdapterSampleAdNetwork : NSObject <GADMediationAdapter>
@end

This change ensures that your class implements several methods discussed below.

Report extras class

If the third-party network wishes to allow publishers to pass additional optional parameters for an ad request, the extras class must be returned from the networkExtrasClass method. Return Nil if the third-party doesn't support the publisher provided extras.

#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

Report version numbers

The adapter must report to the Google Mobile Ads SDK both the version of the adapter itself and the version of the third-party SDK. Versions are reported using GADVersionNumber.

Google's open source and versioned adapters use a 4-digit adapter version scheme, but GADVersionNumber only allows for 3 digits. To work around this, it is recommended to combine the last two digits into the patch version, as shown below:

#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

Initialize the adapter

When an app initializes the Google Mobile Ads SDK, setUpWithConfiguration:completionHandler: is invoked on all adapters configured for the app within the AdMob UI.

The GADMediationServerConfiguration argument provides information on all placements configured for the app within the AdMob UI. Use this information to initialize your ad network SDK. Once your ad network SDK is initialized, invoke the GADMediationAdapterSetUpCompletionBlock argument. This block lets you report either a successful or failed initialization to the Google Mobile Ads SDK by invoking the completion handler with nil or an NSError object.

#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

Request a rewarded ad

When an app loads a rewarded ad with the Google Mobile Ads SDK, loadRewardedAdForAdConfiguration:completionHandler: is invoked on the adapter if your ad network is reached in the mediation waterfall.

The GADRewardedLoadCompletionHandler lets you report a successful ad load to the Google Mobile Ads SDK by providing a reference to an object that conforms to GADMediationRewardedAd protocol, or a failed ad load by providing a nil reference and an NSError object. The invocation of load completion handler returns a GADMediationRewardedAdEventDelegate which your adapter should hold on to for the lifecycle of the ad to notify the Google Mobile Ads SDK of any subsequent event.

#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

Relay ad load events

It is the adapter's responsibility to listen to third party SDK callbacks and map them to the appropriate Google Mobile Ads SDK callback.

Report the success or failure of third party ad load events by invoking the loadCompletionHandler with an ad or an error. If the completion handler is called with an ad and no error, an ad event delegate object is returned. Keep a reference to this delegate so your adapter can relay presentation events later on.

- (void)rewardedAdDidReceiveAd:(nonnull SampleRewardedAd *)rewardedAd {
  _rewardedAdDelegate = _loadCompletionHandler(self, nil);
}

- (void)rewardedAdDidFailToLoadWithError:(SampleErrorCode)errorCode {
  _loadCompletionHandler(nil, [NSError errorWithDomain:kAdapterErrorDomain
                                                  code:kGADErrorNoFill
                                              userInfo:nil]);
}

Show the ad

When the app asks the Google Mobile Ads SDK to present the rewarded ad, the SDK calls the presentFromViewController: method on the instance of GADMediationRewardedAd provided in the call to the load completion handler. Here you should present the rewarded ad:

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

Report ad events to the Mobile Ads SDK

After displaying the ad, the adapter should report ad presentation lifecycle events using the same ad event delegate returned at successful ad load time.

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

The ad events that should be reported to the Google Mobile Ads SDK are detailed below:

Ad event Description
willPresentFullScreenView Notifies the Google Mobile Ads SDK that the ad will be displayed.
didStartVideo Notifies the Google Mobile Ads SDK that a rewarded ad started playing.
reportImpression Notifies the Google Mobile Ads SDK that an impression occurred on the ad.
didEndVideo Notifies the Google Mobile Ads SDK that the rewarded ad finished playing.
didRewardUserWithReward Notifies the Google Mobile Ads SDK that the user has earned a reward.
reportClick Notifies the Google Mobile Ads SDK that the ad has been clicked.
willDismissFullScreenView Notifies the Google Mobile Ads SDK that the ad will be dismissed.
didDismissFullScreenView Notifies the Google Mobile Ads SDK that the ad has been dismissed.