优聚智汇

简体中文

English

简体中文

English

外观

iOS 开屏广告集成 ​

概述 ​

开屏广告在 App 启动时展示，支持倒计时。用户可等待倒计时结束或主动跳过进入主界面。开屏广告具有曝光率高、品牌记忆强的特点。

集成步骤 ​

参考 Demo 示例的 SplashAdHelper：

1. 创建并加载开屏广告 ​

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. 实现开屏监听器 ​

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 配置说明 ​

参数类型必填说明
placementIdString是广告位 ID
scenarioKeyString?否广告展示场景标识，用于统计
userIdString?否用户 ID
customData[String: String]?否自定义数据，透传给广告服务端
bidFloorDouble否底价（元，CPM），由第三方聚合平台集成时传入，普通集成方无需设置

倒计时与关闭 ​

onAdDismissed 回调时机

onAdDismissed() 是开屏广告特有的回调（继承自 SplashAdObjectListener），在以下情况触发：

  • 用户主动跳过开屏（点击跳过按钮）
  • 开屏倒计时结束

建议在 onAdDismissed 中进入主界面，不要在 onAdClosed 中进入（后者仅表示广告视图被移除）。

最佳实践 ​

  1. 尽早加载：在 AppDelegate.didFinishLaunchingWithOptions 完成 SDK 初始化后，立即在根 ViewController 中加载开屏
  2. 超时兜底：建议设置 3-5 秒的超时机制，加载超时直接进入主界面，避免用户长时间等待
  3. 资源释放：开屏展示完毕后调用 destroy() 释放资源
  4. 加载失败降级：onLoadError 时直接进入主界面，不阻塞用户

常见问题 ​

Q: 开屏广告为什么不显示？ ​

A: 可能的原因：

  • 广告位 ID 不正确
  • 网络连接问题
  • 广告库存不足（错误码 102 noFill）
  • 未在 onLoadSuccess 后调用 show()，或未检查 isReady()

Q: 加载失败时应如何处理？ ​

A: 在 onLoadError 中直接进入主界面，不要阻塞用户。开屏广告加载失败属于正常业务响应，可间隔一段时间后重试。

相关链接 ​