优聚智汇

English

简体中文

English

简体中文

Theme

iOS Interstitial Ad Integration ​

Overview ​

Interstitial ads are full-page ads displayed at natural transition points in the app (such as level completion, video pause). Unlike splash ads, interstitials can be triggered at any point during app operation, offering strong exposure and high conversion.

Integration Steps ​

1. Create and Load Interstitial Ad ​

swift
import UIKit
import UjuAdCore

final class InterstitialAdHelper {
    private var interstitialAd: UjuAdObject?

    func load(vc: UIViewController) {
        let config = UjuAdConfig(placementId: "YOUR_INTERSTITIAL_PLACEMENT_ID")
        let interstitial = UjuAdObject.getInterstitialObject(vc, config: config)
        interstitial.setAdObjectListener(InterstitialListener())
        self.interstitialAd = interstitial
        interstitial.load()
    }

    func show(vc: UIViewController) {
        // 展示前判断 isReady
        if interstitialAd?.isReady() == true {
            interstitialAd?.show(vc)
        }
    }

    func destroy() {
        interstitialAd?.destroy()
        interstitialAd = nil
    }
}

2. Implement Interstitial Listener ​

swift
final class InterstitialListener: InterstitialAdObjectListener, @unchecked Sendable {
    func onLoadSuccess() {
        // 广告加载成功，可在合适时机调用 show()
    }

    func onLoadError(error: UjuException) {
        print("插屏加载失败: \(error.description)")
    }

    func onAdShow() {
        // 广告展示
    }

    func onAdClicked() {
        // 广告被点击
    }

    func onAdPlayComplete() {
        // 插屏播放完成（视频插屏时触发）
    }

    func onAdClosed() {
        // 广告关闭，恢复 App 交互
    }

    func onAdError(error: UjuException) {
        print("插屏展示错误: \(error.description)")
    }
}

UjuAdConfig Configuration ​

ParameterTypeRequiredDescription
placementIdStringYesAd placement ID
scenarioKeyString?NoAd display scenario identifier, used for analytics
userIdString?NoUser ID
customData[String: String]?NoCustom data, passed through to the ad server
bidFloorDoubleNoBid floor (CNY, CPM), passed by aggregation platform, not needed for normal integrators

Display Timing ​

Display Timing Recommendations

Interstitial ads should be displayed at natural transition points in the app, avoiding interruption of core user operations:

  • Natural pause points such as level completion, video pause, page transitions
  • Avoid popping up in areas with high user interaction frequency
  • Control display frequency to avoid excessive disruption

Best Practices ​

  1. Preload: Call load() in advance; only show() is needed at display time
  2. Check before showing: Always check isReady() before calling show()
  3. Frequency control: Control interstitial display frequency yourself to avoid affecting user experience
  4. Resource release: Call destroy() after the ad is closed

FAQ ​

Q: Why doesn't the interstitial ad show? ​

A: Possible causes:

  • Incorrect ad placement ID
  • Network connection issues
  • Insufficient ad inventory (error code 102 noFill)
  • Did not call show() after onLoadSuccess, or did not check isReady()

Q: What is the difference between interstitial and splash ads? ​

A: Splash ads are displayed at app startup, listened to via SplashAdObjectListener, and have an onAdDismissed callback. Interstitial ads are displayed during app operation, listened to via InterstitialAdObjectListener, and have an onAdPlayComplete callback.