Rewarded Ads Custom Events

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.