Rewarded

Rewarded ads (also known as rewarded video ads) are a fullscreen format, but unlike interstitials the user is incentivized to watch its entire duration (usually 30 seconds) in order to get an in-app reward, such as in-game currency, extra lives or hints to pass a level.

The OnEarnedReward callback will be triggered by the adapted network, signaling that you can give the user their reward. If the user decides to skip the ad, this callback will not be called.

Start loading an ad

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

Showing an ad

Calling IsReady() will return if there's a rewarded ad 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.Rewarded.IsReady()) {
    XMediatorAds.Rewarded.ShowFromAdSpace("rewarded-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.Rewarded.IsReady("<placement-id>")) {
    XMediatorAds.Rewarded.ShowFromAdSpace("<placement-id>", "rewarded-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 rewarded ad that triggered the event.

// Reward Callback
XMediatorAds.Rewarded.OnEarnedReward += placementId => {
    Debug.Log($"{placementId} Rewarded ad earned a reward!");
};

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

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

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

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

// Failed to show callback
XMediatorAds.Rewarded.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($"Rewarded failed to show. placementId: {placementId}, Reason: {error.Message}");
};

// Dismissed callback
XMediatorAds.Rewarded.OnDismissed += placementId => {
    // If you need to resume your app's flow, make sure to do it here and in the OnFailedToShow callback
    Debug.Log($"Rewarded 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 a rewarded 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

RewardedTest.cs

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

public class RewardedTest : 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.Rewarded.OnEarnedReward += placementId => XMediatorMainThreadDispatcher.Enqueue(
            () => { Log($"Rewarded earned for placement: {placementId}"); }
        );
        XMediatorAds.Rewarded.OnImpression += (placementId, impressionData) =>
        {
            Log($"Rewarded impression for placement: {placementId}");
        };
        XMediatorAds.Rewarded.OnClicked += placementId =>
        {
            Log($"Rewarded clicked for placement: {placementId}");
        };
        XMediatorAds.Rewarded.OnLoaded += (placementId, loadResult) => XMediatorMainThreadDispatcher.Enqueue(
            () => { Log($"Rewarded loaded for placement: {placementId}"); }
        );
        XMediatorAds.Rewarded.OnShowed += placementId => XMediatorMainThreadDispatcher.Enqueue(
            () => { Log($"Rewarded is being shown for placement: {placementId}"); }
        );
        XMediatorAds.Rewarded.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($"Rewarded failed to show for placement: {placementId}"); 
            }
        );
        XMediatorAds.Rewarded.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($"Rewarded dismissed for placement: {placementId}"); 
            }
        );

        // Start loading a rewarded. Subsequent loads or retries are handled by the sdk
        XMediatorAds.Rewarded.Load(YourPlacementId);
    }

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

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

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