Rewarded Ads Custom Events (Beta)

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 Rewarded Ads Beta.

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. The custom event class name defines the class in your app that must implement the Adapter interface to serve a rewarded ad. The custom event parameter defined in the AdMob UI is passed to the adapter when it's asked to load an ad.

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

Initialize the adapter

Upon an app's initialization of the Google Mobile Ads SDK, setUpWithConfiguration:completionHandler: is invoked on all adapters and custom events configured for the app within the AdMob UI. Custom events should perform any required initialization or set up for the third-party ads SDK within this method.

The GADMediationServerConfiguration argument provides information on all placements configured for the app within the AdMob UI.

Report either a successful or failed initialization to the Google Mobile Ads SDK by invoking the GADMediationAdapterSetUpCompletionBlock argument provided in the setUpWithConfiguration:completionHandler: call. Invoke the completion handler with nil to indicate successful initialization. Providing an NSError object to the completion handler reports failed initialization.

The following code snippet initializes the Sample Ads SDK, preparing it to handle ad requests:

#import "GADMediationAdapterSampleAdNetwork.h"

@implementation GADMediationAdapterSampleAdNetwork

+ (void)setUpWithConfiguration:(GADMediationServerConfiguration *)configuration
             completionHandler:(GADMediationAdapterSetUpCompletionBlock)completionHandler {
  NSMutableArray<NSString *> *adUnitIDs = [[NSMutableArray alloc] init];
  for (GADMediationCredentials *credential in configuration.credentials) {
    if (credential.format == GADAdFormatRewarded) {
      [adUnitIDs addObject:credential.settings[@"adUnitID"]];
    }
  }
  if ([adUnitIDs count] == 0) {
    NSError *error =
        [NSError errorWithDomain:@"GADMediationAdapterSampleAdNetwork"
                            code:0
                        userInfo:@{NSLocalizedDescriptionKey : @"No adUnitIDs specified."}];
    completionHandler(error);
    return;
  }
  [SampleAdNetwork initWithCompletionHandler:^(NSError *error) {
    if (error) {
      completionHandler(error);
      return;
    }
    completionHandler(nil);
  }];
}
@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 {
  NSString *adUnit = adConfiguration.credentials.settings[@"ad_unit"];
  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.delgate willPresentFullScreenView];
  [self.delgate reportImpression];
}

- (void)rewardBasedVideoAdDidStartPlaying:(SampleRewardBasedVideo *)rewardBasedVideo {
  [self.delgate didStartVideo];
}

- (void)rewardBasedVideoAdDidStopPlaying:(SampleRewardBasedVideo *)rewardBasedVideo {
  [self.delgate didEndVideo];
}

- (void)rewardBasedVideoAdDidClose:(SampleRewardBasedVideo *)rewardBasedVideo {
  [self.delgate willDismissFullScreenView];
}

- (void)rewardBasedVideoAdDidReceiveAdClick:(SampleRewardBasedVideo *)rewardBasedVideo {
  [self.delgate reportClick];
}

- (void)rewardBasedVideoAd:(SampleRewardBasedVideo *)rewardBasedVideo
      rewardUserWithReward:(int)reward {
  [[GADAdReward alloc] initWithRewardType:@"SampleAdReward"
                             rewardAmount:[NSDecimalNumber decimalNumberWithString:@"1"]];
  [strongDelegate didRewardUserWithReward:reward];
}

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.

Send feedback about...

This page
Documentation feedback
iOS
iOS
Product feedback
Need help? Visit our support page.