优聚智汇

English

简体中文

English

简体中文

Theme

iOS Splash Ad Integration ​

Overview ​

Splash ads are displayed when the app starts and support a countdown. Users can wait for the countdown to end or actively skip to enter the main interface. Splash ads have high exposure rates and strong brand recall.

Integration Steps ​

Refer to the SplashAdHelper in the demo example:

1. Create and Load Splash Ad ​

swift
import UIKit
import UjuAdCore

final class SplashViewController: UIViewController {

    private var splashObject: UjuAdObject?

    override func viewDidLoad() {
        super.viewDidLoad()
        loadSplash()
    }

    private func loadSplash() {
        // 创建广告配置
        let config = UjuAdConfig(placementId: "YOUR_SPLASH_PLACEMENT_ID")
        // 通过工厂方法创建开屏广告对象
        let splash = UjuAdObject.getSplashObject(self, config: config)
        // 设置监听器
        splash.setAdObjectListener(SplashListener(vc: self))
        self.splashObject = splash
        // 开始加载
        splash.load()
    }
}

2. Implement Splash Listener ​

swift
final class SplashListener: SplashAdObjectListener, @unchecked Sendable {
    private weak var vc: UIViewController?

    init(vc: UIViewController) { self.vc = vc }

    func onLoadSuccess() {
        // 加载成功，展示前判断 isReady
        guard let vc = vc, let splashObject = (vc as? SplashViewController)?.splashObject else { return }
        if splashObject.isReady() {
            splashObject.show(vc)
        }
    }

    func onLoadError(error: UjuException) {
        print("开屏加载失败: code=\(error.code) message=\(error.message)")
        // 加载失败，直接进入主界面
    }

    func onAdShow() {
        print("开屏展示")
    }

    func onAdClicked() {
        print("开屏被点击")
    }

    func onAdDismissed() {
        // 开屏被关闭（用户跳过或倒计时结束），进入主界面
        print("开屏倒计时结束，进入主界面")
    }

    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

Countdown and Close ​

onAdDismissed Callback Timing

onAdDismissed() is a callback specific to splash ads (inherited from SplashAdObjectListener), triggered in the following cases:

  • User actively skips the splash (clicks the skip button)
  • Splash countdown ends

It is recommended to enter the main interface in onAdDismissed, not in onAdClosed (the latter only indicates that the ad view was removed).

Best Practices ​

  1. Load early: After completing SDK initialization in AppDelegate.didFinishLaunchingWithOptions, immediately load the splash in the root ViewController
  2. Timeout fallback: It is recommended to set a 3-5 second timeout mechanism; if loading times out, enter the main interface directly to avoid making users wait too long
  3. Resource release: Call destroy() to release resources after the splash finishes displaying
  4. Load failure fallback: Enter the main interface directly on onLoadError without blocking the user

FAQ ​

Q: Why doesn't the splash 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: How should I handle load failures? ​

A: Enter the main interface directly in onLoadError without blocking the user. Splash ad load failure is a normal business response; you can retry after an interval.