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 formatHTML (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()
    }
}

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, onAdDisplayFailed fires and the ad is no longer ready. Call load() 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, and onExpiredAdReloaded fires before it is shown. If no replacement loads, or none is ready within the time limit CloudX sets, onAdDisplayFailed fires.
  • If you call load() while an ad is ready, no new request starts. onAdLoaded fires at once with that ad.
  • A load() call while an ad is showing runs after the ad closes. A load() call while show() waits for a recovery replacement also runs after the show ends, and receives exactly one onAdLoaded or onAdLoadFailed.

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 call onAdLoaded again.
  • 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 the expirationListener is called then. If you call load() after the ad closes while the replacement is still loading, that load() runs its own request and gets onAdLoaded, and no expirationListener call follows for that replacement.
  • If you call load() while the expired ad is still loaded, no new request starts. onAdLoaded fires at once with the expired ad. The replacement keeps loading, and the expirationListener is called when it is ready.
  • If the replacement fails to load while the expired ad is still loaded, onAdLoadFailed fires 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: call load() 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}")
}