iOS SDK - Banners

FairBid mediates banners from several third-party networks: AdMob, AppLovin, Facebook Audience Network, Mopub, and InMobi. In order to show banners, you will need to have one or more of these networks integrated. We also offer banner ads via our own network, FairBid Exchange.

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 HZBannerAd, which has two methods for showing banners. The first method requestBannerWithOptions:delegate:success:failure: returns an HZBannerAd object in its completion block. You can add the banner as a subview in the completion block:

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

Note that requestBannerWithOptions:success:failure: is deprecated since the 9.53.0.

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

    HZBannerAdOptions *options = [[HZBannerAdOptions alloc] init];
    [HZBannerAd placeBannerInView:self.view # Pass `nil` to use the rootViewController, which is a good default for many games
                          success:^(HZBannerAd *banner) {
                          failure:^(NSError *error) {
                              NSLog(@"Error = %@", error);

Note that placeBannerInView:position:options:success:failure: is deprecated since the 9.53.0.

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 *options = [[HZBannerAdOptions alloc] init];
// Optionally set the view controller to present modal views from (this defaults
// to the root VC of the app)
options.presentingViewController = self;

// Optionally set the maximum amount of time (in seconds) to let the fetch
// retry when ad networks don't return an ad right away before failing out.
// The default behavior is to retry until it succeeds.
options.fetchTimeout = 120; // 120 seconds (2 minutes), for example

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

// Optionally, set a tag for the banner ad to give you control over the banner
// ad location from our dashboards.
options.tag = @"mainMenuBanner";

For a complete list of size options, please refer to our API documentation.


We provide both a delegate interface through the HZBannerAdDelegate protocol as well as NSNotifications for all banner callbacks. The object of the NSNotifications listed below will be the HZBannerAd instance returned to you when you requested a banner ad.

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.
bannerDidShowAd:adImpressionData: N/A
  • N/A
Available since `9.53.0`. Called when a fetched and loaded banner has become presented and is visible, or was visible and just refreshed it's fill.
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).

See more info about the adImpressionData here.

Hiding and Destroying Banners

In order to hide or destroy a banner, you must save a reference to the HZBannerAd returned in the success callback of the method you called to show it (placeBannerInView:position:options:delegate:success:failure: or requestBannerWithOptions:delegate:success:failure). In the below examples, banner is the HZBannerAd * saved in the callback.

Hidden banners can be shown again, just like any other view. To hide a banner, just hide the view:

// Hide the banner ad
[banner setHidden: YES];

// Later, to show the same banner ad
[banner 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:delegate:success:failure: or requestBannerWithOptions:delegate:success:failure again. Destroying a banner ad (instead of hiding it) gives FairBid 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 and remove all strong references to it:

[banner removeFromSuperview];
banner = nil; // don't keep any references to the banner so it can be deallocated