RewardedAd

Gates an in-app reward behind a mini-game. The user plays for a minimum duration, then claims their reward. Reward verification happens server-side for tamper resistance.

Basic Usage

import ad.simula.ad.sdk.ads.SimulaRewardedAd
import ad.simula.ad.sdk.ads.SimulaRewardedAdListener
import ad.simula.ad.sdk.ads.SimulaAdError

class RewardGateActivity : ComponentActivity() {
    private val rewarded = SimulaRewardedAd("SIM-RWD-XXXXXXXX")

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)

        rewarded.listener = object : SimulaRewardedAdListener {
            override fun onAdLoaded(ad: SimulaRewardedAd) {
                // Ready to show
            }
            override fun onAdFailedToLoad(ad: SimulaRewardedAd, error: SimulaAdError) {
                // Retry with exponential backoff
            }
            override fun onAdEarnedReward(ad: SimulaRewardedAd) {
                // Client-side play-time threshold met (not yet server-verified)
            }
            override fun onAdRewardVerified(ad: SimulaRewardedAd, token: String?) {
                // Server verified the play — grant the reward here
                grantMessageCredits(10, token)
            }
            override fun onAdRewardVerificationFailed(ad: SimulaRewardedAd, error: Throwable) {
                showError("Reward verification failed")
            }
            override fun onAdClosed(ad: SimulaRewardedAd) {
                // Next ad auto-preloads
            }
        }

        rewarded.load(
            charId = "reze-01",
            charName = "Reze",
            charImage = "https://cdn.example.com/avatars/reze.png",
        )
    }

    fun showRewardedAd() {
        rewarded.show(this)
    }
}

Constructor & Properties

Property	Type	Default	Description
adUnitId	String	required	Ad unit ID from the publisher dashboard

AI Character Integration

Same as InterstitialAd — pass your app's character data so the character plays alongside the user in the ad playable experience. The character commentates, competes, and engages with the user during gameplay, improving the ad experience and raising payout.

Parameter	Type	Required	Description
charId	String?	No	Character identifier
charName	String?	No	Character name displayed in game header
charImage	String?	No	Character avatar URL
charDesc	String?	No	Character description

Listener Interface

Extends the interstitial listener with reward-specific callbacks. All callbacks are delivered on the main thread.

Method	Description
onAdLoaded(ad)	Ad is preloaded and ready to show()
onAdFailedToLoad(ad, error)	Load failed. Retry with backoff
onAdDisplayed(ad)	Ad is on screen
onAdFailedToDisplay(ad, error)	Presentation failed
onAdClicked(ad)	User tapped the CTA
onAdImpression(ad)	Impression recorded (server impression beacon fired)
onAdPaid(ad, adValue)	Estimated per-impression revenue available. See AdValue
onAdEarnedReward(ad)	User played long enough. Client-side signal only -- fires before server verification
onAdRewardVerified(ad, token)	Server verified the play session. Grant the reward here. token is the verification token (null on re-verification)
onAdRewardVerificationFailed(ad, error)	Verification failed. The background queue may still retry
onAdClosed(ad)	User dismissed the ad. Next ad auto-preloads

Reward Verification Flow

1. User plays the mini-game for the required duration
2. onAdEarnedReward fires (client-side play-time threshold met -- not yet verified)
3. The SDK verifies the play session with the Simula server (off the UI thread)
4. onAdRewardVerified fires with a verification token -- grant the reward here
5. If you use Server-Side Verification (SSV), Simula's server also sends a POST to your callback URL

Grant rewards on onAdRewardVerified, not onAdEarnedReward

onAdRewardVerified is the trusted signal -- it fires after the server verifies the play session and includes a verification token. onAdEarnedReward is a client-side signal that fires before verification completes. Verification is durable: the native SDK retries in the background and may deliver onAdRewardVerified after the ad closes or even after app relaunch.

Lifecycle

Same rules as InterstitialAd:

• Auto-preload on close
• 1-hour expiry
• 5-minute deduplication window