Skip to main content

Banner

Banner ads occupy a small portion of the user interface, usually at the bottom or the top of the screen.

To start using banners, just call create() using a valid placement id and a size. To show one in your app, you call its getView() method and add the view to the current view hierarchy.

Start loading a Banner​

import XMediator

XMediatorAds.startWith(appKey: "<your-app-key>") { result in
    XMediatorAds.banner.create(placementId: "<placement-id>",
                                size: UI_USER_INTERFACE_IDIOM() == .phone ? .phone : .tablet,
                                viewController: self)
}
ConstantSize (WxH)Description
Phone320x50Size for banners used in phone devices
Tablet728x90Size for banners used in tablet devices
MREC300x250Size for IAB Medium Rectangle banners

Size is in Points for iOS.

Showing a banner​

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

  • After creating the Banner instance.
  • After the didLoad(placementId:result:) callback is called, or by validating that it is already loaded using the isReady(withPlacementId:) method.
// Optionally, set the ad space where the banner will be shown
XMediatorAds.banner.setAdSpace("banner-ad-space", forPlacementId: "<placement-id>")

// getView() can return nil in case the banner was never requested for the <placement-id> used
let bannerView = try? XMediatorAds.banner.getView(forPlacementId: "<placement-id>",
                                                  fromViewController: self)
if let bannerView {
    view.addSubview(bannerView)
        
    bannerView.translatesAutoresizingMaskIntoConstraints = false
    bannerView.bottomAnchor.constraint(equalTo: view.safeAreaLayoutGuide.bottomAnchor).isActive = true
    bannerView.centerXAnchor.constraint(equalTo: view.centerXAnchor).isActive = true
}

Built-in features​

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.

Additional settings​

Register ad callbacks​

Every ad callback indicates the placement id of the banner that triggered the event.

// Assign a delegate to handle the ad callbacks
XMediatorAds.banner.addDelegate(self)

// [...]

func didLoad(placementId: String, result: LoadResult) {
    print("Banner loaded! placementId: \(placementId)")
}

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

func didClick(placementId: String) {
    print("Banner clicked! placementId: \(placementId)")
}
(Optional) Manually refreshing a banner ad​

Banner ads usually refresh their contents automatically, after a certain amount of time has passed. However, if you prefer to, you can manually refresh a banner's content by calling the load method:

XMediatorAds.banner.load("<placement-id>")
(Optional) Check if banner is ready​

Calling isReady(withPlacementId:) will return if there's a banner available to be shown.

if XMediatorAds.banner.isReady(withPlacementId: "<placement-id>") {
    // show the banner
}

Code example​

In addition to the example below, you can see a real implementation in our iOS Demo App.

BannerViewController.swift
import UIKit
import XMediator

class BannerViewController: UIViewController {
    private let placementId = "<placement-id>"

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

    @IBAction func startButtonTouchUpInside(_ sender: Any) {
        XMediatorAds.startWith(appKey: "<your-app-key>") { result in
            XMediatorAds.banner.addDelegate(self)

            // Create banner once. Subsequent loads or retries are handled by the sdk
            XMediatorAds.banner.create(placementId: placementId,
                                       size: UI_USER_INTERFACE_IDIOM() == .phone ? .phone : .tablet,
                                       viewController: self)
            
            self.addBannerToViewHierarchy()
        }
    }

    private func addBannerToViewHierarchy() {
        let bannerView = try? XMediatorAds.banner.getView(forPlacementId: placementId,
                                                          fromViewController: self)
        if let bannerView {
            view.addSubview(bannerView)
            
            bannerView.translatesAutoresizingMaskIntoConstraints = false
            bannerView.bottomAnchor.constraint(equalTo: view.safeAreaLayoutGuide.bottomAnchor).isActive = true
            bannerView.centerXAnchor.constraint(equalTo: view.centerXAnchor).isActive = true
        }
    }
}

extension BannerViewController: BannerAdsDelegate {
    func didLoad(placementId: String, result: LoadResult) {
        print("Banner loaded! placementId: \(placementId)")
    }

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

    func didClick(placementId: String) {
        print("Banner clicked! placementId: \(placementId)")
    }
}