Interstitial

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.

To start using interstitial ads, just call Load() using a valid placement id and then use one of the available Show() functions when you need it to be displayed.

Start loading an ad

XMediatorAds.StartWith(
    appKey: "<your-app-key>",
    initCallback: result => 
    {
        XMediatorAds.Interstitial.Load("<placement-id>");
    }
);

Showing an ad

Calling IsReady() will return if there's an interstitial available to be shown, regardless of its placement id. If multiple ads with different placement ids were previously loaded, the SDK will try to show the best one available.

if (XMediatorAds.Interstitial.IsReady()) {
    XMediatorAds.Interstitial.ShowFromAdSpace("interstitial-ad-space");
}

Showing an ad with placementId

When the app needs to show an ad for a specific placement id, IsReady("<placement-id>") and Show("<placement-id>") can be alternatively used.

if (XMediatorAds.Interstitial.IsReady("<placement-id>")) {
    XMediatorAds.Interstitial.ShowFromAdSpace("<placement-id>", "interstitial-ad-space");
}

Built-in features

Auto loading

Dismissed or failed to show ads will automatically trigger a new load request.

Auto retry

Failed to load ads will make a retry attempts, with an exponential backoff.

Additional settings

Register ad callbacks

Every ad callback indicates the placement id of the interstitial ad that triggered the event.

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

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

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

// Showed Callback
XMediatorAds.Interstitial.OnShowed += placementId => {
    Debug.Log($"Interstitial is being shown! placementId: {placementId}");
};

// Failed to show callback
XMediatorAds.Interstitial.OnFailedToShow += (placementId, 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. placementId: {placementId}, Reason: {error.Message}");
};

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

Info

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

Advanced use cases

This guide provides the recommended integration steps to show an interstitial 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

InterstitialTest.cs

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

public class InterstitialTest : MonoBehaviour
{
    public Button CheckIsReadyButton;
    public Button ShowButton;

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

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

        // Setup callbacks
        XMediatorAds.Interstitial.OnImpression += (placementId, impressionData) =>
        {
            Log($"Interstitial impression for placement: {placementId}");
        };
        XMediatorAds.Interstitial.OnClicked += placementId =>
        {
            Log($"Interstitial clicked for placement: {placementId}");
        };
        XMediatorAds.Interstitial.OnLoaded += (placementId, loadResult) => XMediatorMainThreadDispatcher.Enqueue(
            () => { Log($"Interstitial loaded for placement: {placementId}"); }
        );
        XMediatorAds.Interstitial.OnShowed += placementId => XMediatorMainThreadDispatcher.Enqueue(
            () => { Log($"Interstitial is being shown for placement: {placementId}"); }
        );
        XMediatorAds.Interstitial.OnFailedToShow += (placementId, showError) => 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 for placement: {placementId}"); 
            }
        );
        XMediatorAds.Interstitial.OnDismissed += placementId => 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 for placement: {placementId}"); 
            }
        );

        // Start loading an interstitial. Subsequent loads or retries are handled by the sdk
        XMediatorAds.Interstitial.Load(YourPlacementId);
    }

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

    private void OnShowClicked()
    {
        Log("Show button clicked.");
        XMediatorAds.Interstitial.Show();
    }

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