This guide is intended for publishers looking to use AdMob mediation to show rewarded ads from a network that is not directly supported in the AdMob UI.
Rewarded ad custom events allow you to write a custom mediation adapter to display rewarded ads from a third-party ad network. In this guide, we'll walk through how to write a custom event to request ads from a sample SDK we developed. You can find the full source for the sample SDK on GitHub.
Prerequisites
Before you can integrate custom events, you need to integrate the rewarded ads format. For instructions to integrate the rewarded ads format, refer to the Rewarded Ads guide.
Creating a custom event
To define a custom event, you must first create it in the AdMob UI. You can find instructions for creating a custom event in Add a custom event.
Once defined, the custom event adapter points to a class within your app that
implements the GADMediationAdapter
protocol to serve a rewarded ad. The custom event also lists a server parameter
that is passed to your rewarded adapter.
Here is a screenshot showing some sample custom event settings:
The screenshot has the following entries:
- Class Name
- The fully-qualified name of the class that implements the custom event adapter.
- Label
- A unique name defining the ad source.
- Parameter
- An optional string argument passed to your custom event adapter.
Implementing the custom event
A custom event is a class that implements the GADMediationAdapter
protocol to
serve third-party ads. The steps below implement a custom event to request and
display rewarded ads from the
Sample Ad Network.
Implement GADMediationAdapter
The first step to creating a custom event is to implement the
GADMediationAdapter
protocol, as done by the
GADMediationAdapterSampleAdNetwork
class below:
#import <Foundation/Foundation.h>
@import GoogleMobileAds;
@interface GADMediationAdapterSampleAdNetwork : NSObject <GADMediationAdapter>
@end
Report extras class
If the custom event supports extras to specify additional parameters for an ad
request, the extras
class must be returned from the networkExtrasClass
method.
Return Nil
if the custom event doesn't support publisher provided extras.
#import "GADMediationAdapterSampleAdNetwork.h"
@implementation GADMediationAdapterSampleAdNetwork
...
+ (nullable Class<GADAdNetworkExtras>)networkExtrasClass {
return Nil;
}
...
@end
Report version numbers
All custom events must report to the Google Mobile Ads SDK both the version of
the custom event itself and the version of the third-party SDK the custom event
interfaces with. Versions are reported as GADVersionNumber
:
#import "GADMediationAdapterSampleAdNetwork.h"
@implementation GADMediationAdapterSampleAdNetwork
...
+ (GADVersionNumber)adSDKVersion {
NSString *versionString = @"1.0.0";
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 = @"1.0.0.0";
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
Request a rewarded ad
Requests made by your app to load a rewarded ad invoke the
loadRewardedAdForAdConfiguration:completionHandler:
method of the custom
event.
Report a successful ad load to the Google Mobile Ads SDK by invoking the provided
completionHandler with a reference to an object that implements
GADMediationRewardedAd
. This invocation returns a
GADMediationRewardedAdEventDelegate
. Custom events should maintain reference
to this object to notify the Google Mobile Ads SDK of ad lifecycle events. This is shown in
further detail in the Show the ad section.
To report an ad load error, invoke the provided completionHandler with an
NSError
object.
Here's an example implementation of
loadRewardedAdForAdConfiguration:completionHandler:
:
#import "GADMediationAdapterSampleAdNetwork.h"
@interface GADMediationAdapterSampleAdNetwork () <GADMediationRewardedAd> {
/// Reward-based video ads from Sample SDK.
SampleRewardBasedVideo *_rewardBasedVideoAd;
}
@property(nonatomic, weak, nullable) id<GADMediationRewardedAdEventDelegate> delegate;
@end
@implementation GADMediationAdapterSampleAdNetwork
...
- (void)loadRewardedAdForAdConfiguration:(GADMediationRewardedAdConfiguration *)adConfiguration
completionHandler:(GADRewardedLoadCompletionHandler)completionHandler {
// Look for the "parameter" key to fetch the parameter you defined in the AdMob UI.
NSString *adUnit = adConfiguration.credentials.settings[@"parameter"];
SampleAdRequest *request = [[SampleAdRequest alloc] init];
[SampleAdNetwork loadAdWithRequest:request
completionHandler:^(SampleRewardBasedVideo *ad ,NSError *error) {
if (error) {
completionHandler(nil, error);
return;
}
_rewardBasedVideoAd = ad;
self.delegate = completionHandler(self, nil);
}];
}
...
@end
Show the ad
When the app asks the Google Mobile Ads SDK to present the rewarded ad, the SDK
calls the presentFromViewController:
method on your instance of
GADMediationRewardedAd
. Implement this method to show the rewarded ad.
- (void)presentFromViewController:(nonnull UIViewController *)viewController {
if ([_rewardBasedVideoAd checkAdAvailability]) {
// The reward based video ad is available, present the ad.
[_rewardBasedVideoAd presentFromRootViewController:viewController];
} else {
NSError *error =
[NSError errorWithDomain:@"GADMediationAdapterSampleAdNetwork"
code:0
userInfo:@{NSLocalizedDescriptionKey : @"Unable to display ad."}];
[self.delegate didFailToPresentWithError:error];
}
}
Report ad events
After displaying the ad, the custom event should report ad lifecycle events as
appropriate to the Google Mobile Ads SDK using the GADMediationRewardedAdEventDelegate
provided at successful ad load time.
- (void)rewardBasedVideoAdDidOpen:(SampleRewardBasedVideo *)rewardBasedVideo {
[self.delegate willPresentFullScreenView];
[self.delegate reportImpression];
}
- (void)rewardBasedVideoAdDidStartPlaying:(SampleRewardBasedVideo *)rewardBasedVideo {
[self.delegate didStartVideo];
}
- (void)rewardBasedVideoAdDidStopPlaying:(SampleRewardBasedVideo *)rewardBasedVideo {
[self.delegate didEndVideo];
}
- (void)rewardBasedVideoAdDidClose:(SampleRewardBasedVideo *)rewardBasedVideo {
[self.delegate willDismissFullScreenView];
}
- (void)rewardBasedVideoAdDidReceiveAdClick:(SampleRewardBasedVideo *)rewardBasedVideo {
[self.delegate reportClick];
}
- (void)rewardedAd:(nonnull SampleRewardedAd *)rewardedAd userDidEarnReward:(NSUInteger)reward {
GADAdReward *aReward =
[[GADAdReward alloc] initWithRewardType:@""
rewardAmount:[NSDecimalNumber numberWithUnsignedInt:reward]];
[self.delegate didRewardUserWithReward:aReward];
}
}
The ad events that must 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. |