Banner Integration for iOS

Banners are a rectangular, system-initiated ads that can be either static or animated, and are served in a designated area around your live app content. 

Before you start
  • Make sure that you have correctly integrated the ironSource SDK into your application. Integration is outlined here.
  • Make sure to initialize the SDK using LevelPlay Initialization API.
  • You can find the AdUnitID in LevelPlay dashboard. Learn more here.
  • This documentation is relevant for SDK 8.4.0+. Documentation for legacy banner APIs (SDK 8.4.0 and below) can be found here.

Create Banner Ad Object and Set Size

The creation of the banner ad object should be done after receiving onInitSuccess callback.

// Create the banner view and set the ad unit id 
self.bannerAdView = [[LPMBannerAdView alloc] initWithAdUnitId:@"adUnitId"];
/ Create the banner view and set the ad unit id
self.bannerAdView = LPMBannerAdView(adUnitId: "adUnitId")
LPMAdSize Description Dimensions in dp
(Width X Height)
bannerSize Standard banner 320 x 50
largeSize Large banner 320 x 90
mediumRectangleSize Medium Rectangular (MREC) 300 x 250
Adaptive Automatically renders ads to adjust size and orientation for mobile & tablets
Device width X recommended height

To create the ad size follow one of these options: 

Adaptive ad size that adjusts to the screen width (recommended):

This option returns BANNER or LEADERBOARD according to the device type.
Networks that supports adaptive feature (Google, Yandex) will return the a height based on their optimization logic.

LPMAdSize *bannerSize = [LPMAdSize createAdaptiveAdSize];
[self.bannerAdView setAdSize: bannerSize];
let bannerSize = LPMAdSize.createAdaptive()
self.bannerAdView.setAdSize(bannerSize)

Specific banner size:
This option allows you to set specifically a banner size: BANNER, LARGE, MEDIUM_RECTANGLE.

LPMAdSize *bannerSize = [LPMAdSize largeSize];
[self.bannerAdView setAdSize: bannerSize];
let bannerSize = LPMAdSize.large()
self.bannerAdView.setAdSize(bannerSize)

Placements

We support placements in banners for reporting only. Placements should be set before the loadAd, to affect all reloaded ads.

// Set the placement name
[self.bannerAdView setPlacementName:@"PlacementName"];
// Set the placement name
self.bannerAdView.setPlacementName("PlacementName")

Set Banner Delegates 

Implement the LPMBannerAdViewDelegate in your code to get informed of ad delivery.

  • It is recommended to set the delegates before loading the banner ad.
  • Please note that each banner ad view should have its own delegate implementation.
  • Callbacks run on the main thread.
  • When callbacks are not supported by all networks, they are marked as optional.
// Set delegate implementation 
[self.bannerAdView setDelegate:self]
#pragma mark - LPMBannerAdViewDelegate
- (void)didLoadAdWithAdInfo:(nonnull LPMAdInfo *)adInfo {
   //Ad was loaded successfully
}
- (void)didFailToLoadAdWithAdUnitId:(nonnull NSString *)adUnitId error:(nonnull NSError *)error { 
   // Ad load failed
}
- (void)didClickAdWithAdInfo:(LPMAdInfo *)adInfo {
   // Ad was clicked
}
- (void)didDisplayAdWithAdInfo:(LPMAdInfo *)adInfo {
   // Ad was displayed and visible on screen
}
- (void)didFailToDisplayAdWithAdInfo:(LPMAdInfo *)adInfo error:(NSError *)error {
   // Optional. Ad was failed to be displayed on screen
}
- (void)didLeaveAppWithAdInfo:(LPMAdInfo *)adInfo {
   // Optional. User pressed on the ad and was navigated out of the app 
}
- (void)didExpandAdWithAdInfo:(LPMAdInfo *)adInfo {
   // Optional. Ad is opened on full screen
}
- (void)didCollapseAdWithAdInfo:(LPMAdInfo *)adInfo {
   // Optional. Ad is restored to its original size
}
// Set delegate implementation 
self.bannerAdViewView.setDelegate(self)
func didLoadAd(with adInfo: LPMAdInfo) {
   //Ad was loaded successfully 
}
func didFailToLoadAd(withAdUnitId adUnitId: String, error: Error) {
   // Ad load failed
}
func didClickAd(with adInfo: LPMAdInfo) {
   // Ad was clicked
}
func didDisplayAd(with adInfo: LPMAdInfo) {
   // Ad was displayed and visible on screen
}
func didFailToDisplayAd(with adInfo: LPMAdInfo, error: Error) {
   // Optional. Ad was failed to be displayed on screen
}
func didLeaveApp(with adInfo: LPMAdInfo) {
   // Optional. User pressed on the ad and was navigated out of the app 
}
func didExpandAd(with adInfo: LPMAdInfo) {
   // Optional. Ad is opened on full screen
}
func didCollapseAd(with adInfo: LPMAdInfo) {
   // Optional. Ad is restored to its original size
}

LevelPlay Ad Info

Ad Info

The LevelPlayAdInfo parameter includes information about the loaded ad.

Learn more about its implementation and available fields here.

Load Banner Ad

To load a banner ad, use loadAd.

// Load the banner ad
[self.bannerAdView loadAdWithViewController:self]
// Load the banner ad
self.bannerAdView.loadAd(with: self)

Pause and Resume Banner Refresh 

You can pause banner refresh in your code if the refresh value was defined in the platform. Use the following methods to stop the automatic refresh of the banner ad, or re-enable it after pausing. 

Note:

When the banner is displayed again, it will complete the time till refresh, from the time it was paused. 

  • pauseAutoRefresh – pauses auto-refresh of the banner ad.
  • resumeAutoRefresh – resumes auto-refresh of the banner ad after it has been paused.
// Pause refresh
[self.bannerAdView pauseAutoRefresh]; 
// Resume refresh
[self.bannerAdView resumeAutoRefresh];
// Pause refresh
self.bannerAdView.pauseAutoRefresh()
// Resume refresh
self.bannerAdView.resumeAutoRefresh()

Destroy Banner Ad

To destroy a banner, call the destroy method.

A destroyed banner can no longer be shown again. To display more ads, create a new LPMBannerAdView object.

[self.bannerAdView destroy];
self.bannerAdViewView.destroy()

Full Implementation Example of Banner Ads

Here is an example for creating and loading a banner ad using adaptive banner size.

NS_ASSUME_NONNULL_BEGIN
@interface BannerAdViewController () <LPMBannerAdViewDelegate>
@property(nonatomic, strong) LPMBannerAdView *bannerAd;
@end
@implementation BannerAdViewController
- (void)dealloc {
    [self.bannerAd destroy];
}
- (void)createBannerAd {
    // Create the banner view and set the ad unit id
    self.bannerAd = [[LPMBannerAdView alloc] initWithAdUnitId:@"adUnitId"];
    
    // Set the placement name (optional)
    [self.bannerAd setPlacementName:@"PlacementName"];
    
    // Set the ad size
    LPMAdSize *bannerSize = [self getBannerSize];
    
    // Required when using adaptive ad size
    if (bannerSize == nil) {
        return;
     }
    
    [self.bannerAd setAdSize:bannerSize];
    
    // Set the delegate implementation
    [self.bannerAd setDelegate:self];
    
    // Add the banner view to the view hierarchy with the proper constraints
    [self addBannerViewWithSize:bannerSize];
}
- (LPMAdSize *)getBannerSize {
    // 1. Recommended - Adaptive ad size that adjusts to the screen width
    LPMAdSize *bannerSize = [LPMAdSize createAdaptiveAdSize];
    // 2. Adaptive ad size using fixed width ad size
    // self.bannerSize = [LPMAdSize createAdaptiveAdSizeWithWidth:400];
    // 3. Specific banner size - BANNER, LARGE, MEDIUM_RECTANGLE
    // self.bannerSize = [LPMAdSize mediumRectangleSize];
    
    return bannerSize;
}
- (void)loadBannerAd {
    [self.bannerAd loadAdWithViewController:self];
}
- (void)addBannerViewWithSize:(LPMAdSize *)bannerSize {
    self.bannerAd.translatesAutoresizingMaskIntoConstraints = NO;
    
    // Add the banner view to the view hierarchy
    [self.view addSubview:self.bannerAd];
    [NSLayoutConstraint activateConstraints:@[
        [self.bannerAd.bottomAnchor constraintEqualToAnchor:self.view.safeAreaLayoutGuide.bottomAnchor],
        [self.bannerAd.centerXAnchor constraintEqualToAnchor:self.view.centerXAnchor],
        [self.bannerAd.widthAnchor constraintEqualToConstant:bannerSize.width],
        [self.bannerAd.heightAnchor constraintEqualToConstant:bannerSize.height]
    ]];
}
#pragma mark - LPMBannerAdViewDelegate
- (void)didLoadAdWithAdInfo:(nonnull LPMAdInfo *)adInfo {}
- (void)didFailToLoadAdWithAdUnitId:(nonnull NSString *)adUnitId error:(nonnull NSError *)error {}
- (void)didClickAdWithAdInfo:(LPMAdInfo *)adInfo {}
- (void)didDisplayAdWithAdInfo:(LPMAdInfo *)adInfo {}
- (void)didFailToDisplayAdWithAdInfo:(LPMAdInfo *)adInfo error:(NSError *)error {}
- (void)didLeaveAppWithAdInfo:(LPMAdInfo *)adInfo {}
- (void)didExpandAdWithAdInfo:(LPMAdInfo *)adInfo {}
- (void)didCollapseAdWithAdInfo:(LPMAdInfo *)adInfo {}
@end
NS_ASSUME_NONNULL_END
import UIKit
class BannerAdViewController: UIViewController, LPMBannerAdViewDelegate {
    var bannerAd: LPMBannerAdView!
    deinit {
        self.bannerAd.destroy()
    }
    func createBannerAd() {
        // Create the banner view and set the ad unit id
        self.bannerAd = LPMBannerAdView(adUnitId: "adUnitId")
        
        // Set the placement name (optional)
        self.bannerAd.setPlacementName("PlacementName")
        
        // Set the ad size
        // Null check required when using adaptive ad size
        guard let bannerSize = getBannerSize() else {
            return
        }
        self.bannerAd.setAdSize(bannerSize)
        
        // Set the delegate implementation
        self.bannerAd.setDelegate(self)
        
        // Add the banner view to the view hierarchy with the proper constraints
        addBannerView(withSize: bannerSize)
    }
    func getBannerSize() -> LPMAdSize? {
        // 1. Recommended - Adaptive ad size that adjusts to the screen width
        let bannerSize = LPMAdSize.createAdaptive()
        // 2. Adaptive ad size using fixed width ad size
        // bannerSize = LPMAdSize.createAdaptiveAdSize(withWidth: 400)
        // 3. Specific banner size - BANNER, LARGE, MEDIUM_RECTANGLE
        // bannerSize = LPMAdSize.mediumRectangleSize()
        
        return bannerSize
    }
    func loadBannerAd() {
        self.bannerAd.loadAd(with: self)
    }
    func addBannerView(withSize bannerSize: LPMAdSize) {
        DispatchQueue.main.async {
            self.bannerAd.translatesAutoresizingMaskIntoConstraints = false
            self.view.addSubview(self.bannerAd)
            let centerX = self.bannerAd.centerXAnchor.constraint(equalTo: self.view.centerXAnchor)
            let bottom = self.bannerAd.bottomAnchor.constraint(equalTo: self.view.safeAreaLayoutGuide.bottomAnchor)
            let width = self.bannerAd.widthAnchor.constraint(equalToConstant: CGFloat(bannerSize.width))
            let height = self.bannerAd.heightAnchor.constraint(equalToConstant: CGFloat(bannerSize.height))
            NSLayoutConstraint.activate([centerX, bottom, width, height])
        }
    }
    // MARK: - LPMBannerAdViewDelegate
    func didLoadAd(with adInfo: LPMAdInfo) {}
    func didFailToLoadAd(withAdUnitId adUnitId: String, error: Error) {}
    func didClickAd(with adInfo: LPMAdInfo) {}
    func didDisplayAd(with adInfo: LPMAdInfo) {}
    func didFailToDisplayAd(with adInfo: LPMAdInfo, error: Error) {}
    func didLeaveApp(with adInfo: LPMAdInfo) {}
    func didExpandAd(with adInfo: LPMAdInfo) {}
    func didCollapseAd(with adInfo: LPMAdInfo) {}
}

LevelPlay Mediation Demo App

The Integration Demo application demonstrates how to integrate banner Ad Unit APIs in your app.

Download iOS Demo Application

Done!
You are now all set up to serve banners in your application. Verify your integration with our Integration Test Suite.


What’s Next?
Follow our integration guides to integrate additional Banner Ad networks or configure additional ad formats: