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 SimulaAdSDK

class RewardGateViewModel: ObservableObject, SimulaRewardedAdDelegate {
    private let rewarded: SimulaRewardedAd
    @Published var isLoaded = false

    init() {
        rewarded = SimulaRewardedAd(adUnitId: "SIM-RWD-XXXXXXXX")
        rewarded.delegate = self
        rewarded.load(
            charId: "reze-01",
            charName: "Reze",
            charImage: "https://cdn.example.com/avatars/reze.png"
        )
    }

    func showAd() {
        rewarded.show()
    }

    // MARK: - SimulaRewardedAdDelegate

    func rewardedDidLoad(_ ad: SimulaRewardedAd) {
        isLoaded = true
    }

    func rewardedDidFailToLoad(_ ad: SimulaRewardedAd, error: SimulaAdError) {
        // Retry with exponential backoff
    }

    func rewardedDidEarnReward(_ ad: SimulaRewardedAd) {
        // Client-side play-time threshold met (not yet server-verified)
    }

    func rewardedDidVerifyReward(_ ad: SimulaRewardedAd, token: String?) {
        // Server verified the play — grant the reward here
        grantMessageCredits(10, token: token)
    }

    func rewardedRewardVerificationDidFail(_ ad: SimulaRewardedAd, error: Error) {
        showError("Reward verification failed")
    }

    func rewardedDidClose(_ ad: SimulaRewardedAd) {
        isLoaded = false
        // Next ad auto-preloads
    }
}

SwiftUI View

struct RewardGateView: View {
    @StateObject private var vm = RewardGateViewModel()

    var body: some View {
        Button("Watch an ad to earn 10 credits") { vm.showAd() }
            .disabled(!vm.isLoaded)
    }
}

Constructor Parameters

Parameter	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

Delegate Protocol

Extends the interstitial delegate with reward-specific callbacks. All methods are optional and called on the main thread.

Method	Description
rewardedDidLoad(_:)	Ad is preloaded and ready to show()
rewardedDidFailToLoad(_:error:)	Load failed. Retry with backoff
rewardedDidDisplay(_:)	Ad is on screen
rewardedDidFailToDisplay(_:error:)	Presentation failed
rewardedDidClick(_:)	User tapped the CTA
rewardedDidRecordImpression(_:)	Impression recorded (server impression beacon fired)
rewardedDidPay(_:value:)	Estimated per-impression revenue available. See AdValue
rewardedDidEarnReward(_:)	User played long enough. Client-side signal only -- fires before server verification
rewardedDidVerifyReward(_:token:)	Server verified the play session. Grant the reward here. token is the verification token (nil on re-verification)
rewardedRewardVerificationDidFail(_:error:)	Verification failed. The background queue may still retry
rewardedDidClose(_:)	User dismissed the ad. Next ad auto-preloads

Reward Verification Flow

1. User plays the mini-game for the required duration
2. rewardedDidEarnReward fires (client-side play-time threshold met -- not yet verified)
3. The SDK verifies the play session with the Simula server (off the main thread)
4. rewardedDidVerifyReward 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 rewardedDidVerifyReward, not rewardedDidEarnReward

rewardedDidVerifyReward is the trusted signal -- it fires after the server verifies the play session and includes a verification token. rewardedDidEarnReward is a client-side signal that fires before verification completes. Verification is durable: the native SDK retries in the background and may deliver rewardedDidVerifyReward 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