To discuss and provide feedback on our products, join the official AdMob Discord channel in the Google Advertising and Measurement Community server.

Banner ads custom events

  • To request a banner ad using custom events, create a class that implements GADMediationAdapter and loadBanner:adConfiguration:completionHandler:.

  • SampleCustomEventBanner is responsible for loading banner ads, implementing the GADMediationBannerAd protocol, and reporting ad events to the Google Mobile Ads SDK.

  • AdMob UI parameters can be accessed in your code using adConfiguration.credentials.settings[@"parameter"].

  • You need to forward mediation events from the third-party SDK to the Google Mobile Ads SDK by using GADMediationBannerAdEventDelegate.

  • A full example implementation of banner custom events is available on GitHub for reference or modification.
Select platform: Android iOS

Prerequisites

Complete the custom events setup.

Request a banner ad

When the custom event line item is reached in the waterfall mediation chain, the loadBanner:adConfiguration:completionHandler: method is called on the class name you provided when creating a custom event. In this case, that method is in SampleCustomEvent, which then calls the loadBanner:adConfiguration:completionHandler: method in SampleCustomEventBanner.

To request a banner ad, create or modify a class that implements GADMediationAdapter and loadBanner:adConfiguration:completionHandler:. If a class that extends GADMediationAdapter already exists, implement loadBanner:adConfiguration:completionHandler: there. Additionally, create a new class to implement GADMediationBannerAd.

In our custom event example, SampleCustomEvent implements the GADMediationAdapter interface and then delegates to SampleCustomEventBanner.

Swift

importGoogleMobileAds
classSampleCustomEvent:NSObject,MediationAdapter{
fileprivatevarbannerAd:SampleCustomEventBanner?
...
funcloadBanner(
foradConfiguration:MediationBannerAdConfiguration,
completionHandler:@escapingGADMediationBannerLoadCompletionHandler
){
self.bannerAd=SampleCustomEventBanner()
self.bannerAd?.loadBanner(
for:adConfiguration,completionHandler:completionHandler)
}
}

Objective-C

#import "SampleCustomEvent.h"
@implementation SampleCustomEvent
...
SampleCustomEventBanner*sampleBanner;
- (void)loadBannerForAdConfiguration:
(GADMediationBannerAdConfiguration*)adConfiguration
completionHandler:(GADMediationBannerLoadCompletionHandler)
 completionHandler{
sampleBanner=[[SampleCustomEventBanneralloc]init];
[sampleBannerloadBannerForAdConfiguration:adConfiguration
completionHandler:completionHandler];
}

SampleCustomEventBanner is responsible for the following tasks:

  • Loading the banner ad and invoking a GADMediationBannerLoadCompletionHandler method once loading completes.

  • Implementing the GADMediationBannerAd protocol.

  • Receiving and reporting ad event callbacks to Google Mobile Ads SDK.

The optional parameter defined in the AdMob UI is included in the ad configuration. The parameter can be accessed through adConfiguration.credentials.settings[@"parameter"]. This parameter is typically an ad unit identifier that an ad network SDK requires when instantiating an ad object.

Swift

classSampleCustomEventBanner:NSObject,MediationBannerAd{
/// The Sample Ad Network banner ad.
varbannerAd:SampleBanner?
/// The ad event delegate to forward ad rendering events to Google Mobile Ads SDK.
vardelegate:MediationBannerAdEventDelegate?
/// Completion handler called after ad load
varcompletionHandler:GADMediationBannerLoadCompletionHandler?
funcloadBanner(
foradConfiguration:MediationBannerAdConfiguration,
completionHandler:@escapingGADMediationBannerLoadCompletionHandler
){
// Create the bannerView with the appropriate size.
letadSize=adConfiguration.adSize
bannerAd=SampleBanner(
frame:CGRect(x:0,y:0,width:adSize.size.width,height:adSize.size.height))
bannerAd?.delegate=self
bannerAd?.adUnit=adConfiguration.credentials.settings["parameter"]as?String
letadRequest=SampleAdRequest()
adRequest.testMode=adConfiguration.isTestRequest
self.completionHandler=completionHandler
bannerAd?.fetchAd(adRequest)
}
}

Objective-C

#import "SampleCustomEventBanner.h"
@interface SampleCustomEventBanner()<SampleBannerAdDelegate,
GADMediationBannerAd>{
/// The sample banner ad.
SampleBanner*_bannerAd;
/// The completion handler to call when the ad loading succeeds or fails.
GADMediationBannerLoadCompletionHandler_loadCompletionHandler;
/// The ad event delegate to forward ad rendering events to the Google Mobile
/// Ads SDK.
id<GADMediationBannerAdEventDelegate>_adEventDelegate;
}
@end
@implementation SampleCustomEventBanner
- (void)loadBannerForAdConfiguration:
(GADMediationBannerAdConfiguration*)adConfiguration
completionHandler:(GADMediationBannerLoadCompletionHandler)
 completionHandler{
__blockatomic_flagcompletionHandlerCalled=ATOMIC_FLAG_INIT;
__blockGADMediationBannerLoadCompletionHandleroriginalCompletionHandler=
[completionHandlercopy];
_loadCompletionHandler=^id<GADMediationBannerAdEventDelegate>(
_Nullableid<GADMediationBannerAd>ad,NSError*_Nullableerror){
// Only allow completion handler to be called once.
if(atomic_flag_test_and_set(&completionHandlerCalled)){
returnnil;
}
id<GADMediationBannerAdEventDelegate>delegate=nil;
if(originalCompletionHandler){
// Call original handler and hold on to its return value.
delegate=originalCompletionHandler(ad,error);
}
// Release reference to handler. Objects retained by the handler will also
// be released.
originalCompletionHandler=nil;
returndelegate;
};
NSString*adUnit=adConfiguration.credentials.settings[@"parameter"];
_bannerAd=[[SampleBanneralloc]
initWithFrame:CGRectMake(0,0,adConfiguration.adSize.size.width,
adConfiguration.adSize.size.height)];
_bannerAd.adUnit=adUnit;
_bannerAd.delegate=self;
SampleAdRequest*adRequest=[[SampleAdRequestalloc]init];
adRequest.testMode=adConfiguration.isTestRequest;
[_bannerAdfetchAd:adRequest];
}

Whether the ad is successfully fetched or encounters an error, you would call GADMediationBannerLoadCompletionHandler. In the event of success, pass through the class that implements GADMediationBannerAd with a nil value for the error parameter; in the event of failure, pass through the error you encountered.

Typically, these methods are implemented inside callbacks from the third-party SDK your adapter implements. For this example, the Sample SDK has a SampleBannerAdDelegate with relevant callbacks:

Swift

funcbannerDidLoad(_banner:SampleBanner){
iflethandler=completionHandler{
delegate=handler(self,nil)
}
}
funcbanner(
_banner:SampleBanner,didFailToLoadAdWitherrorCode:SampleErrorCode
){
leterror=
SampleCustomEventUtilsSwift.SampleCustomEventErrorWithCodeAndDescription(
code:SampleCustomEventErrorCodeSwift
.SampleCustomEventErrorAdLoadFailureCallback,
description:
"Sample SDK returned an ad load failure callback with error code: \(errorCode)"
)
iflethandler=completionHandler{
delegate=handler(nil,error)
}
}

Objective-C

- (void)bannerDidLoad:(SampleBanner*)banner{
_adEventDelegate=_loadCompletionHandler(self,nil);
}
- (void)banner:(SampleBanner*)banner
didFailToLoadAdWithErrorCode:(SampleErrorCode)errorCode{
NSError*error=SampleCustomEventErrorWithCodeAndDescription(
SampleCustomEventErrorAdLoadFailureCallback,
[NSStringstringWithFormat:@"Sample SDK returned an ad load failure "
@"callback with error code: %@",
errorCode]);
_adEventDelegate=_loadCompletionHandler(nil,error);
}

GADMediationBannerAd requires implementing a UIView property:

Swift

varview:UIView{
returnbannerAd??UIView()
}

Objective-C

- (nonnullUIView*)view{
return_bannerAd;
}

Forward mediation events to Google Mobile Ads SDK

Once you've called GADMediationBannerLoadCompletionHandler with a loaded ad, the returned GADMediationBannerAdEventDelegate delegate object can then be used by the adapter to forward presentation events from the third-party SDK to Google Mobile Ads SDK. The SampleCustomEventBanner class implements the SampleBannerAdDelegate protocol to forward callbacks from the sample ad network to Google Mobile Ads SDK.

It's important that your custom event forwards as many of these callbacks as possible, so that your app receives these equivalent events from Google Mobile Ads SDK. Here's an example of using callbacks:

Swift

funcbannerWillLeaveApplication(_banner:SampleBanner){
delegate?.reportClick()
}

Objective-C

- (void)bannerWillLeaveApplication:(SampleBanner*)banner{
[_adEventDelegatereportClick];
}

This completes the custom events implementation for banner ads. The full example is available on GitHub. You can use it with an ad network that is already supported or modify it to display custom event banner ads.

Except as otherwise noted, the content of this page is licensed under the Creative Commons Attribution 4.0 License, and code samples are licensed under the Apache 2.0 License. For details, see the Google Developers Site Policies. Java is a registered trademark of Oracle and/or its affiliates.

Last updated 2025年10月14日 UTC.