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.

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];
}];

When creating a banner, in addition to the 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.

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:) delegate callback is called.

SwiftObjective-C

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

// Optionally, set the ad space where the banner will be shown
[X3MXMediatorAds.banner setAdSpace:@"banner-ad-space" forPlacementId:@"<placement-id>"];

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

After being displayed for some time, our banner fires a new 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 an 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) Updating ad space

Before showing an ad, you can set an ad space name for the banner instance. This is useful for tracking purposes because it enables you to get performance insights for different ad spaces of your application.

SwiftObjective-C

XMediatorAds.banner.setAdSpace("banner-ad-space", forPlacementId: "<placement-id>")

[X3MXMediatorAds.banner setAdSpace:@"test_space_simp_ban" forPlacementId:@"<placement-id>"];

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>"];

Advanced use cases

This guide provides the recommended integration steps to show a banner ad using X3M, which covers most of the common scenarios. For advanced use cases, where manually handling the lifecycle of the ad object is needed, refer to this section.

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

Banner

Start loading a Banner

Showing a banner

Built-in features

Banner autorefresh

Banner retry

Additional settings

Register ad callbacks

(Optional) Updating ad space

(Optional) Manually refreshing a banner ad

Advanced use cases

Code example