Rewarded

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:

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.

Create an Rewarded instance

var rewarded = Rewarded.Create("<placement-id>");

Register ad callbacks

// Load Callbacks

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

rewarded.OnLoaded += result => {
    Debug.Log("Rewarded ad loaded!");
};

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

// Show Callbacks

rewarded.OnShowed += () => {
    Debug.Log("Rewarded ad is being shown!");
};

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

rewarded.OnImpression += impressionData => {
    Debug.Log("Rewarded ad impression!");
};

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

// Reward Callback

rewarded.OnEarnedReward += () => {
    Debug.Log("Rewarded ad earned a reward!");
};

Info

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

Load an ad

rewarded.Load();

Load an ad (with custom properties)

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

Show an ad

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

Dispose an ad

rewarded.Dispose();

Code example

RewardedTest.cs

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

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

        [CanBeNull] private Rewarded _rewarded;

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

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

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

            // Dispose previous rewarded instance
            _rewarded?.Dispose();

            // Create a Rewarded instance
            _rewarded = Rewarded.Create("<placement-id>");

            // Load Callbacks

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

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

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

            // Show Callbacks

            _rewarded.OnShowed += () => XMediatorMainThreadDispatcher.Enqueue(
                () => { Log("Rewarded showed!"); }
            );

            _rewarded.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($"Rewarded failed to show. Reason: {error.Message}"); 
                }
            );

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

            _rewarded.OnDismissed += () => XMediatorMainThreadDispatcher.Enqueue(() =>
            {
                // The user finished watching the rewarded ad, we can resume gameplay
                Log("Rewarded dismissed!");
            });

            // Reward Callback
            _rewarded.OnEarnedReward += () => XMediatorMainThreadDispatcher.Enqueue(() =>
            {
                // The user should be given a reward for watching the ad
                Log("Rewarded earned reward!");
            });

            // Request an Ad
            _rewarded.Load();
        }

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

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

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