Skip to content

Banner

Warning

This is the documentation for the Advanced API. Most developers should use our Simplified API, which comes with several built-in features such as:

  • automatic ad loading

  • retries for failed requests

See the documentation for the Simplified API here:

Banner ads occupy a small portion of the user interface, usually at the bottom or the top of the screen. To show one in your app, you access its view property and add it to the current view hierarchy.

Create a Banner instance

// Inside a view controller's viewDidLoad
let banner = Banner.create(placementId: "<placement-id>",
                           size: UI_USER_INTERFACE_IDIOM() == .phone ? .phone : .tablet,
                           viewController: self)
When creating a banner, in addition to your placementId, you have to provide:

  • size: Size of the banner. See Size for the available sizes.
  • viewController: Some networks require a viewController to be able to display a full sized ad when a banner is clicked.

Register ad callbacks

// Assign a delegate to handle the ad callbacks
banner.delegate = self

// [...]

// Load Callbacks
func didCompletePrebidding(result: PrebiddingResults) {
    print("Banner client-side bidding finished!")
}

func didLoad(result: LoadResult) {
    print("Banner loaded!")
}

func failedToLoad(result: LoadResult?, error: LoadError) {
    print("Banner failed to load. Reason: \(error.localizedDescription)")
}

// Impression Callback
func didRecordImpression(data: ImpressionData) {
    print("Banner impression, with revenue: \(data.revenue)")
}

Load an ad

banner.load()

Load an ad (with custom properties)

var properties = CustomProperties()
properties.addString(key: "game_mode", value: "classic")

banner.load(customProperties: properties)

Displaying the banner

The most common practice is to add the banner view to the view hierarchy either:

  • After creating the Banner instance.
  • After the didLoad(result:) delegate callback is called.
// Optionally, set the ad space where the banner will be shown
banner.adSpace = "banner-ad-space"

let bannerView = banner.view
view.addSubview(bannerView)

bannerView.translatesAutoresizingMaskIntoConstraints = false
bannerView.bottomAnchor.constraint(equalTo: view.safeAreaLayoutGuide.bottomAnchor).isActive = true
bannerView.centerXAnchor.constraint(equalTo: view.centerXAnchor).isActive = true

After being displayed for some time, our banner fires a Load() call automatically to refresh its contents. You can configure this time through our Admin tool for each one of your banners.

Our banner has a built in auto retry for failed loads attempts. This means that when a banner fails to load, it will retry again until it loads successfully. Time between each retry attemp will increase using an exponential backoff. You should not add any retry logic on your end, as it may interefere with our retry behaviour.

Code example

BannerViewController.swift 
import UIKit
import XMediator

class BannerViewController: UIViewController {
    private var banner: Banner?

    override func viewDidLoad() {
        super.viewDidLoad()

        let banner = Banner.create(placementId: "<placement-id>",
                                   size: UI_USER_INTERFACE_IDIOM() == .phone ? .phone : .tablet,
                                   viewController: self)

        banner.delegate = self
        self.banner = banner

        addBannerToViewHierarchy(banner.view)
    }

    private func addBannerToViewHierarchy(_ bannerView: UIView) {
        view.addSubview(bannerView)

        bannerView.translatesAutoresizingMaskIntoConstraints = false
        bannerView.bottomAnchor.constraint(equalTo: view.safeAreaLayoutGuide.bottomAnchor).isActive = true
        bannerView.centerXAnchor.constraint(equalTo: view.centerXAnchor).isActive = true
    }

    @IBAction func loadTouchUp(_ sender: Any) {
        banner?.load()
    }
}

extension BannerViewController: BannerDelegate {
    func didCompletePrebidding(result: PrebiddingResults) {
        print("Banner client-side bidding finished!")
    }

    func didLoad(result: LoadResult) {
        print("Banner loaded!")
    }

    func failedToLoad(result: LoadResult?, error: LoadError) {
        print("Banner failed to load. Reason: \(error.localizedDescription)")
    }

    func didRecordImpression(data: ImpressionData) {
        print("Banner impression, with revenue: \(data.revenue)")
    }

    func didClick() {
        print("Banner was clicked!")
    }
}