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 supply Google with your adapter class name and other required parameters to gain access for 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:GADErrorNoFill
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. |