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, a size and a position. Use Show() when you need the banner to be displayed.

Start loading a Banner

XMediatorAds.StartWith(
    appKey: "<your-app-key>",
    initCallback: result => 
    {
        XMediatorAds.Banner.Create(
            placementId: "<placement-id>",
            size: BannerAds.Size.Phone,
            position: BannerAds.Position.Bottom
        );
    }
);

Showing a banner

// Optionally, set the ad space where the banner will be shown
XMediatorAds.Banner.SetAdSpace("<placement-id>", "banner-ad-space");

// Show the banner
XMediatorAds.Banner.Show("<placement-id>");

Hiding a banner

Use this function to indicate that the banner should not be visible. This will not interfere with the loading process, so if the banner is still being loaded it will continue to do so.

XMediatorAds.Banner.Hide("<placement-id>");

Built-in features

Banner autorefresh

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.

Banner retry

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.

// Load Callback
XMediatorAds.Banner.OnLoaded += (placementId, result) => {
    Debug.Log($"Banner loaded! placementId: {placementId}");
};

// Impression Callback
XMediatorAds.Banner.OnImpression += (placementId, impressionData) => {
    Debug.Log($"Banner impression! placementId: {placementId}");
};

// Click Callback
XMediatorAds.Banner.OnClicked += placementId => {
    Debug.Log($"Banner clicked! placementId: {placementId}");
};

Info

For information about handling callback threads using XMediatorMainThreadDispatcher please refer to this section.

(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.

XMediatorAds.Banner.SetAdSpace("<placement-id>", "banner-ad-space");

(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>");

Setting a banner's position

// Change position to the top of the screen
XMediatorAds.Banner.SetPosition("<placement-id>", BannerAds.Position.Top);

Banner sizes

Constant	Size (WxH)	Description
Phone	320x50	Size for banners used in phone devices
Tablet	728x90	Size for banners used in tablet devices
MREC	300x250	Size for IAB Medium Rectangle banners

Size is in DP for Android and Points for iOS.

Banner position

Constant	Description
Top	Places the banner at the top of the screen
Bottom	Places the banner at the bottom of the screen
Custom	Custom x,y position relative to top-left corner

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

BannerTest.cs

using UnityEngine;
using UnityEngine.UI;
using XMediator.Api;
using XMediator.Core.Util;

public class BannerTest : MonoBehaviour
{
    public Button LoadButton;
    public Button ShowBannerTopButton;
    public Button ShowBannerBottomButton;
    public Button HideBannerButton;

    private BannerAds.Position _position = BannerAds.Position.Bottom;
    private BannerAds.Size _size = BannerAds.Size.Phone;

    private const string YourPlacementId = "<placement-id>";

    private void Start()
    {
        LoadButton.onClick.AddListener(OnLoadClicked);
        ShowBannerTopButton.onClick.AddListener(OnShowBannerTopClicked);
        ShowBannerBottomButton.onClick.AddListener(OnShowBannerBottomClicked);
        HideBannerButton.onClick.AddListener(OnHideBannerClicked);

        // Setup callbacks
        XMediatorAds.Banner.OnLoaded += (placementId, result) => XMediatorMainThreadDispatcher.Enqueue(
            () => { Log($"Banner loaded for placement: {placementId}"); }
        );
        XMediatorAds.Banner.OnImpression += (placementId, impressionData) =>
        {
            Log($"Banner impression for placement: {placementId}");
        };
        XMediatorAds.Banner.OnClicked += placementId =>
        {
            Log($"Banner with placement {placementId} was clicked");
        };

        // Start loading a banner
        XMediatorAds.Banner.Create(placementId: YourPlacementId, size: _size, position: _position);
    }

    private void OnShowBannerTopClicked()
    {
        Log("Show banner top button clicked.");
        _position = BannerAds.Position.Top;
        XMediatorAds.Banner.Show(YourPlacementId, _position);
    }

    private void OnShowBannerBottomClicked()
    {
        Log("Show banner bottom button clicked.");
        _position = BannerAds.Position.Bottom;
        XMediatorAds.Banner.Show(YourPlacementId, _position);
    }

    private void OnHideBannerClicked()
    {
        Log("Hide banner button clicked.");
        XMediatorAds.Banner.Hide(YourPlacementId);
    }

    private void OnLoadClicked()
    {
        Log("Manually refreshing banner.");
        XMediatorAds.Banner.Load(YourPlacementId);
    }

    private static void Log(string message)
    {
        Debug.Log($"[BannerTest] {message}");
    }
}