Interstitial

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:

An interstitial ad is a fullscreen format, usually skippable after the first few seconds of its display. Because of this, it's commonly used in transitions of the app or game, such as completing a level or navigating to a different screen.

Create an Interstitial instance

var interstitial = Interstitial.Create("<placement-id>");

Register ad callbacks

// Load Callbacks

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

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

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

// Show Callbacks

interstitial.OnShowed += () => {
    Debug.Log("Interstitial is being shown!");
};

interstitial.OnFailedToShow += error => {
    // If you need to resume your app's flow, make sure to do it here and in the OnDismissed callback
    Debug.Log($"Interstitial failed to show. Reason: {error.Message}");
};

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

interstitial.OnDismissed += () => {
    // If you need to resume your app's flow, make sure to do it here and in the OnFailedToShow callback
    Debug.Log("Interstitial dismissed! Resume gameplay");
};

Info

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

Load an ad

interstitial.Load();

Load an ad (with custom properties)

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

Show an ad

if (interstitial.IsReady()) {
    interstitial.Show("interstitial-ad-space");
}

Dispose an ad

interstitial.Dispose();

Code example

InterstitialTest.cs

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

namespace X3M.XMediatorTest.Scripts
{
    public class InterstitialTest : MonoBehaviour
     {
        public Button LoadButton;
        public Button CheckIsReadyButton;
        public Button ShowButton;

        [CanBeNull] private Interstitial _interstitial;

        private void Start()
        {
            LoadButton.onClick.AddListener(OnLoadClicked);
            CheckIsReadyButton.onClick.AddListener(OnCheckIsReadyClicked);
            ShowButton.onClick.AddListener(OnShowClicked);
        }

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

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

            // Dispose previous interstitial instance
            _interstitial?.Dispose();

            // Create an Interstitial instance
            _interstitial = Interstitial.Create("<placement-id>");

            // Load Callbacks

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

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

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

            // Show Callbacks

            _interstitial.OnShowed += () => XMediatorMainThreadDispatcher.Enqueue(
                () => { Log("Interstitial is being shown!"); }
            );

            _interstitial.OnFailedToShow += error => XMediatorMainThreadDispatcher.Enqueue(
                () => { 
                    // If you need to resume your app's flow, make sure to do it here and in the OnDismissed callback
                    Log($"Interstitial failed to show. Reason: {error.Message}"); 
                }
            );

            _interstitial.OnImpression += impressionData =>
            {
                Log($"Interstitial impression!");
            };

            _interstitial.OnDismissed += () => XMediatorMainThreadDispatcher.Enqueue(
                () => { 
                    // If you need to resume your app's flow, make sure to do it here and in the OnFailedToShow callback
                    Log("Interstitial dismissed! Resume gameplay"); 
                }
            );

            // Request an Ad

            _interstitial.Load();
        }

        private void OnCheckIsReadyClicked()
        {
            Log("Check Is Ready button clicked.");
            var isReady = _interstitial?.IsReady();
            Log($"Interstitial.IsReady() -> {isReady}");
        }

        private void OnShowClicked()
        {
            Log("Show button clicked.");
            _interstitial?.Show();
        }

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