Ad Events

This guide explains how to use GADBannerViewDelegate and GADInterstitialDelegate to listen for ad events for banner and interstitial ads. These events allow you to track lifecycle events such as when an ad is loaded or an ad causes the user to leave the app.

To see banner ad events in action, download the iOS API Demo app in Objective-C or Swift.

Download API Demo

Prerequisites

Complete the Get Started guide.

Helpful primers

You may want to read how to add interstitials to your project as motivation for using GADInterstitialDelegate to listen for interstitial ad events.

GADBannerViewDelegate implementation

Registering for banner events

To register for banner ad events, set the delegate property on GADBannerView to an object that implements the GADBannerViewDelegate protocol. Generally, the class that implements banner ads also acts as the delegate class, in which case, the delegate property can be set to self.

#import "GADBannerView.h"
#import "GADBannerViewDelegate.h"

@interface ViewController () <GADBannerViewDelegate>

@property(nonatomic, strong) GADBannerView *bannerView;

@end

@implementation ViewController

- (void)viewDidLoad {
  [super viewDidLoad];
  self.bannerView = [[GADBannerView alloc] initWithAdSize:kGADAdSizeBanner];
  self.bannerView.delegate = self;
}

import UIKit
import GoogleMobileAds

class ViewController: UIViewController, GADBannerViewDelegate {

  var bannerView: GADBannerView!

  override func viewDidLoad() {
    super.viewDidLoad()
    bannerView = GADBannerView(adSize: kGADAdSizeBanner)
    bannerView.delegate = self
  }
}

Implementing banner events

Each of the methods in GADBannerViewDelegate is marked as optional, so you only need to implement the methods you want. This example implements each method and logs a message to the console:

/// Tells the delegate an ad request loaded an ad.
- (void)adViewDidReceiveAd:(GADBannerView *)adView {
  NSLog(@"adViewDidReceiveAd");
}

/// Tells the delegate an ad request failed.
- (void)adView:(GADBannerView *)adView
    didFailToReceiveAdWithError:(GADRequestError *)error {
  NSLog(@"adView:didFailToReceiveAdWithError: %@", [error localizedDescription]);
}

/// Tells the delegate that a full screen view will be presented in response
/// to the user clicking on an ad.
- (void)adViewWillPresentScreen:(GADBannerView *)adView {
  NSLog(@"adViewWillPresentScreen");
}

/// Tells the delegate that the full screen view will be dismissed.
- (void)adViewWillDismissScreen:(GADBannerView *)adView {
  NSLog(@"adViewWillDismissScreen");
}

/// Tells the delegate that the full screen view has been dismissed.
- (void)adViewDidDismissScreen:(GADBannerView *)adView {
  NSLog(@"adViewDidDismissScreen");
}

/// Tells the delegate that a user click will open another app (such as
/// the App Store), backgrounding the current app.
- (void)adViewWillLeaveApplication:(GADBannerView *)adView {
  NSLog(@"adViewWillLeaveApplication");
}

/// Tells the delegate an ad request loaded an ad.
func adViewDidReceiveAd(bannerView: GADBannerView!) {
  print("adViewDidReceiveAd")
}

/// Tells the delegate an ad request failed.
func adView(bannerView: GADBannerView!,
    didFailToReceiveAdWithError error: GADRequestError!) {
  print("adView:didFailToReceiveAdWithError: \(error.localizedDescription)")
}

/// Tells the delegate that a full screen view will be presented in response
/// to the user clicking on an ad.
func adViewWillPresentScreen(bannerView: GADBannerView!) {
  print("adViewWillPresentScreen")
}

/// Tells the delegate that the full screen view will be dismissed.
func adViewWillDismissScreen(bannerView: GADBannerView!) {
  print("adViewWillDismissScreen")
}

/// Tells the delegate that the full screen view has been dismissed.
func adViewDidDismissScreen(bannerView: GADBannerView!) {
  print("adViewDidDismissScreen")
}

/// Tells the delegate that a user click will open another app (such as
/// the App Store), backgrounding the current app.
func adViewWillLeaveApplication(bannerView: GADBannerView!) {
  print("adViewWillLeaveApplication")
}

See the AdMob Ad Delegate example for an implementation of banner delegate methods in the iOS API Demo app.

Objective-C Swift

Use cases

Here are some example use cases for these ad event methods.

Adding a banner to the view hierarchy once an ad is received

You may choose to hold off on adding a GADBannerView to the view hierarchy until an ad is received. You can do this by listening for the adViewDidReceiveAd: event:

- (void)adViewDidReceiveAd:(GADBannerView *)adView {
  [self.view addSubview:adView];
}

func adViewDidReceiveAd(bannerView: GADBannerView!) {
  view.addSubview(bannerView)
}

The addSubview() method automatically removes a view from its parent if it already has one, so it's safe to make this call every time.

Animating a banner ad

You can also use the adViewDidReceiveAd event to animate a banner ad once it's returned as shown in the following example:

- (void)adViewDidReceiveAd:(GADBannerView *)adView {
  adView.alpha = 0;
  [UIView animateWithDuration:1.0 animations:^{
    adView.alpha = 1;
  }];
}

func adViewDidReceiveAd(bannerView: GADBannerView!) {
  bannerView.alpha = 0
  UIView.animateWithDuration(1, animations: {
    bannerView.alpha = 1
  })
}

Third-party analytics

The SDK automatically tracks clicks and impressions, but if you're also using a third-party analytics solution, you can also track each of the GADBannerViewDelegate calls separately.

Pausing and resuming the app

The GADBannerViewDelegate protocol has methods to notify you of events such as when a click causes an overlay to be presented or dismissed, or invokes an external browser. If you want to know that these events happened because of ads, then register for these GADBannerViewDelegate methods:

But to catch all types of overlay presentations or external browser invocations, not just ones that come from ad clicks, your app is better off listening for the equivalent methods on UIViewController or UIApplication. Here is a table showing the equivalent iOS methods that are invoked at the same time as GADBannerViewDelegate methods:

GADInterstitialDelegate implementation

Registering for interstitial events

To register for interstitial ad events, set the delegate property on GADInterstitial to an object that implements the GADInterstitialDelegate protocol. Generally, the class that implements interstitial ads also acts as the delegate class, in which case the delegate property can be set to self as follows:

#import "GADInterstitial.h"
#import "GADInterstitialDelegate.h"

@interface ViewController () <GADInterstitialDelegate>

@property(nonatomic, strong) GADInterstitial *interstitial;

@end

@implementation ViewController

- (void)viewDidLoad {
  [super viewDidLoad];
  self.interstitial = [[GADInterstitial alloc] initWithAdUnitID:"ca-app-pub-3940256099942544/4411468910"];
  self.interstitial.delegate = self;
}

import UIKit
import GoogleMobileAds

class ViewController: UIViewController, GADInterstitialDelegate {

  var interstitial: GADInterstitial!

  override func viewDidLoad() {
    super.viewDidLoad()
    interstitial = GADInterstitial(adUnitID: "ca-app-pub-3940256099942544/4411468910")
    interstitial.delegate = self
  }
}

Implementing interstitial events

Each of the methods in GADInterstitialDelegate are marked as optional, so you only need to implement the methods you want. This example implements each method and logs a message to the console:

/// Called when an interstitial ad request succeeded.
- (void)interstitialDidReceiveAd:(GADInterstitial *)ad {
  NSLog(@"interstitialDidReceiveAd");
}

/// Called when an interstitial ad request failed.
- (void)interstitial:(GADInterstitial *)ad
    didFailToReceiveAdWithError:(GADRequestError *)error {
  NSLog(@"interstitial:didFailToReceiveAdWithError: %@", [error localizedDescription]);
}

/// Called just before presenting an interstitial.
- (void)interstitialWillPresentScreen:(GADInterstitial *)ad {
  NSLog(@"interstitialWillPresentScreen");
}

/// Called before the interstitial is to be animated off the screen.
- (void)interstitialWillDismissScreen:(GADInterstitial *)ad {
  NSLog(@"interstitialWillDismissScreen");
}

/// Called just after dismissing an interstitial and it has animated off the screen.
- (void)interstitialDidDismissScreen:(GADInterstitial *)ad {
  NSLog(@"interstitialDidDismissScreen");
}

/// Called just before the app will background or terminate because the user clicked on an
/// ad that will launch another app (such as the App Store).
- (void)interstitialWillLeaveApplication:(GADInterstitial *)ad {
  NSLog(@"interstitialWillLeaveApplication");
}

/// Called when an interstitial ad request succeeded.
func interstitialDidReceiveAd(ad: GADInterstitial!) {
  print("interstitialDidReceiveAd")
}

/// Called when an interstitial ad request failed.
func interstitial(ad: GADInterstitial!, didFailToReceiveAdWithError error: GADRequestError!) {
  print("interstitial:didFailToReceiveAdWithError: \(error.localizedDescription)")
}

/// Called just before presenting an interstitial.
func interstitialWillPresentScreen(ad: GADInterstitial!) {
  print("interstitialWillPresentScreen")
}

/// Called before the interstitial is to be animated off the screen.
func interstitialWillDismissScreen(ad: GADInterstitial!) {
  print("interstitialWillDismissScreen")
}

/// Called just after dismissing an interstitial and it has animated off the screen.
func interstitialDidDismissScreen(ad: GADInterstitial!) {
  print("interstitialDidDismissScreen")
}

/// Called just before the application will background or terminate because the user clicked on an
/// ad that will launch another app (such as the App Store).
func interstitialWillLeaveApplication(ad: GADInterstitial!) {
  print("interstitialWillLeaveApplication")
}

Use cases

Third-party analytics

The SDK automatically tracks clicks and impressions, but if you're also using a third-party analytics solution, you can also track each of the GADInterstitialDelegate calls separately.

FAQ

Will I get GADBannerViewDelegate and GADInterstitialDelegate event notifications when using mediation?

Yes, mediation adapters are required to send all of these events, and these events are forwarded to your app.

Can I use the interstitialDidReceiveAd event to show the interstitial?

This goes against our best practices recommendation and can cause a poor user experience. Instead, preload the ad before you need to show it, and check the isReady() method on GADInterstitial to find out if it is ready to be shown.