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

SwiftObjective-C

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)
}

@import XMediatorObjC;

[X3MXMediatorAds startWithAppKey:@"<your-app-key>"
                        callback:^(NSError * _Nullable error) {
    X3MBannerSize size = UI_USER_INTERFACE_IDIOM() == UIUserInterfaceIdiomPhone ?
        X3MBannerSizePhone : X3MBannerSizeTablet;

    [X3MXMediatorAds.banner createWithPlacementId:@"<placement-id>"
                                             size:size
                                   viewController:self];
}];

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.

SwiftObjective-C

// 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
}

// getView can return nil in case the banner was never requested for the <placement-id> used
UIView *bannerView = [X3MXMediatorAds.banner getViewForPlacementId:@"<placement-id>"
                                                fromViewController:self];
if (bannerView != nil) {
    [view addSubview:bannerView];

    bannerView.translatesAutoresizingMaskIntoConstraints = NO;
    [bannerView.bottomAnchor constraintEqualToAnchor:view.safeAreaLayoutGuide.bottomAnchor].active = YES;
    [bannerView.centerXAnchor constraintEqualToAnchor:view.centerXAnchor].active = YES;
}

Built-in features

Banner autorefresh

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.

Banner retry

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.

SwiftObjective-C

// 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)")
}

// Assign a delegate to handle the ad callbacks
[X3MXMediatorAds.banner addDelegate:self];

// [...]

- (void)didLoadWithPlacementId:(NSString * _Nonnull)placementId result:(X3MLoadResult * _Nonnull)result {
    NSLog(@"Banner loaded! placementId: %@", placementId);
}

- (void)didRecordImpressionWithPlacementId:(NSString * _Nonnull)placementId data:(X3MImpressionData * _Nonnull)data {
    NSLog(@"Banner impression, with revenue: %f. PlacementId %@", data.revenue, placementId);
}

- (void)didClickWithPlacementId:(NSString * _Nonnull)placementId {
    NSLog(@"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:

SwiftObjective-C

XMediatorAds.banner.load("<placement-id>")

[X3MXMediatorAds.banner loadWithPlacementId:@"<placement-id>"];

Code example

SwiftObjective-C

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)")
    }
}

BannerViewController.m

@import UIKit;
@import XMediatorObjC;

@interface BannerViewController ()<X3MBannerAdsDelegate>
@end

@implementation BannerViewController

- (void)viewDidLoad {
    [super viewDidLoad];
}

- (IBAction)startButtonTouchUpInside:(id)sender {
    [X3MXMediatorAds startWithAppKey:@"<your-app-key>"
                            callback:^(NSError * _Nullable error) {
        [X3MXMediatorAds.banner addDelegate:self];

        X3MBannerSize size = UI_USER_INTERFACE_IDIOM() == UIUserInterfaceIdiomPhone ?
            X3MBannerSizePhone : X3MBannerSizeTablet;

        // Create banner once. Subsequent loads or retries are handled by the sdk
        [X3MXMediatorAds.banner createWithPlacementId:@"<placement-id>"
                                                 size:size
                                       viewController:self];

        [self addBannerToViewHierarchy];
    }];
}

- (void)addBannerToViewHierarchy {
    UIView *bannerView = [X3MXMediatorAds.banner getViewForPlacementId:@"<placement-id>"
                                                    fromViewController:self];
    if (bannerView != nil) {
        [self.view addSubview:bannerView];

        bannerView.translatesAutoresizingMaskIntoConstraints = NO;
        [bannerView.bottomAnchor constraintEqualToAnchor:self.view.safeAreaLayoutGuide.bottomAnchor].active = YES;
        [bannerView.centerXAnchor constraintEqualToAnchor:self.view.centerXAnchor].active = YES;
    }
}

#pragma mark - Ads Delegate

- (void)didLoadWithPlacementId:(NSString * _Nonnull)placementId result:(X3MLoadResult * _Nonnull)result {
    NSLog(@"Banner loaded! placementId: %@", placementId);
}

- (void)didRecordImpressionWithPlacementId:(NSString * _Nonnull)placementId data:(X3MImpressionData * _Nonnull)data {
    NSLog(@"Banner impression, with revenue: %f. PlacementId %@", data.revenue, placementId);
}

- (void)didClickWithPlacementId:(NSString * _Nonnull)placementId {
    NSLog(@"Banner clicked! placementId: %@", placementId);
}

@end