Banner Ads

Banner ads occupy a spot within an app's layout, either at the top or bottom of the device screen. They stay on screen while users are interacting with the app, and can refresh automatically after a certain period of time. If you're new to mobile advertising, they're a great place to start.

This guide shows you how to integrate banner ads from Ad Manager into an iOS app. In addition to code snippets and instructions, it includes information about sizing banners properly and links to additional resources.

Prerequisites

• Import the Google Mobile Ads SDK.

Always test with test ads

When building and testing your apps, make sure you use test ads rather than live, production ads. Failure to do so can lead to suspension of your account.

The easiest way to load test ads is to use our dedicated test ad unit ID for iOS banners: /6499/example/banner

It's been specially configured to return test ads for every request, and you're free to use it in your own apps while coding, testing, and debugging. Just make sure you replace it with your own ad unit ID before publishing your app.

For more information about how the Mobile Ads SDK's test ads work, see Test Ads.

Create a GAMBannerView

Banner ads are displayed in GAMBannerView objects, so the first step toward integrating banner ads is to include a GAMBannerView in your view hierarchy. This is typically done either with the Interface Builder or programmatically.

Interface Builder

A GAMBannerView can be added to a storyboard or xib file like any typical view. When using this method, be sure to add width and height constraints to match the ad size you'd like to display. For example, when displaying a banner (320x50), use a width constraint of 320 points, and a height constraint of 50 points.

Programmatically

A GAMBannerView can also be instantiated directly. Here's an example of how to create a GAMBannerView, aligned to the bottom center of the safe area of the screen, with a banner size of 320x50:

import GoogleMobileAds
import UIKit

class ViewController: UIViewController {

  var bannerView: GAMBannerView!

  override func viewDidLoad() {
    super.viewDidLoad()
    
    // In this case, we instantiate the banner with desired ad size.
    bannerView = GAMBannerView(adSize: GADAdSizeBanner)

    addBannerViewToView(bannerView)
  }

  func addBannerViewToView(_ bannerView: GAMBannerView) {
    bannerView.translatesAutoresizingMaskIntoConstraints = false
    view.addSubview(bannerView)
    view.addConstraints(
      [NSLayoutConstraint(item: bannerView,
                          attribute: .bottom,
                          relatedBy: .equal,
                          toItem: bottomLayoutGuide,
                          attribute: .top,
                          multiplier: 1,
                          constant: 0),
       NSLayoutConstraint(item: bannerView,
                          attribute: .centerX,
                          relatedBy: .equal,
                          toItem: view,
                          attribute: .centerX,
                          multiplier: 1,
                          constant: 0)
      ])
   }
   
}

@import GoogleMobileAds;

@interface ViewController ()

@property(nonatomic, strong) GAMBannerView *bannerView;

@end

@implementation ViewController

- (void)viewDidLoad {
  [super viewDidLoad];
  
  // In this case, we instantiate the banner with desired ad size.
  self.bannerView = [[GAMBannerView alloc]
      initWithAdSize:GADAdSizeBanner];

  [self addBannerViewToView:self.bannerView];
}

- (void)addBannerViewToView:(UIView *)bannerView {
  bannerView.translatesAutoresizingMaskIntoConstraints = NO;
  [self.view addSubview:bannerView];
  [self.view addConstraints:@[
    [NSLayoutConstraint constraintWithItem:bannerView
                               attribute:NSLayoutAttributeBottom
                               relatedBy:NSLayoutRelationEqual
                                  toItem:self.bottomLayoutGuide
                               attribute:NSLayoutAttributeTop
                              multiplier:1
                                constant:0],
    [NSLayoutConstraint constraintWithItem:bannerView
                               attribute:NSLayoutAttributeCenterX
                               relatedBy:NSLayoutRelationEqual
                                  toItem:self.view
                               attribute:NSLayoutAttributeCenterX
                              multiplier:1
                                constant:0]
                                ]];
}
  


@end

Note that in this case we don't give width or height constraints, as the provided ad size will give the banner an intrinsic content size to size the view.

If you don't want to use a standard size defined by a constant, you can set a custom size using GADAdSizeFromCGSize. See the banner size section for more information.

Configure GAMBannerView properties

In order to load and display ads, GAMBannerView requires a few properties be set.

• rootViewController - This view controller is used to present an overlay when the ad is clicked. It should normally be set to the view controller that contains the GAMBannerView.
• adUnitID - This is the ad unit ID from which the GAMBannerView should load ads.

Here's a code example showing how to set the two required properties in the viewDidLoad method of a UIViewController:

override func viewDidLoad() {
  super.viewDidLoad()
  ...

  bannerView.adUnitID = "/6499/example/banner"
  bannerView.rootViewController = self
}

- (void)viewDidLoad {
  [super viewDidLoad];
  ...

  self.bannerView.adUnitID = @"/6499/example/banner";
  self.bannerView.rootViewController = self;
}

Load an ad

Once the GAMBannerView is in place and its properties configured, it's time to load an ad. This is done by calling loadRequest: on a GAMRequest object:

override func viewDidLoad() {
  super.viewDidLoad()
  ...

  bannerView.adUnitID = "/6499/example/banner"
  bannerView.rootViewController = self
  bannerView.load(GAMRequest())
}

- (void)viewDidLoad {
  [super viewDidLoad];
  ...

  self.bannerView.adUnitID = @"/6499/example/banner";
  self.bannerView.rootViewController = self;
  [self.bannerView loadRequest:[GAMRequest request]];
}

GAMRequest objects represent a single ad request, and contain properties for things like targeting information.

Ad events

Through the use of GADBannerViewDelegate, you can listen for lifecycle events, such as when an ad is closed or the user leaves the app.

Registering for banner events

To register for banner ad events, set the delegate property on GAMBannerView 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 GoogleMobileAds
import UIKit

class ViewController: UIViewController, GADBannerViewDelegate {

  var bannerView: GAMBannerView!

  override func viewDidLoad() {
    super.viewDidLoad()
    ...
    bannerView.delegate = self
  }
}

@import GoogleMobileAds;

@interface ViewController () <GADBannerViewDelegate>

@property(nonatomic, strong) GAMBannerView *bannerView;

@end

@implementation ViewController

- (void)viewDidLoad {
  [super viewDidLoad];
  ...
  self.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:

func bannerViewDidReceiveAd(_ bannerView: GADBannerView) {
  print("bannerViewDidReceiveAd")
}

func bannerView(_ bannerView: GADBannerView, didFailToReceiveAdWithError error: Error) {
  print("bannerView:didFailToReceiveAdWithError: \(error.localizedDescription)")
}

func bannerViewDidRecordImpression(_ bannerView: GADBannerView) {
  print("bannerViewDidRecordImpression")
}

func bannerViewWillPresentScreen(_ bannerView: GADBannerView) {
  print("bannerViewWillPresentScreen")
}

func bannerViewWillDismissScreen(_ bannerView: GADBannerView) {
  print("bannerViewWillDIsmissScreen")
}

func bannerViewDidDismissScreen(_ bannerView: GADBannerView) {
  print("bannerViewDidDismissScreen")
}

- (void)bannerViewDidReceiveAd:(GADBannerView *)bannerView {
  NSLog(@"bannerViewDidReceiveAd");
}

- (void)bannerView:(GADBannerView *)bannerView didFailToReceiveAdWithError:(NSError *)error {
  NSLog(@"bannerView:didFailToReceiveAdWithError: %@", [error localizedDescription]);
}

- (void)bannerViewDidRecordImpression:(GADBannerView *)bannerView {
  NSLog(@"bannerViewDidRecordImpression");
}

- (void)bannerViewWillPresentScreen:(GADBannerView *)bannerView {
  NSLog(@"bannerViewWillPresentScreen");
}

- (void)bannerViewWillDismissScreen:(GADBannerView *)bannerView {
  NSLog(@"bannerViewWillDismissScreen");
}

- (void)bannerViewDidDismissScreen:(GADBannerView *)bannerView {
  NSLog(@"bannerViewDidDismissScreen");
}

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

Swift Objective-C

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 want to delay in adding a GAMBannerView to the view hierarchy until after an ad is received. You can do this by listening for the bannerViewDidReceiveAd: event:

func bannerViewDidReceiveAd(_ bannerView: GADBannerView) {
  // Add banner to view and add constraints as above.
  addBannerViewToView(bannerView)
}

- (void)bannerViewDidReceiveAd:(GAMBannerView *)bannerView {
  // Add bannerView to view and add constraints as above.
  [self addBannerViewToView:self.bannerView];
}

Animating a banner ad

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

func bannerViewDidReceiveAd(_ bannerView: GADBannerView) {
  bannerView.alpha = 0
  UIView.animate(withDuration: 1, animations: {
    bannerView.alpha = 1
  })
}

- (void)bannerViewDidReceiveAd:(GAMBannerView *)bannerView {
  bannerView.alpha = 0;
  [UIView animateWithDuration:1.0 animations:^{
    bannerView.alpha = 1;
  }];
}

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. If you want to trace whether these events were due to ads, register for these GADBannerViewDelegate methods.

To catch all types of overlay presentations or external browser invocations, not just those 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:

Banner sizes

The table below lists the standard banner sizes.

Custom ad sizes

To define a custom banner size, set your desired size using GADAdSizeFromCGSize, as shown here:

let adSize = GADAdSizeFromCGSize(CGSize(width: 300, height: 50))

GADAdSize size = GADAdSizeFromCGSize(CGSizeMake(300, 50));

Custom ad size

In addition to the standard ad units, Google Ad Manager allows you to serve any sized ad unit into an app. The ad size (width, height) defined for an ad request should match the dimensions of the ad view (GAMBannerView) displayed on the app. To set a custom size, use GADAdSizeFromCGSize.

// Define custom GADAdSize of 250x250 for GAMBannerView.
let customAdSize = GADAdSizeFromCGSize(CGSize(width: 250, height: 250))
bannerView = GAMBannerView(adSize: customAdSize)

// Define custom GADAdSize of 250x250 for GAMBannerView
GADAdSize customAdSize = GADAdSizeFromCGSize(CGSizeMake(250, 250));
self.bannerView = [[GAMBannerView alloc] initWithAdSize:customAdSize];

See the Ad Manager Multiple Ad Sizes example for an implementation of custom ad size in the iOS API Demo app.

Swift Objective-C

Multiple ad sizes

Ad Manager allows you to specify multiple ad sizes which may be eligible to serve into a GAMBannerView. There are three steps needed in order to use this feature:

1. In the Ad Manager UI, create a line item targeting the same ad unit that is associated with different size creatives.

2. In your app, set the validAdSizes property on GAMBannerView:

   Swift

   // Define an optional array of GADAdSize to specify all valid sizes that are appropriate
   // for this slot. Never create your own GADAdSize directly. Use one of the
   // predefined standard ad sizes (such as GADAdSizeBanner), or create one using
   // the GADAdSizeFromCGSize method.
   //
   // Note: Ensure that the allocated GAMBannerView is defined with an ad size. Also note
   // that all desired sizes should be included in the validAdSizes array.
   bannerView.validAdSizes = [NSValueFromGADAdSize(GADAdSizeBanner),
       NSValueFromGADAdSize(GADAdSizeMediumRectangle),
       NSValueFromGADAdSize(GADAdSizeFromCGSize(CGSize(width: 120, height: 20)))]
   

   Objective-C

   // Define an optional array of GADAdSize to specify all valid sizes that are appropriate
   // for this slot. Never create your own GADAdSize directly. Use one of the
   // predefined standard ad sizes (such as GADAdSizeBanner), or create one using
   // the GADAdSizeFromCGSize method.
   //
   // Note: Ensure that the allocated GAMBannerView is defined with an ad size. Also note
   // that all desired sizes should be included in the validAdSizes array.
   self.bannerView.validAdSizes = @[
       NSValueFromGADAdSize(GADAdSizeBanner),
       NSValueFromGADAdSize(GADAdSizeMediumRectangle),
       NSValueFromGADAdSize(GADAdSizeFromCGSize(CGSizeMake(120, 20)))
   ];
   

3. Implement the GADAdSizeDelegate method to detect an ad size change.

   Swift

   public func bannerView(_ bannerView: GADBannerView, willChangeAdSizeTo size: GADAdSize)
   

   Objective-C

   
   
   (void)bannerView:(GAMBannerView *)view willChangeAdSizeTo:(GADAdSize)size;
   

Remember to set the delegate before making the request for an ad.

Swift

bannerView.adSizeDelegate = self

Objective-C

self.bannerView.adSizeDelegate = self;

See the Ad Manager Multiple Ad Sizes example for an implementation of custom ad size in the iOS API Demo app.

Swift Objective-C

Manual impression counting

You can manually send impression pings to Ad Manager if you have special conditions for when an impression should be recorded. This can be done by first enabling a GAMBannerView for manual impressions prior to loading an ad:

bannerView.enableManualImpressions = true

self.bannerView.enableManualImpressions = YES;

When you determine that an ad has been successfully returned and is on screen, you can manually fire an impression:

bannerView.recordImpression()

[self.bannerView recordImpression];

App events

App events allow you to create ads that can send messages to their app code. The app can then take actions based on these messages.

You can listen for Ad Manager-specific app events using GADAppEventDelegate. These events may occur at any time during the ad's lifecycle, even before the GADBannerViewDelegate object's bannerViewDidReceiveAd: is called.

// Implement your app event within this method. The delegate will be
// notified when the SDK receives an app event message from the ad.

// Called when the banner receives an app event.
optional public func bannerView(_ banner: GAMBannerView,
    didReceiveAppEvent name: String, withInfo info: String?)

// Implement your app event within this method. The delegate will be
// notified when the SDK receives an app event message from the ad.

@optional
// Called when the banner receives an app event.
- (void)bannerView:(GAMBannerView *)banner
    didReceiveAppEvent:(NSString *)name
              withInfo:(NSString *)info;

Your app event methods can be implemented in a view controller:

import GoogleMobileAds

class ViewController: UIViewController, GADAppEventDelegate {
}

@import GoogleMobileAds;

@interface ViewController : UIViewController <GADAppEventDelegate> {
}

@end

Remember to set the delegate using the appEventDelegate property before making the request for an ad.

bannerView.appEventDelegate = self

self.bannerView.appEventDelegate = self;

Here is an example showing how to change the background color of your app by specifying the color through an app event:

func bannerView(_ banner: GAMBannerView, didReceiveAppEvent name: String,
    withInfo info: String?) {
  if name == "color" {
    guard let info = info else { return }
    switch info {
    case "green":
      // Set background color to green.
      view.backgroundColor = UIColor.green
    case "blue":
      // Set background color to blue.
      view.backgroundColor = UIColor.blue
    default:
      // Set background color to black.
      view.backgroundColor = UIColor.black
    }
  }
}

- (void)bannerView:(GAMBannerView *)banner
    didReceiveAppEvent:(NSString *)name
              withInfo:(NSString *)info {
  if ([name isEqual:@"color"]) {
    if ([info isEqual:@"green"]) {
      // Set background color to green.
      self.view.backgroundColor = [UIColor greenColor];
    } else if ([info isEqual:@"blue"]) {
      // Set background color to blue.
      self.view.backgroundColor = [UIColor blueColor];
    } else
      // Set background color to black.
      self.view.backgroundColor = [UIColor blackColor];
    }
  }
}

And, here is the corresponding creative that sends color app event messages to appEventDelegate:

<html>
<head>
  <script src="//www.gstatic.com/afma/api/v1/google_mobile_app_ads.js"></script>
  <script>
    document.addEventListener("DOMContentLoaded", function() {
      // Send a color=green event when ad loads.
      admob.events.dispatchAppEvent("color", "green");

      document.getElementById("ad").addEventListener("click", function() {
        // Send a color=blue event when ad is clicked.
        admob.events.dispatchAppEvent("color", "blue");
      });
    });
  </script>
  <style>
    #ad {
      width: 320px;
      height: 50px;
      top: 0px;
      left: 0px;
      font-size: 24pt;
      font-weight: bold;
      position: absolute;
      background: black;
      color: white;
      text-align: center;
    }
  </style>
</head>
<body>
  <div id="ad">Carpe diem!</div>
</body>
</html>

See the Ad Manager App Events example for an implementation of app events in the iOS API Demo app.

Swift Objective-C

Additional resources

Examples on GitHub

• Banner ads example: Swift | Objective-C

• Advanced features demo: Swift | Objective-C

Mobile Ads Garage video tutorials

• Banner Implementation
• Banner Best Practices