Rewarded Ads
Integrate CloudX rewarded ads in Android apps
Rewarded ads give users a reward — typically in-app currency or bonus content — in exchange for watching a fullscreen ad.
CloudX-rendered creatives
CloudX-served creatives are rendered by the built-in renderer, which ships inside the core SDK — no separate renderer adapter module is required. The creative type is selected automatically from the bid response, so no publisher integration is needed to render either format. The renderer supports MRAID 3.0 (HTML) and VAST creatives across the ad formats:
| Ad format | HTML (MRAID 3.0) | VAST |
|---|---|---|
| Banner | ✓ | — |
| MREC | ✓ | ✓ |
| Interstitial | ✓ | ✓ |
| Rewarded | ✓ | ✓ |
class MainActivity : AppCompatActivity(), CloudXRewardedListener, CloudXAdRevenueListener {
private lateinit var rewardedAd: CloudXRewardedAd
private var retryAttempt = 0
private fun createRewardedAd() {
rewardedAd = CloudX.createRewarded(this, "your-rewarded-ad-unit-id")
rewardedAd.listener = this
rewardedAd.revenueListener = this
rewardedAd.load()
}
private fun showRewardedAd() {
if (rewardedAd.isAdReady) {
// Basic show
rewardedAd.show(this)
// Or with optional placement and custom data for tracking
// rewardedAd.show(this, "bonus_coins", "level:5,coins:100")
} else {
Log.w("CloudX", "Rewarded ad not ready yet")
}
}
// CloudXRewardedListener callbacks
override fun onAdLoaded(cloudXAd: CloudXAd) {
Log.d("CloudX", "Rewarded ad loaded from ${cloudXAd.networkName}")
retryAttempt = 0
}
/**
* Retries loading with exponential backoff: delay doubles with each attempt
* (2s → 4s → 8s … 32s max) to avoid hammering the server during transient
* failures. [retryAttempt] resets to 0 in [onAdLoaded].
*/
override fun onAdLoadFailed(adUnitId: String, cloudXError: CloudXError) {
Log.e("CloudX", "Rewarded ad failed to load: ${cloudXError.message}")
retryAttempt++
val delayMillis = TimeUnit.SECONDS.toMillis(2.0.pow(retryAttempt.coerceAtMost(5)).toLong())
Handler(Looper.getMainLooper()).postDelayed({ rewardedAd.load() }, delayMillis)
}
override fun onAdDisplayed(cloudXAd: CloudXAd) {
Log.d("CloudX", "Rewarded ad displayed")
}
override fun onAdDisplayFailed(cloudXAd: CloudXAd, cloudXError: CloudXError) {
Log.e("CloudX", "Rewarded ad failed to display: ${cloudXError.message}")
rewardedAd.load()
}
override fun onAdHidden(cloudXAd: CloudXAd) {
Log.d("CloudX", "Rewarded ad hidden")
// Reload for next use
rewardedAd.load()
}
override fun onAdClicked(cloudXAd: CloudXAd) {
Log.d("CloudX", "Rewarded ad clicked")
}
override fun onUserRewarded(cloudXAd: CloudXAd, reward: CloudXReward) {
Log.d("CloudX", "User rewarded: ${reward.amount} ${reward.label}")
// Grant the reward to the user
}
// CloudXAdRevenueListener callback
override fun onAdRevenuePaid(cloudXAd: CloudXAd) {
Log.d("CloudX", "Rewarded bid-time revenue: ${cloudXAd.revenue} from ${cloudXAd.networkName}")
}
override fun onDestroy() {
super.onDestroy()
rewardedAd.destroy()
}
}public class MainActivity extends AppCompatActivity implements CloudXRewardedListener, CloudXAdRevenueListener {
private CloudXRewardedAd rewardedAd;
private int retryAttempt;
private void createRewardedAd() {
rewardedAd = CloudX.createRewarded(this, "your-rewarded-ad-unit-id");
rewardedAd.setListener(this);
rewardedAd.setRevenueListener(this);
rewardedAd.load();
}
private void showRewardedAd() {
if (rewardedAd.isAdReady()) {
// Basic show
rewardedAd.show(this);
// Or with optional placement and custom data for tracking
// rewardedAd.show(this, "bonus_coins", "level:5,coins:100");
} else {
Log.w("CloudX", "Rewarded ad not ready yet");
}
}
@Override
protected void onDestroy() {
super.onDestroy();
if (rewardedAd != null) {
rewardedAd.destroy();
}
}
// CloudXRewardedListener callbacks
@Override
public void onAdLoaded(@NonNull CloudXAd cloudXAd) {
Log.d("CloudX", "Rewarded ad loaded from " + cloudXAd.getNetworkName());
retryAttempt = 0;
}
@Override
public void onAdLoadFailed(@NonNull String adUnitId, @NonNull CloudXError cloudXError) {
Log.e("CloudX", "Rewarded ad failed to load: " + cloudXError.getMessage());
retryAttempt++;
long delayMillis = TimeUnit.SECONDS.toMillis((long) Math.pow(2, Math.min(5, retryAttempt)));
new Handler(Looper.getMainLooper()).postDelayed(() -> rewardedAd.load(), delayMillis);
}
@Override
public void onAdDisplayed(@NonNull CloudXAd cloudXAd) {
Log.d("CloudX", "Rewarded ad displayed");
}
@Override
public void onAdDisplayFailed(@NonNull CloudXAd cloudXAd, @NonNull CloudXError cloudXError) {
Log.e("CloudX", "Rewarded ad failed to display: " + cloudXError.getMessage());
rewardedAd.load();
}
@Override
public void onAdHidden(@NonNull CloudXAd cloudXAd) {
Log.d("CloudX", "Rewarded ad hidden");
// Reload for next use
rewardedAd.load();
}
@Override
public void onAdClicked(@NonNull CloudXAd cloudXAd) {
Log.d("CloudX", "Rewarded ad clicked");
}
@Override
public void onUserRewarded(@NonNull CloudXAd cloudXAd, @NonNull CloudXReward reward) {
Log.d("CloudX", "User rewarded: " + reward.getAmount() + " " + reward.getLabel());
// Grant the reward to the user
}
// CloudXAdRevenueListener callback
@Override
public void onAdRevenuePaid(@NonNull CloudXAd cloudXAd) {
Log.d("CloudX", "Rewarded bid-time revenue: " + cloudXAd.getRevenue() + " from " + cloudXAd.getNetworkName());
}
}Ad readiness
isAdReady is true from the moment an ad loads until you show it or destroy the ad object. An ad network can stop being able to show an ad without telling the SDK. isAdReady stays true in that case, and the problem is found when you call show(). If the network does report that its ad has expired, the ad is no longer ready.
- If you call
show()on an ad the network can no longer show,onAdDisplayFailedfires and the ad is no longer ready. Callload()to get a new ad. - In that case, if CloudX has enabled show recovery for your app and ad unit, the SDK loads a replacement and shows it instead. You receive the replacement’s display and revenue callbacks, and no
onAdDisplayFailed. If an expired-ad replacement is already loading, the SDK uses it, andonExpiredAdReloadedfires before it is shown. If no replacement loads, or none is ready within the time limit CloudX sets,onAdDisplayFailedfires. - If you call
load()while an ad is ready, no new request starts.onAdLoadedfires at once with that ad. - A
load()call while an ad is showing runs after the ad closes. Aload()call whileshow()waits for a recovery replacement also runs after the show ends, and receives exactly oneonAdLoadedoronAdLoadFailed.
Expired ads
A loaded ad that is not shown before it expires is reloaded automatically on the same ad object. The current ad stays ready and can still be shown until the replacement is ready.
- To be told when a replacement is ready, set an
expirationListener. A replacement that loads on its own does not callonAdLoadedagain. - If you show the ad while the replacement loads, the replacement is kept. If it is ready when the ad closes, or no
load()comes before it is ready, it becomes ready on the ad object and theexpirationListeneris called then. If you callload()after the ad closes while the replacement is still loading, thatload()runs its own request and getsonAdLoaded, and noexpirationListenercall follows for that replacement. - If you call
load()while the expired ad is still loaded, no new request starts.onAdLoadedfires at once with the expired ad. The replacement keeps loading, and theexpirationListeneris called when it is ready. - If the replacement fails to load while the expired ad is still loaded,
onAdLoadFailedfires and the ad is no longer ready. Reload and its retries are set per ad unit by CloudX, and retries are off by default, so one no-fill ends here. This is the normal outcome, not an integration error: callload()again after a delay rather than in a tight loop.
rewardedAd.expirationListener = CloudXAdExpirationListener { expiredAd, newAd ->
Log.d("CloudX", "Expired rewarded ad replaced by an ad from ${newAd.networkName}")
}rewardedAd.setExpirationListener((expiredAd, newAd) ->
Log.d("CloudX", "Expired rewarded ad replaced by an ad from " + newAd.getNetworkName()));