iOS API 参考
本文档是优聚智汇 iOS SDK 的 API 参考手册，涵盖全部公共枚举与核心类的完整签名。所有内容均基于 SDK 源码验证，供开发者在集成过程中查阅。
枚举参考
AdFormat
广告格式枚举，描述 SDK 支持的 5 种广告类型。
| 枚举值 | 数值 | 含义 |
|---|---|---|
.splash | 0 | 开屏广告 |
.banner | 1 | 横幅广告 |
.native | 2 | 原生/信息流广告 |
.reward | 3 | 激励视频 |
.interstitial | 4 | 插屏广告 |
FeedType
信息流广告子类型枚举，标识渲染模式。通过 UjuAdObject.getFeedType() 获取。
| 枚举值 | 数值 | 含义 |
|---|---|---|
.express | 0 | 模板渲染（SDK 提供模板，当前版本未启用） |
.banner | 1 | 横幅模板（横幅广告固定返回此值） |
.native | 2 | 自渲染（业务方提供视图，原生广告固定返回此值） |
let feedType = adObject.getFeedType()
switch feedType {
case .native:
// 自渲染，需调用 getAdData() 获取物料并自行绑定视图
case .banner:
// 横幅模板
default:
break
}当前版本渲染模式
当前版本中，原生广告 getFeedType() 固定返回 .native（自渲染），横幅广告固定返回 .banner。.express 模板渲染模式将在后续版本支持。
AdMediaType
自渲染广告的媒体素材类型。
| 枚举值 | 数值 | 含义 |
|---|---|---|
.singleImage | 1 | 单图素材 |
.multiImage | 2 | 多图素材（组图） |
.video | 3 | 视频素材 |
AdBidType
广告竞价类型，标识广告位的竞价模式。
| 枚举值 | 数值 | 含义 |
|---|---|---|
.normal | 0 | 普通模式（无竞价，瀑布流直跑） |
.adx | 1 | ADX 模式（优聚自有 ADX API） |
.c2s | 2 | 客户端到服务端竞价（C2S） |
.s2s | 3 | 服务端到服务端竞价（S2S） |
AdPlatformType
广告平台标识枚举，用于标识广告来源的 ADN 平台。
| 枚举值 | 数值 | 平台名称 | 说明 |
|---|---|---|---|
.csj | 1 | 穿山甲 | 字节跳动穿山甲（Pangle） |
.ylh | 2 | 优量汇 | 腾讯优量汇（GDT） |
.bd | 3 | 百度 | 百度百青藤 |
.ks | 4 | 快手 | 快手广告 |
.vivo | 13 | VIVO | VIVO 广告平台 |
.oppo | 14 | OPPO | OPPO 广告平台 |
.adx | 100 | ADX | 优聚内部 ADX（平台 ID 统一为 100） |
ADX 自有广告源
ADX 自有广告源已内置在核心库中，无需额外注册。通过 UjuAdInfo.platformId 获取到的 ADX 广告平台 ID 统一为 100。
UjuAdInitStatus
SDK 初始化状态枚举，可通过 UjuAdCore.shared.getInitializeState() 获取。
| 枚举值 | 数值 | 含义 |
|---|---|---|
.idle | 0 | 空闲状态（未启动） |
.initializing | 1 | 初始化中（start 已调用，流程执行中） |
.initialized | 2 | 初始化完成（可调用广告 API） |
.failed | 3 | 初始化失败（需重新调用 start） |
UjuAdRegion
服务区域枚举，集成方仅需选择区域，各服务 host 由 SDK 内部自动推导。
| 枚举值 | 含义 |
|---|---|
.domestic | 国内 |
.singapore | 海外（新加坡） |
公共 API 参考
UjuAdCore
SDK 全局入口，final class 单例（UjuAdCore.shared），标注 @unchecked Sendable。负责 SDK 初始化、启动、状态查询与资源释放。
方法列表
| 方法签名 | 返回值 | 说明 |
|---|---|---|
initialize(_ application: AnyObject?, config: UjuAdInitConfig) | Void | 第一阶段初始化，同步保存配置，不采集隐私 |
start(_ listener: BaseInitListener?) | Void | 第二阶段启动，采集设备信息并拉取策略，完成后回调 listener |
isSdkInitialized() | Bool | 是否已完成 initialize（第一阶段） |
getInitializeState() | UjuAdInitStatus | 获取 SDK 初始化状态枚举 |
getVersion() | String | 获取 SDK 版本号（当前 3.4.8） |
getAppId() | String | 获取当前应用 ID |
getRegion() | UjuAdRegion | 获取服务区域 |
getIDFA() | String | 获取 IDFA（未授权返回空串） |
getIDFV() | String | 获取 IDFV |
requestAttAuthorization(completion:) | Void | 请求 ATT 授权 |
requestLocation(completion:) | Void | 一次性定位请求 |
setIDFA(_:) | Void | 开发者主动注入 IDFA |
setUserInfo(_:) | Void | 注入用户信息 |
setLocation(_:) | Void | 注入位置信息 |
updateChannel(channel:subChannel:) | Void | 更新渠道与子渠道 |
registerAdapterFactory(_:) | Bool | 注册单个适配器工厂 |
destroy() | Void | 释放 SDK 资源 |
// 第一阶段：initialize（同步，不采集隐私）
UjuAdCore.shared.initialize(application, config: config)
// 第二阶段：start 并监听回调
UjuAdCore.shared.start(listener)
// 判断是否已完成 initialize
if UjuAdCore.shared.isSdkInitialized() { /* 可调用 start */ }
// 获取版本号
UjuAdCore.shared.getVersion() // "3.4.8"
// 释放资源
UjuAdCore.shared.destroy()两阶段初始化
initialize() 仅保存配置，不执行任何耗时操作；start() 才会真正采集设备信息、拉取策略并初始化适配器。必须先 initialize，再 start。
UjuAdObject
统一广告对象，final class，通过静态工厂方法创建（被 #if canImport(UIKit) 守卫，iOS-only），承载广告的加载、展示、销毁等生命周期。
工厂方法（静态）
| 方法签名 | 说明 |
|---|---|
getSplashObject(_ vc: UIViewController, config: UjuAdConfig) -> UjuAdObject | 创建开屏广告对象 |
getRewardObject(_ vc: UIViewController, config: UjuAdConfig) -> UjuAdObject | 创建激励视频广告对象 |
getInterstitialObject(_ vc: UIViewController, config: UjuAdConfig) -> UjuAdObject | 创建插屏广告对象 |
getBannerObject(_ vc: UIViewController, config: UjuAdConfig) -> UjuAdObject | 创建横幅广告对象 |
getNativeObject(_ vc: UIViewController, config: UjuAdConfig) -> UjuAdObject | 创建原生广告对象 |
实例方法
| 方法签名 | 返回值 | 说明 |
|---|---|---|
setAdObjectListener(_:) | Void | 设置广告监听器，类型需与广告类型匹配 |
load() | Void | 加载广告，触发竞价与请求流程 |
show(_ vc: UIViewController) | Void | 展示广告（无容器），适用于开屏/激励/插屏 |
show(_ vc: UIViewController, container: UIView) | Void | 展示广告（需容器），适用于横幅/原生 |
isReady() | Bool | 判断广告是否就绪可展示 |
destroy() | Void | 销毁广告对象，释放资源 |
getAdInfo() | UjuAdInfo? | 获取广告信息（价格、平台等），未加载返回 nil |
getFeedType() | FeedType? | 获取信息流渲染类型（原生固定返回 .native，横幅固定返回 .banner） |
getAdData() | NativeAdData? | 获取自渲染原生物料数据（仅原生自渲染有效） |
registerViewForInteraction(vc:adView:container:binder:) | Void | 注册自渲染视图，绑定点击交互与物料（仅原生自渲染） |
无 pause/resume 方法
UjuAdObject 没有 pause() 和 resume() 方法。如需暂停展示，请调用 destroy() 销毁后重新创建对象。
UjuAdInitConfig
SDK 初始化配置，struct（Sendable）。init 为 private，必须通过 create(...) 工厂方法构造。
create 参数
| 参数 | 类型 | 必填 | 默认值 | 说明 |
|---|---|---|---|---|
appId | String | 是 | — | 应用 ID |
appKey | String | 是 | — | RSA 公钥，原样传入 |
channel | String | 否 | "AppStore" | 渠道标识 |
subChannel | String | 否 | "" | 子渠道 |
isDebug | Bool | 否 | false | 调试模式 |
wxAppId | String? | 否 | nil | 微信 AppId |
privacyConfig | UjuPrivacyConfig | 否 | UjuPrivacyConfig() | 隐私授权配置 |
personalization | UjuPersonalizedConfig | 否 | UjuPersonalizedConfig() | 个性化推荐配置 |
presetStrategyFileName | String? | 否 | nil | 预置策略文件名 |
region | UjuAdRegion | 否 | .domestic | 服务区域 |
rsaPublicKey | String | 否 | "" | RSA 公钥（PEM），用于服务端通信加密 |
loggerBackend | UjuLoggerBackend | 否 | .nsLog | 日志后端类型（.nsLog / .osLog / .fileLog / .hybrid） |
debugBidRequest | Bool | 否 | false | 是否输出 BidRequest JSON 调试日志（仅 isDebug=true 时生效） |
crashReportingEnabled | Bool | 否 | true | 是否启用崩溃上报 |
let config = UjuAdInitConfig.create(
appId: "YOUR_APP_ID",
appKey: "YOUR_APP_KEY",
channel: "AppStore",
isDebug: true,
region: .domestic,
rsaPublicKey: "YOUR_RSA_PUBLIC_KEY"
)UjuAdConfig
广告请求配置，struct，每次创建广告对象时传入，直接 init 构造。
| 字段 | 类型 | 必填 | 默认值 | 说明 |
|---|---|---|---|---|
placementId | String | 是 | — | 广告位 ID |
scenarioKey | String? | 否 | nil | 场景标识，用于统计 |
adViewSize | AdViewSize? | 否 | nil | 横幅 / 原生期望尺寸（逻辑点）。3.4.6 起作为竞价 slot 尺寸与预算源模版加载尺寸（宽度不超过宿主窗口当前宽度）；nil 时按宿主窗口当前宽度推导 |
userId | String? | 否 | nil | 用户 ID，激励视频常用 |
customData | [String: String]? | 否 | nil | 自定义数据 |
bidFloor | Double | 否 | 0.0 | 底价（元，CPM），由聚合平台（如 ToBid）传入，普通集成方无需设置 |
UjuPrivacyConfig
隐私授权配置，struct（Sendable）。所有字段默认 false（最严格隐私合规），业务方需显式开启。
| 字段 | 类型 | 默认值 | 说明 |
|---|---|---|---|
canUseIDFA | Bool | false | 是否允许使用 IDFA（需 ATT 授权） |
canUseIDFV | Bool | false | 是否允许使用 IDFV |
canUseLocation | Bool | false | 是否允许使用地理位置 |
canUseImei | Bool | false | 是否允许使用 IMEI（iOS 通常不允许，字段保留兼容） |
canUseOaid | Bool | false | 是否允许使用 OAID（iOS 无对应，字段保留兼容） |
canUseMac | Bool | false | 是否允许使用 MAC 地址（iOS 通常不允许，字段保留兼容） |
UjuPersonalizedConfig
个性化推荐配置，struct（Sendable）。所有字段默认 false（最严格合规），业务方需显式开启。
| 字段 | 类型 | 默认值 | 说明 |
|---|---|---|---|
personalizedRecommend | Bool | false | 是否允许个性化推荐 |
programmaticRecommended | Bool | false | 是否允许程序化推荐 |
UjuAdInfo
广告信息模型，struct。通过 UjuAdObject.getAdInfo() 获取。
| 字段 | 类型 | 说明 |
|---|---|---|
ecpm | Double | 广告价格（eCPM） |
placementId | String | 广告位 ID |
soltId | String | 广告位槽位 ID（注意：源码拼写为 soltId） |
platformId | Int | 平台 ID，对应 AdPlatformType 的数值 |
adFormat | AdFormat | 广告格式 |
originalDoubleData | Double? | 原始 eCPM（未转换） |
loadId | String | 加载实例 ID |
字段拼写注意
UjuAdInfo 中的槽位 ID 字段拼写为 soltId（非 slotId），这是源码中的实际拼写，使用时请保持一致。
NativeAdData
原生广告自渲染物料数据，struct。通过 UjuAdObject.getAdData() 获取，所有字段均为可选。
| 字段 | 类型 | 说明 |
|---|---|---|
title | String? | 广告标题 |
desc | String? | 广告描述 |
source | String? | 广告来源 |
callToAction | String? | 行动号召文案（如「立即下载」） |
imageUrl | String? | 单图 URL |
imageUrlList | [String]? | 多图 URL 列表 |
iconUrl | String? | 图标 URL |
NativeAdViewBinder
原生广告视图绑定器，struct，采用 view.tag 模式。仅 titleTag 必填，其余默认 0/[] 表示不绑定。
| 字段 | 类型 | 必填 | 默认值 | 说明 |
|---|---|---|---|---|
titleTag | Int | 是 | — | 标题视图 tag |
descTag | Int | 否 | 0 | 描述视图 tag |
sourceTag | Int | 否 | 0 | 来源视图 tag |
imageTag | Int | 否 | 0 | 主图视图 tag |
mediaViewTag | Int | 否 | 0 | 媒体视图 tag（视频广告） |
iconTag | Int | 否 | 0 | 图标视图 tag |
callToActionTag | Int | 否 | 0 | 行动号召按钮 tag |
logoTag | Int | 否 | 0 | 广告标识 tag |
clickViewTags | [Int] | 否 | [] | 额外可点击视图 tag 列表 |
dislikeTag | Int | 否 | 0 | 不感兴趣按钮 tag |
AdViewSize
广告尺寸配置，struct（Sendable），单位为逻辑点（pt，与 UIView 尺寸同单位），仅对横幅与原生模板广告生效。3.4.6 起设置后 SDK 以此作为竞价 slot 尺寸与各预算源模版加载尺寸（宽度不超过宿主窗口当前宽度）；未设置时按宿主窗口当前宽度推导，折叠屏折叠 / 展开后随窗口变化。
| 字段 | 类型 | 说明 |
|---|---|---|
width | CGFloat | 宽度（逻辑点） |
height | CGFloat | 高度（逻辑点） |
预设尺寸（静态属性）
| 预设属性 | 宽 × 高 | 描述 |
|---|---|---|
AdViewSize.bannerSize320x50 | 320 × 50 | 标准 Banner |
AdViewSize.bannerSize320x100 | 320 × 100 | 大号 Banner |
AdViewSize.bannerSize320x75 | 320 × 75 | 智能 Banner |
AdViewSize.nativeSize600x200 | 600 × 200 | Native 自渲染 |
AdViewSize.nativeSize690x388 | 690 × 388 | Native 信息流卡片 |
// 使用预设
let size = AdViewSize.bannerSize320x50
// 自定义尺寸
let custom = AdViewSize(width: 300, height: 250)Listener 接口
SDK 提供一组监听器协议，按广告类型区分。所有广告监听器均继承自 BaseAdObjectListener，方法均有默认空实现，调用方可只实现关心的回调。
继承关系
BaseAdObjectListener
├── FeedAdObjectListener （横幅 / 原生信息流）
├── SplashAdObjectListener （开屏）
├── InterstitialAdObjectListener （插屏）
└── RewardAdObjectListener （激励视频）
BaseInitListener （SDK 初始化，独立接口）BaseAdObjectListener
所有广告对象监听器的基类协议（AnyObject）。
| 方法签名 | 说明 |
|---|---|
onLoadSuccess() | 广告加载成功（无参数） |
onLoadError(error: UjuException) | 广告加载失败（1 个参数） |
onAdShow() | 广告展示 |
onAdClicked() | 广告被点击 |
onAdClosed() | 广告关闭 |
onAdError(error: UjuException) | 广告展示阶段错误（1 个参数） |
参数数量
iOS 的 onLoadSuccess() 无参数，onLoadError(error:) 与 onAdError(error:) 均为 1 个参数（error）。与 Android 不同（Android onLoadSuccess 有 placementId 参数，onLoadError 有 2 个参数）。
FeedAdObjectListener
横幅与原生信息流监听器，继承 BaseAdObjectListener。
| 方法签名 | 说明 |
|---|---|
onAdSizeChanged(width: CGFloat, height: CGFloat) | 广告视图尺寸变化（3.4.6 新增，主线程）。容器宽度变化（折叠屏折叠 / 展开、分屏、旋转）后广告按新宽度重排、高度随之改变时回调；初次渲染不回调。列表类宿主可据此刷新行高 |
onLpClosed() | 落地页关闭 |
SplashAdObjectListener
开屏广告监听器，继承 BaseAdObjectListener。
| 方法签名 | 说明 |
|---|---|
onAdDismissed() | 开屏被关闭（用户跳过或倒计时结束） |
InterstitialAdObjectListener
插屏广告监听器，继承 BaseAdObjectListener。
| 方法签名 | 说明 |
|---|---|
onAdPlayComplete() | 插屏播放完成 |
RewardAdObjectListener
激励视频监听器，继承 BaseAdObjectListener。
| 方法签名 | 说明 |
|---|---|
onAdRewardArrived() | 发放奖励（无参数） |
onAdPlayComplete() | 视频播放完成 |
onAdSkippedVideo() | 用户跳过视频 |
onAdRewardArrived 无参数
onAdRewardArrived() 没有任何参数。如需自定义奖励信息，请在服务端通过 S2S 回调验证。
BaseInitListener
SDK 初始化监听器，独立接口（AnyObject, Sendable），回调在 MainActor（主线程）。
| 方法签名 | 说明 |
|---|---|
onInitSuccess() | SDK 初始化成功 |
onInitFailed(error: UjuException) | SDK 初始化失败 |