Skip to main content

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 (or equivalent) 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 a rewarded​

#include "x3mads/XMediatorAds.hpp"
// Initialize the SDK once, then load a rewarded
x3mads::XMediatorAds::getInstance()->startWith(
    "<your-app-key>",
    x3mads::InitSettings(),
    [](const x3mads::InitResult& result) {
        x3mads::XMediatorAds::getInstance()->rewarded->load("<placement-id>");
    }
);

Showing a rewarded​

Calling isReady() returns whether a rewarded is available to be shown, regardless of placement ID. If multiple ads with different placement IDs were previously loaded, the SDK will try to show the best one available.

if (x3mads::XMediatorAds::getInstance()->rewarded->isReady()) {
    x3mads::XMediatorAds::getInstance()->rewarded->show();
}
info

You don't need to check isReady() before calling show(). If there isn't an ad ready, your listener's onFailedToShow(...) will be called.

Auto loading​

Ads that are dismissed or fail to show automatically trigger a new load request.

Auto retry​

Failed loads will be retried with exponential backoff.

Additional settings​

Add listener​

Every ad callback indicates the placement ID of the rewarded that triggered the event.

// Register rewarded callbacks via a listener
struct MyRewardedListener : public x3mads::RewardedAdsListener {
    void onEarnedReward(const std::string& placementId) override {
        CCLOG("%s Rewarded earned a reward!", placementId.c_str());
    }
    void onImpression(const std::string& placementId, const x3mads::ImpressionData& data) override {
        CCLOG("Rewarded impression! placementId: %s", placementId.c_str());
    }
    void onClicked(const std::string& placementId) override {
        CCLOG("Rewarded clicked! placementId: %s", placementId.c_str());
    }
    void onLoaded(const std::string& placementId, const x3mads::LoadResult& result) override {
        CCLOG("Rewarded loaded! placementId: %s", placementId.c_str());
    }
    void onShowed(const std::string& placementId) override {
        CCLOG("Rewarded is being shown! placementId: %s", placementId.c_str());
    }
    void onFailedToShow(const std::string& placementId, const x3mads::Error& error) override {
        // If you need to resume your app's flow, do it here and in onDismissed
        CCLOG("Rewarded failed to show. placementId: %s", placementId.c_str());
    }
    void onDismissed(const std::string& placementId) override {
        // If you need to resume your app's flow, do it here and in onFailedToShow
        CCLOG("Rewarded dismissed! placementId: %s", placementId.c_str());
    }
};

auto listener = new MyRewardedListener();
x3mads::XMediatorAds::getInstance()->rewarded->addListener(listener);

Remove listener​

If you add a listener, you should remove it when your scene/object is destroyed to stop receiving events.

void RewardedExample::cleanup()
{
    x3mads::XMediatorAds::getInstance()->rewarded->removeListener(listener);
    Scene::cleanup();
}

Showing a rewarded with ad space​

x3mads::XMediatorAds::getInstance()->rewarded->showFromAdSpace("ad-space");

Showing a rewarded with placement ID​

Calling isReady("<placement-id>") returns whether a rewarded is available to be shown.

if (x3mads::XMediatorAds::getInstance()->rewarded->isReady("<placement-id>")) {
    // show without ad space
    x3mads::XMediatorAds::getInstance()->rewarded->show("<placement-id>");
    // or show with ad space
    x3mads::XMediatorAds::getInstance()->rewarded->show("<placement-id>", "ad-space");
}

Code example​

Below is a Cocos2d-x example showing how to load, check readiness, and show a rewarded.

RewardedExample.cpp
void showRewarded()
{
    auto* sdk = x3mads::XMediatorAds::getInstance();
    if (sdk->rewarded->isReady()) {
        sdk->rewarded->show();
    }
}

x3mads::XMediatorAds::getInstance()->startWith(
    "<your-app-key>", 
    x3mads::InitSettings(), 
    [=](const x3mads::InitResult&) {
        x3mads::XMediatorAds::getInstance()->rewarded->addListener(this);
        x3mads::XMediatorAds::getInstance()->rewarded->load("<placement-id>");
    }
);