Custom Events

This guide is intended for publishers looking to add support for banner and interstitial custom events within AdMob mediation. Custom events allow you to put any view you want into your ad space. Through custom events, you can also monetize your application with ad networks not directly supported by mediation. A custom event is implemented through either the GADCustomEventBanner or the GADCustomEventInterstitial protocol.

Prerequisites

• Complete the Get Started guide.
• You may also want to read about making an AdRequest and how mediation works.

Sample Ad Network

This guide demonstrates how to serve banners and interstitials from the Sample Ad Network using the SampleCustomEventBanner and SampleCustomEventInterstital custom event classes. The Sample Ad Network SDK is a mock SDK developed for the purpose of showing off what a real-life implementation of a custom event would look like. The SDK contains classes that are representative of the classes offered by most ad networks. See the complete sample SDK implementation for more information about these classes.

Define a custom event

Custom events must be defined in the AdMob interface. Create a custom event provides instructions.

Follow this procedure to define a custom event:

1. Navigate to the Custom Event screen.

   

2. Fill in the fields on the screen as follows:

   Class Name	Enter the fully qualified name of the class that implements the custom event.
   Label	Enter a unique name for the event.
   Parameter	If you wish to pass an argument to your custom event, enter the appropriate string.

   Banner custom event

   In the following example, you first create a banner custom event within AdMob mediation. This requires defining a custom event that points to that specific class in your application through the AdMob interface, then implementing a banner custom event to return a view.

   Request a banner

   For custom event banner requests, the requestBannerAd:parameter:label:request: method is called immediately after the custom event class is instantiated. This method does not return anything. The assumption is that the adapter will start an asynchronous ad fetch over the network. Your custom event should act as a delegate to your SDK to listen to callbacks.

   If your SDK does not support the given ad size or does not support banner ads, call the customEventBanner:didFailAd: method of the custom event delegate. The serverParameter and serverLabel parameters correspond to the parameter and label fields defined when creating a custom event in the AdMob front end.

   Here is an example implementation of requestBannerAd:parameter:label:request: using the Sample Ad Network:

   Objective-C

   - (void)requestBannerAd:(GADAdSize)adSize
                 parameter:(NSString *)serverParameter
                     label:(NSString *)serverLabel
                   request:(GADCustomEventRequest *)request {
     // Create the bannerView with the appropriate size.
     self.bannerAd =
         [[SampleBanner alloc] initWithFrame:CGRectMake(0,
                                                        0,
                                                        adSize.size.width,
                                                        adSize.size.height)];
   
     self.bannerAd.delegate = self;
     self.bannerAd.adUnit = serverParameter;
     SampleAdRequest *adRequest = [[SampleAdRequest alloc] init];
     adRequest.testMode = request.isTesting;
     adRequest.keywords = request.userKeywords;
     [self.bannerAd fetchAd:adRequest];
   }
   

   Swift

   func requestBannerAd(adSize: GADAdSize, parameter serverParameter: String!,
       label serverLabel: String!, request: GADCustomEventRequest!) {
     // Create a banner view with the appropriate size.
     bannerAd = SampleBanner(frame: CGRectMake(
         0, 0, adSize.size.width, adSize.size.height))
     bannerAd.delegate = self
     bannerAd.adUnit = serverParameter
     let adRequest = SampleAdRequest()
     adRequest.testMode = request.isTesting
     adRequest.keywords = request.userKeywords
     bannerAd.fetchAd(adRequest)
   }
   

   Your custom event must notify mediation via the custom event's delegate when it receives or fails to receive an ad. Otherwise, the custom event times out, and mediation moves on to the next network.

   Notify AdMob mediation

   Implement the ad listener for your network and invoke the relevant callbacks on the custom event's delegate to send messages back to mediation. The following example implements the Sample Ad Network's SampleBannerAdDelegate interface to send these messages:

   Objective-C

   /// Constant for Sample Ad Network custom event error domain.
   static NSString *const customEventErrorDomain = @"com.google.CustomEvent";
   
   // Sent when banner ad has loaded.
   - (void)bannerDidLoad:(SampleBanner *)banner {
     [self.delegate customEventBanner:self didReceiveAd:banner];
   }
   
   // Sent when banner has failed to load.
   - (void)banner:(SampleBanner *)banner
       didFailToLoadAdWithErrorCode:(SampleErrorCode)errorCode {
     NSError *error = [NSError errorWithDomain:customEventErrorDomain
                                          code:errorCode
                                      userInfo:nil];
     [self.delegate customEventBanner:self didFailAd:error];
   }
   
   // Sent when a banner is clicked and an external application is launched.
   - (void)bannerWillLeaveApplication:(SampleBanner *)banner {
     [self.delegate customEventBannerWasClicked:self];
     [self.delegate customEventBannerWillLeaveApplication:self];
   }
   

   Swift

   /// Type property for Sample Ad Network custom event error domain.
   static let customEventErrorDomain = "com.google.CustomEvent"
   
   // Sent when banner ad has loaded.
   func bannerDidLoad(banner: SampleBanner!) {
     delegate.customEventBanner(self, didReceiveAd: banner)
   }
   
   // Sent when banner has failed to load.
   func banner(banner: SampleBanner!, didFailToLoadAdWithErrorCode error: SampleErrorCode) {
     let nsError = NSError(domain: SampleCustomEventBanner.customEventErrorDomain,
         code: error.rawValue, userInfo: nil)
     delegate.customEventBanner(self, didFailAd: nsError)
   }
   
   // Sent when a banner is clicked and an external application is launched
   func bannerWillLeaveApplication(banner: SampleBanner!) {
     delegate.customEventBannerWasClicked(self)
     delegate.customEventBannerWillLeaveApplication(self)
   }
   

   See the sample implementation of a custom event banner for more information.

   Interstitial custom event

   The implementation of an interstitial custom event is similar to that of a banner custom event. The main difference is that the interstitial custom event class you create should implement the GADCustomEventInterstitial protocol instead of the GADCustomEventBanner protocol.

   Request an interstitial

   For custom event interstitial requests, the requestInterstitialAdWithParameter:label:request: method is called immediately after the custom event class is instantiated. This method does not return anything. The assumption is that the adapter will start an asynchronous ad fetch over the network. Your custom event should act as a delegate to your SDK to listen to callbacks. The serverParameter and serverLabel parameters correspond to the parameter and label fields defined when creating a custom event in the AdMob front end.

   Here is an example implementation of requestInterstitialAdWithParameter:label:request: using the Sample Ad Network:

   Objective-C

   - (void)requestInterstitialAdWithParameter:(NSString *)serverParameter
                                        label:(NSString *)serverLabel
                                      request:(GADCustomEventRequest *)request {
     self.interstitial = [[SampleInterstitial alloc] init];
     self.interstitial.delegate = self;
     self.interstitial.adUnit = serverParameter;
     SampleAdRequest *adRequest = [[SampleAdRequest alloc] init];
     adRequest.testMode = request.isTesting;
     adRequest.keywords = request.userKeywords;
     [self.interstitial fetchAd:adRequest];
   }
   

   Swift

   func requestInterstitialAdWithParameter(serverParameter: String!,
       label serverLabel: String!, request: GADCustomEventRequest!) {
     interstitial = SampleInterstitial()
     interstitial.delegate = self
     interstitial.adUnit = serverParameter
     let adRequest = SampleAdRequest()
     adRequest.testMode = request.isTesting
     adRequest.keywords = request.userKeywords
     interstitial.fetchAd(adRequest)
   }
   

   The GADCustomEventInterstitial custom event protocol requires you to implement the presentFromRootViewController: method. Mediation invokes this method when you tell the Mobile Ads SDK to show the interstitial as follows:

   Objective-C

   - (void)presentFromRootViewController:(UIViewController *)rootViewController {
     if ([self.interstitial isInterstitialLoaded]) {
       [self.interstitial show];
     }
   }
   

   Swift

   func presentFromRootViewController(rootViewController: UIViewController!) {
     if interstitial.interstitialLoaded {
       interstitial.show()
     }
   }
   

   Notify AdMob mediation

   Just as with the banner custom event, implement your network's ad listener to send messages back to mediation. The following example shows the implementation of the Sample Ad Network's SampleInterstitialAdDelegate interface:

   Objective-C

   /// Constant for Sample Ad Network custom event error domain.
   static NSString *const customEventErrorDomain = @"com.google.CustomEvent";
   
   // Sent when an interstitial ad has loaded.
   - (void)interstitialDidLoad:(SampleInterstitial *)interstitial {
     [self.delegate customEventInterstitialDidReceiveAd:self];
   }
   
   // Sent when an interstitial ad has failed to load.
   - (void)interstitial:(SampleInterstitial *)interstitial
       didFailToLoadAdWithErrorCode:(SampleErrorCode)errorCode {
     NSError *error = [NSError errorWithDomain:customEventErrorDomain
                                          code:errorCode
                                      userInfo:nil];
     [self.delegate customEventInterstitial:self didFailAd:error];
   }
   
   // Sent when an interstitial is about to be shown.
   - (void)interstitialWillPresentScreen:(SampleInterstitial *)interstitial {
     [self.delegate customEventInterstitialWillPresent:self];
   }
   
   // Sent when an interstitial is about to be dismissed.
   - (void)interstitialWillDismissScreen:(SampleInterstitial *)interstitial {
     [self.delegate customEventInterstitialWillDismiss:self];
   }
   
   // Sent when an interstitial has been dismissed.
   - (void)interstitialDidDismissScreen:(SampleInterstitial *)interstitial {
     [self.delegate customEventInterstitialDidDismiss:self];
   }
   
   // Sent when an interstitial is clicked and an external application is launched.
   - (void)interstitialWillLeaveApplication:(SampleInterstitial *)interstitial {
     [self.delegate customEventInterstitialWasClicked:self];
     [self.delegate customEventInterstitialWillLeaveApplication:self];
   }
   

   Swift

   /// Type property for Sample Ad Network custom event error domain.
   static let customEventErrorDomain = "com.google.CustomEvent"
   
   // Sent when an interstitial ad has loaded.
   func interstitialDidLoad(interstitial: SampleInterstitial!) {
     delegate.customEventInterstitialDidReceiveAd(self)
   }
   
   // Sent when interstitial ad has failed to load.
   func interstitial(interstitial: SampleInterstitial!,
       didFailToLoadAdWithErrorCode errorCode: SampleErrorCode) {
     let nsError = NSError(domain: SampleCustomEventInterstitial.customEventErrorDomain,
         code: errorCode.rawValue, userInfo: nil)
     delegate.customEventInterstitial(self, didFailAd: nsError)
   }
   
   // Sent when an interstitial is about to be shown.
   func interstitialWillPresentScreen(interstitial: SampleInterstitial!) {
     delegate.customEventInterstitialWillPresent(self)
   }
   
   // Sent when an interstitial is about to be dismissed.
   func interstitialWillDismissScreen(interstitial: SampleInterstitial!) {
     delegate.customEventInterstitialWillDismiss(self)
   }
   
   // Sent when an interstitial has been dismissed.
   func interstitialDidDismissScreen(interstitial: SampleInterstitial!) {
     delegate.customEventInterstitialDidDismiss(self)
   }
   
   // Sent when an interstitial is clicked and an external application is launched.
   func interstitialWillLeaveApplication(interstitial: SampleInterstitial!) {
     delegate.customEventInterstitialWasClicked(self)
     delegate.customEventInterstitialWillLeaveApplication(self)
   }
   

   Sending messages back to mediation allows it to continue the mediation flow.

   See the sample implementation of an interstitial custom event for more information.