Unified Platform – iOS Banners

Heyzap mediates banners from AdMob, Facebook Audience Network, and Inmobi. In order to show banners, you will need to have one of these networks integrated.

Note: Most banner networks have a setting on their dashboard to automatically refresh at a given time interval. If you want to use this feature, it is strongly recommended that you use the same time interval on all of the banner networks you are using. Different refresh rates for different networks can result in confusing impression statistics.

Showing Banners

The main interface for accessing banners is HZBannerAdController, which has two methods for showing banners. The first method, requestBannerWithOptions:success:failure: returns a UIView object in its completion block. You can add the banner as a subview in the completion block:

HZBannerAdOptions *bannerOpts = [[HZBannerAdOptions alloc] init];
[[HZBannerAdController sharedInstance] requestBannerWithOptions:bannerOpts success:^(UIView *banner) {
    [self.view addSubview:banner];
} failure:^(NSError *error) {
    NSLog(@"Error = %@",error);

You can also have Heyzap automatically place the banner at the top or bottom of the screen:

HZBannerAdOptions *bannerOpts = [[HZBannerAdOptions alloc] init];
bannerOpts.presentingViewController = self; // Only necessary if you're using multiple view controllers in your app
[[HZBannerAdController sharedInstance] placeBannerAtPosition:HZBannerPositionTop options:bannerOpts success:^(UIView *banner) {
    NSLog(@"Showed banner");
} failure:^(NSError *error) {
    NSLog(@"Error showing banner: %@",error);

Configuration Options

Banners can be configured by passing an instance of HZBannerAdOptions as the options parameter in the above two methods. You can set the specific banner size to use (per ad network), as well as the view controller to present modal views from when the banner is clicked. These values are all optional (they have reasonable defaults).

HZBannerAdOptions *bannerOpts = [[HZBannerAdOptions alloc] init];
// Optionally set the view controller to present modal views from (this defaults
// to the root VC of the app)
bannerOpts.presentingViewController = self;

// Optionally set your preferred sizes for each network's banners.
// These are the default values.
bannerOpts.admobBannerSize    = HZAdMobBannerSizeFlexibleWidthPortrait; 
bannerOpts.facebookBannerSize = HZFacebookBannerSizeFlexibleWidthHeight50;
bannerOpts.inmobiBannerSize   = HZInmobiBannerSize728x90;

For a complete list of size options, please refer to the constants defined in HZBannerAdOptions.h


We provide both a delegate interface through the HZBannerAdDelegate protocol as well as NSNotifications for all banner callbacks.

HZBannerAdDelegate NSNotification NSNotification userInfo Keys Description
bannerDidReceiveAd: kHZBannerAdDidReceiveAdNotification
  • HZAdTagUserInfoKey
  • HZNetworkNameUserInfoKey
Called when a banner ad is refreshed. You should use the completion block on the method used to request a banner to be notified of banner ad availability, not this method.
bannerDidFailToReceiveAd:error: kHZBannerAdDidFailToReceiveAdNotification
  • HZAdTagUserInfoKey
  • HZNetworkNameUserInfoKey
  • NSUnderlyingErrorKey (if available)
Called when the banner fails to refresh itself. Banners are guaranteed to be loaded when first returned to you, but may fail when refreshing themselves later.
bannerWasClicked: kHZBannerAdWasClickedNotification
  • HZAdTagUserInfoKey
  • HZNetworkNameUserInfoKey
Called when the banner ad is clicked by the user.
bannerWillPresentModalView: kHZBannerAdWillPresentModalViewNotification
  • HZAdTagUserInfoKey
  • HZNetworkNameUserInfoKey
Called after the user taps the banner and a modal view will be presented from it.
bannerDidDismissModalView: kHZBannerAdDidDismissModalViewNotification
  • HZAdTagUserInfoKey
  • HZNetworkNameUserInfoKey
Called after the user dismisses the modal view presented from the banner.
bannerWillLeaveApplication: kHZBannerAdWillLeaveApplicationNotification
  • HZAdTagUserInfoKey
  • HZNetworkNameUserInfoKey
Called after the user taps the banner and is redirected out of the app (e.g. to a web page or the app store).

Hiding and Destroying Banners

Hidden banners can be shown again, just like any other view. To hide a banner, just hide the view (this is a method on UIView):

// Hide the banner ad
[[HZBannerAdController sharedInstance].bannerView setHidden: YES];

// Later, to show the same banner ad
[[HZBannerAdController sharedInstance].bannerView setHidden: NO];

Destroyed banners cannot be shown again. The next time you want to show a banner after destroying one, you will need to call placeBannerInView:position:options:success:failure: or requestBannerWithOptions:success:failure again. Destroying a banner ad (instead of hiding it) gives Heyzap another chance to choose the best network to show an ad from next time, and it will refresh the contents of the banner. To destroy a banner ad, remove the view from its superview remove all strong references to it if you have any, and call this method:

banner = nil; // don't keep any references to the banner view, if you have any, so it can be deallocated

[[HZBannerAdController sharedInstance] destroyBanner];