InterstitialAd

Full-screen ad that displays at natural transition points -- between sessions, after a conversation ends, or at a message threshold. Users play a sponsored mini-game with an AI character.

Basic Usage

import SimulaAdSDK

class ChatViewModel: ObservableObject, SimulaInterstitialAdDelegate {
    private let interstitial = SimulaInterstitialAd(adUnitId: "SIM-INT-XXXXXXXX")
    @Published var isLoaded = false

    init() {
        interstitial.delegate = self
        interstitial.load(
            charId: "reze-01",
            charName: "Reze",
            charImage: "https://cdn.example.com/avatars/reze.png"
        )
    }

    func showAd() {
        interstitial.show()
    }

    // MARK: - SimulaInterstitialAdDelegate

    func interstitialDidLoad(_ ad: SimulaInterstitialAd) {
        isLoaded = true
    }

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

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

SwiftUI View

struct ChatView: View {
    @StateObject private var vm = ChatViewModel()

    var body: some View {
        VStack {
            // Chat content
        }
        .toolbar {
            Button("Show Ad") { vm.showAd() }
                .disabled(!vm.isLoaded)
        }
    }
}

AI Character Integration

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. Omit to use a Simula default character.

Character context drives engagement

Passing character context lets the AI companion in the ad playable match your app's character — using their name, avatar, and personality. Users see a familiar face instead of a generic character, which increases play time and ad revenue.

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 for AI context

Metadata

Attach up to 10 key/value labels to segment your reporting. Set them before load():

interstitial.setMetadata("screen", "chat")                       // upsert one key
interstitial.setMetadata(["screen": "chat", "tier": "free"])     // replace all

Keys: ≤64 chars, no $ prefix, no .. Values: ≤256 chars. Extra or invalid entries are dropped.

Delegate Protocol

All delegate methods are optional and called on the main thread.

Method	Description
interstitialDidLoad(_:)	Ad is preloaded and ready to show()
interstitialDidFailToLoad(_:error:)	Load failed. Inspect error and retry with backoff
interstitialDidDisplay(_:)	Ad is on screen
interstitialDidFailToDisplay(_:error:)	Presentation failed. Call load() to try again
interstitialDidClick(_:)	User tapped the CTA
interstitialDidRecordImpression(_:)	Impression recorded (server impression beacon fired)
interstitialDidPay(_:value:)	Estimated per-impression revenue available. See AdValue
interstitialDidClose(_:)	User dismissed the ad. Next ad auto-preloads with the same character context

Lifecycle

• Auto-preload on close: The SDK automatically preloads the next ad when the user dismisses the current one. You do not need to call load() again after interstitialDidClose.
• 1-hour expiry: A loaded ad expires after 1 hour. show() fails with .stale -- call load() again.
• Deduplication: Calling load() with the same parameters within 5 minutes returns .duplicateRequest. Wait for the retry window or change the character context.