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

• Interstitial

• Rewarded

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

Once you create a Banner instance, you must use Load() to start loading. When loaded, banners are automatically added to the screen, so if this is not what you want you should use Hide(). This controls only its visibility, meaning that if the banner wasn't loaded yet it will continue to do so in background.

Use Show() when you need the banner to be displayed, indicating the position as explained below.

Finally, use Dispose() when you won't be using this banner instance anymore. That being said, we don't recommend disposing banners but reusing them instead. You can create one instance for each banner, and call Load() every time you need to make sure a new ad is available.

Create a Banner instance

var banner = Banner.Create("<placement-id>", position: Banner.Position.Bottom, size: Size.Phone);

banner.Hide(); //This prevents banner from automatically showing when loaded

Size parameter is optional, the value set by default is Size.Phone.

Register ad callbacks

// Load Callbacks

banner.OnPrebiddingFinished += result => {
    Debug.Log("Banner client-side bidding finished!");
};

banner.OnLoaded += result => {
    Debug.Log("Banner loaded!");
};

banner.OnFailedToLoad += (error, result) => {
    Debug.Log($"Banner failed to load. Reason: {error.Message}");
};

// Impression Callback

banner.OnImpression += impressionData => {
    Debug.Log("Banner impression!");
};

Info

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

Load an ad

// When the banner finishes loading, it will automatically be added to the view hierarchy
banner.Load();

Banner supports multiple Load() calls for each instance throughout its lifecycle.

Load an ad (with custom properties)

banner.Load(
    customProperties: new CustomProperties.Builder()
        .AddString("game_mode", "classic")
        .Build()
);

Hide a banner

banner.Hide();

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.

Show and change a banner's position

// Optionally, set the ad space where the banner will be shown
banner.SetAdSpace("banner-ad-space")

// Change position to the top of the screen
banner.Show(Banner.Position.Top);

// Change position to bottom of the screen
banner.Show(Banner.Position.Bottom);

Dispose an ad

banner.Dispose();

A disposed banner can no longer be used, you must create another banner instance again.

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
Bottom	Places the banner at the bottom of the screen
Top	Places the banner at the top of the screen

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.

Code example

BannerTest.cs

using JetBrains.Annotations;
using UnityEngine;
using UnityEngine.UI;
using XMediator.Api;

namespace X3M.XMediatorTest.Scripts
{
    public class BannerTest : MonoBehaviour
    {
        public Button CreateButton;
        public Button LoadButton;
        public Button ShowBannerTopButton;
        public Button ShowBannerBottomButton;
        public Button HideBannerButton;

        [CanBeNull] private Banner _banner;

        private Banner.Position _position = Banner.Position.Bottom;

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

        private void OnDestroy()
        {
            // Dispose the banner at the end of its lifecycle
            _banner?.Dispose();
        }

        private void OnCreateClicked()
        {
            Log("Create button clicked.");

            // Dispose previous banner instance
            _banner?.Dispose();

            // Create a banner instance
            _banner = Banner.Create("<placement-id>", position: _position);

            // Load Callbacks

            _banner.OnPrebiddingFinished += result => XMediatorMainThreadDispatcher.Enqueue(
                () => { Log("Banner client-side bidding finished!"); }
            );

            _banner.OnLoaded += result => XMediatorMainThreadDispatcher.Enqueue(
                () => { Log("Banner loaded!"); }
            );

            _banner.OnFailedToLoad += (error, result) => XMediatorMainThreadDispatcher.Enqueue(
                () => { Log($"Banner failed to load. Reason: {error.Message}"); }
            );

            // Impression Callback
            _banner.OnImpression += impressionData =>
            {
                Log($"Banner impression!");
            };
        }

        private void OnLoadClicked()
        {
            Log("Load button clicked.");
            _banner?.Load();
        }

        private void OnShowBannerTopClicked()
        {
            Log("Show banner top button clicked.");
            _position = Banner.Position.Top;
            _banner?.Show(_position);
        }

        private void OnShowBannerBottomClicked()
        {
            Log("Show banner bottom button clicked.");
            _position = Banner.Position.Bottom;
            _banner?.Show(_position);
        }

        private void OnHideBannerClicked()
        {
            Log("Hide banner button clicked.");
            _banner?.Hide();
        }

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