Banner ads custom events

    • Implementing banner custom events requires completing the custom events setup and modifying classes to implement GADMediationAdapter and GADMediationBannerAd .

    • The loadBanner:adConfiguration:completionHandler: method is crucial for requesting banner ads within the mediation chain.

    • SampleCustomEventBanner is responsible for loading the ad, implementing GADMediationBannerAd , and reporting ad event callbacks.

    • The optional parameter from the Ad Manager UI, often an ad unit identifier, can be accessed via adConfiguration.credentials.settings[@"parameter"] .

    • Forwarding mediation events from the third-party SDK to Google Mobile Ads SDK using the GADMediationBannerAdEventDelegate is important for app callback consistency.
    Select platform: Android (beta)New 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

     import 
  
 GoogleMobileAds 
 class 
  
 SampleCustomEvent 
 : 
  
 NSObject 
 , 
  
 MediationAdapter 
  
 { 
  
 fileprivate 
  
 var 
  
 bannerAd 
 : 
  
 SampleCustomEventBanner 
 ? 
  
 ... 
  
 func 
  
 loadBanner 
 ( 
  
 for 
  
 adConfiguration 
 : 
  
 MediationBannerAdConfiguration 
 , 
  
 completionHandler 
 : 
  
 @ 
 escaping 
  
 GADMediationBannerLoadCompletionHandler 
  
 ) 
  
 { 
  
 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 
  
 = 
  
 [[ 
 SampleCustomEventBanner 
  
 alloc 
 ] 
  
 init 
 ]; 
  
 [ 
 sampleBanner 
  
 loadBannerForAdConfiguration 
 : 
 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 Ad Manager 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

     class 
  
 SampleCustomEventBanner 
 : 
  
 NSObject 
 , 
  
 MediationBannerAd 
  
 { 
  
 /// The Sample Ad Network banner ad. 
  
 var 
  
 bannerAd 
 : 
  
 SampleBanner 
 ? 
  
 /// The ad event delegate to forward ad rendering events to Google Mobile Ads SDK 
. 
  
 var 
  
 delegate 
 : 
  
 MediationBannerAdEventDelegate 
 ? 
  
 /// Completion handler called after ad load 
  
 var 
  
 completionHandler 
 : 
  
 GADMediationBannerLoadCompletionHandler 
 ? 
  
 func 
  
 loadBanner 
 ( 
  
 for 
  
 adConfiguration 
 : 
  
 MediationBannerAdConfiguration 
 , 
  
 completionHandler 
 : 
  
 @ 
 escaping 
  
 GADMediationBannerLoadCompletionHandler 
  
 ) 
  
 { 
  
 // Create the bannerView with the appropriate size. 
  
 let 
  
 adSize 
  
 = 
  
 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 
  
 let 
  
 adRequest 
  
 = 
  
 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 
  
 { 
  
 __block 
  
 atomic_flag 
  
 completionHandlerCalled 
  
 = 
  
 ATOMIC_FLAG_INIT 
 ; 
  
 __block 
  
 GADMediationBannerLoadCompletionHandler 
  
 originalCompletionHandler 
  
 = 
  
 [ 
 completionHandler 
  
 copy 
 ]; 
  
 _loadCompletionHandler 
  
 = 
  
 ^ 
 id<GADMediationBannerAdEventDelegate 
 > 
 ( 
  
 _Nullable 
  
 id<GADMediationBannerAd 
 > 
  
 ad 
 , 
  
 NSError 
  
 * 
 _Nullable 
  
 error 
 ) 
  
 { 
  
 // Only allow completion handler to be called once. 
  
 if 
  
 ( 
 atomic_flag_test_and_set 
 ( 
 & 
 completionHandlerCalled 
 )) 
  
 { 
  
 return 
  
 nil 
 ; 
  
 } 
  
 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 
 ; 
  
 return 
  
 delegate 
 ; 
  
 }; 
  
 NSString 
  
 * 
 adUnit 
  
 = 
  
 adConfiguration 
 . 
 credentials 
 . 
 settings 
 [ 
 @"parameter" 
 ]; 
  
 _bannerAd 
  
 = 
  
 [[ 
 SampleBanner 
  
 alloc 
 ] 
  
 initWithFrame 
 : 
 CGRectMake 
 ( 
 0 
 , 
  
 0 
 , 
  
 adConfiguration 
 . 
 adSize 
 . 
 size 
 . 
 width 
 , 
  
 adConfiguration 
 . 
 adSize 
 . 
 size 
 . 
 height 
 )]; 
  
 _bannerAd 
 . 
 adUnit 
  
 = 
  
 adUnit 
 ; 
  
 _bannerAd 
 . 
 delegate 
  
 = 
  
 self 
 ; 
  
 SampleAdRequest 
  
 * 
 adRequest 
  
 = 
  
 [[ 
 SampleAdRequest 
  
 alloc 
 ] 
  
 init 
 ]; 
  
 adRequest 
 . 
 testMode 
  
 = 
  
 adConfiguration 
 . 
 isTestRequest 
 ; 
  
 [ 
 _bannerAd 
  
 fetchAd 
 : 
 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

     func 
  
 bannerDidLoad 
 ( 
 _ 
  
 banner 
 : 
  
 SampleBanner 
 ) 
  
 { 
  
 if 
  
 let 
  
 handler 
  
 = 
  
 completionHandler 
  
 { 
  
 delegate 
  
 = 
  
 handler 
 ( 
 self 
 , 
  
 nil 
 ) 
  
 } 
 } 
 func 
  
 banner 
 ( 
  
 _ 
  
 banner 
 : 
  
 SampleBanner 
 , 
  
 didFailToLoadAdWith 
  
 errorCode 
 : 
  
 SampleErrorCode 
 ) 
  
 { 
  
 let 
  
 error 
  
 = 
  
 SampleCustomEventUtilsSwift 
 . 
 SampleCustomEventErrorWithCodeAndDescription 
 ( 
  
 code 
 : 
  
 SampleCustomEventErrorCodeSwift 
  
 . 
 SampleCustomEventErrorAdLoadFailureCallback 
 , 
  
 description 
 : 
  
 "Sample SDK returned an ad load failure callback with error code: 
 \( 
 errorCode 
 ) 
 " 
  
 ) 
  
 if 
  
 let 
  
 handler 
  
 = 
  
 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 
 , 
  
 [ 
 NSString 
  
 stringWithFormat 
 : 
 @"Sample SDK returned an ad load failure " 
  
 @"callback with error code: %@" 
 , 
  
 errorCode 
 ]); 
  
 _adEventDelegate 
  
 = 
  
 _loadCompletionHandler 
 ( 
 nil 
 , 
  
 error 
 ); 
 }

    GADMediationBannerAd requires implementing a UIView property:

    Swift

     var 
  
 view 
 : 
  
 UIView 
  
 { 
  
 return 
  
 bannerAd 
  
 ?? 
  
 UIView 
 () 
 }

    Objective-C

     - 
 ( 
 nonnull 
  
 UIView 
  
 * 
 ) 
 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

     func 
  
 bannerWillLeaveApplication 
 ( 
 _ 
  
 banner 
 : 
  
 SampleBanner 
 ) 
  
 { 
  
 delegate 
 ?. 
 reportClick 
 () 
 }

    Objective-C

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

    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.
    Design a Mobile Site
    View Site in Mobile | Classic
    Share by: