iOS API Reference
This document is the API reference manual for the UjuAd iOS SDK, covering all public enums and complete signatures of core classes. All content is verified against SDK source code for developers to reference during integration.
Reading Recommendations
- For first-time integration, read SDK Initialization and Preparation first.
- For specific usage of each ad type, refer to the Ad Type Integration documentation series.
- This document only lists API signatures and field meanings; it does not include complete integration examples.
Enum Reference
AdFormat
Ad format enum, describing the 5 ad types supported by the SDK.
| Enum Value | Numeric Value | Meaning |
|---|---|---|
.splash | 0 | Splash ad |
.banner | 1 | Banner ad |
.native | 2 | Native/feed ad |
.reward | 3 | Rewarded video |
.interstitial | 4 | Interstitial ad |
FeedType
Feed ad subtype enum, identifying the rendering mode. Obtained via UjuAdObject.getFeedType().
| Enum Value | Numeric Value | Meaning |
|---|---|---|
.express | 0 | Template rendering (SDK provides template, not enabled in current version) |
.banner | 1 | Banner template (banner ads always return this value) |
.native | 2 | Self-rendering (integrator provides view, native ads always return this value) |
let feedType = adObject.getFeedType()
switch feedType {
case .native:
// Self-rendering, call getAdData() to get creatives and bind views yourself
case .banner:
// Banner template
default:
break
}Current version rendering modes
In the current version, native ads getFeedType() always returns .native (self-rendering), and banner ads always return .banner. The .express template rendering mode will be supported in future versions.
AdMediaType
Media creative type for self-rendered ads.
| Enum Value | Numeric Value | Meaning |
|---|---|---|
.singleImage | 1 | Single image creative |
.multiImage | 2 | Multi-image creative (image group) |
.video | 3 | Video creative |
AdBidType
Ad bidding type, identifying the bidding mode of the ad placement.
| Enum Value | Numeric Value | Meaning |
|---|---|---|
.normal | 0 | Normal mode (no bidding, waterfall direct run) |
.adx | 1 | ADX mode (UjuAd self-owned ADX API) |
.c2s | 2 | Client-to-server bidding (C2S) |
.s2s | 3 | Server-to-server bidding (S2S) |
AdPlatformType
Ad platform identifier enum, used to identify the ADN platform of the ad source.
| Enum Value | Numeric Value | Platform Name | Description |
|---|---|---|---|
.csj | 1 | CSJ | ByteDance ChuanShanJia (Pangle) |
.ylh | 2 | YLH | Tencent YouLiangHui (GDT) |
.bd | 3 | Baidu | Baidu BaiQingTeng |
.ks | 4 | Kuaishou | Kuaishou Ads |
.vivo | 13 | VIVO | VIVO Ad Platform |
.oppo | 14 | OPPO | OPPO Ad Platform |
.adx | 100 | ADX | UjuAd internal ADX (platform ID is uniformly 100) |
ADX Self-owned Ad Sources
ADX self-owned ad sources are built into the core library and require no additional registration. The ADX ad platform ID obtained via UjuAdInfo.platformId is uniformly 100.
UjuAdInitStatus
SDK initialization state enum, obtainable via UjuAdCore.shared.getInitializeState().
| Enum Value | Numeric Value | Meaning |
|---|---|---|
.idle | 0 | Idle state (not started) |
.initializing | 1 | Initializing (start has been called, process is running) |
.initialized | 2 | Initialization complete (ad APIs can be called) |
.failed | 3 | Initialization failed (need to call start again) |
UjuAdRegion
Service region enum. Integrators only need to select the region; all service hosts are automatically derived by the SDK.
| Enum Value | Meaning |
|---|---|
.domestic | China |
.singapore | Overseas (Singapore) |
Public API Reference
UjuAdCore
SDK global entry point, final class singleton (UjuAdCore.shared), annotated @unchecked Sendable. Responsible for SDK initialization, startup, state queries, and resource release.
Method List
| Method Signature | Return Value | Description |
|---|---|---|
initialize(_ application: AnyObject?, config: UjuAdInitConfig) | Void | Phase 1 initialization, synchronously saves configuration, no privacy collection |
start(_ listener: BaseInitListener?) | Void | Phase 2 startup, collects device information and fetches strategies, calls back listener on completion |
isSdkInitialized() | Bool | Whether initialize (phase 1) has completed |
getInitializeState() | UjuAdInitStatus | Get SDK initialization state enum |
getVersion() | String | Get SDK version number (currently 3.4.8) |
getAppId() | String | Get current app ID |
getRegion() | UjuAdRegion | Get service region |
getIDFA() | String | Get IDFA (returns empty string if unauthorized) |
getIDFV() | String | Get IDFV |
requestAttAuthorization(completion:) | Void | Request ATT authorization |
requestLocation(completion:) | Void | One-time location request |
setIDFA(_:) | Void | Developer-injected IDFA |
setUserInfo(_:) | Void | Inject user information |
setLocation(_:) | Void | Inject location information |
updateChannel(channel:subChannel:) | Void | Update channel and sub-channel |
registerAdapterFactory(_:) | Bool | Register a single adapter factory |
destroy() | Void | Release SDK resources |
// 第一阶段：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()Two-Phase Initialization
initialize() only saves configuration and does not perform any time-consuming operations; start() is what actually collects device information, fetches strategies, and initializes adapters. You must call initialize first, then start.
UjuAdObject
Unified ad object, final class, created via static factory methods (guarded by #if canImport(UIKit), iOS-only), carrying the ad's load, show, destroy, and other lifecycle operations.
Factory Methods (Static)
| Method Signature | Description |
|---|---|
getSplashObject(_ vc: UIViewController, config: UjuAdConfig) -> UjuAdObject | Create splash ad object |
getRewardObject(_ vc: UIViewController, config: UjuAdConfig) -> UjuAdObject | Create rewarded video ad object |
getInterstitialObject(_ vc: UIViewController, config: UjuAdConfig) -> UjuAdObject | Create interstitial ad object |
getBannerObject(_ vc: UIViewController, config: UjuAdConfig) -> UjuAdObject | Create banner ad object |
getNativeObject(_ vc: UIViewController, config: UjuAdConfig) -> UjuAdObject | Create native ad object |
Instance Methods
| Method Signature | Return Value | Description |
|---|---|---|
setAdObjectListener(_:) | Void | Set ad listener; type must match the ad type |
load() | Void | Load ad, triggers bidding and request flow |
show(_ vc: UIViewController) | Void | Show ad (no container), for splash/reward/interstitial |
show(_ vc: UIViewController, container: UIView) | Void | Show ad (with container), for banner/native |
isReady() | Bool | Check whether the ad is ready to show |
destroy() | Void | Destroy ad object, release resources |
getAdInfo() | UjuAdInfo? | Get ad info (price, platform, etc.); returns nil if not loaded |
getFeedType() | FeedType? | Get feed rendering type (native always returns .native, banner always returns .banner) |
getAdData() | NativeAdData? | Get self-rendered native creative data (only valid for native self-rendering) |
registerViewForInteraction(vc:adView:container:binder:) | Void | Register self-rendered view, bind click interaction and creatives (native self-rendering only) |
No pause/resume Methods
UjuAdObject does not have pause() and resume() methods. If you need to pause display, call destroy() to destroy and then recreate the object.
UjuAdInitConfig
SDK initialization configuration, struct (Sendable). init is private; must be constructed via the create(...) factory method.
create Parameters
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
appId | String | Yes | — | App ID |
appKey | String | Yes | — | RSA public key, pass as-is |
channel | String | No | "AppStore" | Channel identifier |
subChannel | String | No | "" | Sub-channel |
isDebug | Bool | No | false | Debug mode |
wxAppId | String? | No | nil | WeChat AppId |
privacyConfig | UjuPrivacyConfig | No | UjuPrivacyConfig() | Privacy authorization configuration |
personalization | UjuPersonalizedConfig | No | UjuPersonalizedConfig() | Personalized recommendation configuration |
presetStrategyFileName | String? | No | nil | Preset strategy file name |
region | UjuAdRegion | No | .domestic | Service region |
rsaPublicKey | String | No | "" | RSA public key (PEM), used for server-side communication encryption |
loggerBackend | UjuLoggerBackend | No | .nsLog | Log backend type (.nsLog / .osLog / .fileLog / .hybrid) |
debugBidRequest | Bool | No | false | Whether to output BidRequest JSON debug logs (only effective when isDebug=true) |
crashReportingEnabled | Bool | No | true | Whether to enable crash reporting |
let config = UjuAdInitConfig.create(
appId: "YOUR_APP_ID",
appKey: "YOUR_APP_KEY",
channel: "AppStore",
isDebug: true,
region: .domestic,
rsaPublicKey: "YOUR_RSA_PUBLIC_KEY"
)UjuAdConfig
Ad request configuration, struct, passed in when creating each ad object, constructed directly via init.
| Field | Type | Required | Default | Description |
|---|---|---|---|---|
placementId | String | Yes | — | Ad placement ID |
scenarioKey | String? | No | nil | Scenario identifier, used for analytics |
adViewSize | AdViewSize? | No | nil | Preferred banner / native size (in points). Since 3.4.6 it is used as the bid slot size and the budget-source template load size (width capped at the host window's current width); when nil, the current window width is used |
userId | String? | No | nil | User ID, commonly used for rewarded video |
customData | [String: String]? | No | nil | Custom data |
bidFloor | Double | No | 0.0 | Bid floor (CNY, CPM), passed by aggregation platform (e.g. ToBid), not needed for normal integrators |
UjuPrivacyConfig
Privacy authorization configuration, struct (Sendable). All fields default to false (strictest privacy compliance). The integrator must explicitly enable them.
| Field | Type | Default | Description |
|---|---|---|---|
canUseIDFA | Bool | false | Whether IDFA usage is allowed (requires ATT authorization) |
canUseIDFV | Bool | false | Whether IDFV usage is allowed |
canUseLocation | Bool | false | Whether location usage is allowed |
canUseImei | Bool | false | Whether IMEI usage is allowed (iOS typically does not allow; field retained for compatibility) |
canUseOaid | Bool | false | Whether OAID usage is allowed (iOS has no equivalent; field retained for compatibility) |
canUseMac | Bool | false | Whether MAC address usage is allowed (iOS typically does not allow; field retained for compatibility) |
UjuPersonalizedConfig
Personalized recommendation configuration, struct (Sendable). All fields default to false (strictest compliance). The integrator must explicitly enable them.
| Field | Type | Default | Description |
|---|---|---|---|
personalizedRecommend | Bool | false | Whether personalized recommendations are allowed |
programmaticRecommended | Bool | false | Whether programmatic recommendations are allowed |
UjuAdInfo
Ad information model, struct. Obtained via UjuAdObject.getAdInfo().
| Field | Type | Description |
|---|---|---|
ecpm | Double | Ad price (eCPM) |
placementId | String | Ad placement ID |
soltId | String | Ad placement slot ID (note: source code spelling is soltId) |
platformId | Int | Platform ID, corresponds to the numeric value of AdPlatformType |
adFormat | AdFormat | Ad format |
originalDoubleData | Double? | Original eCPM (unconverted) |
loadId | String | Load instance ID |
Field Spelling Note
The slot ID field in UjuAdInfo is spelled soltId (not slotId). This is the actual spelling in the source code; please keep it consistent when using.
NativeAdData
Native ad self-rendering creative data, struct. Obtained via UjuAdObject.getAdData(). All fields are optional.
| Field | Type | Description |
|---|---|---|
title | String? | Ad title |
desc | String? | Ad description |
source | String? | Ad source |
callToAction | String? | Call-to-action text (e.g. "Download Now") |
imageUrl | String? | Single image URL |
imageUrlList | [String]? | Multi-image URL list |
iconUrl | String? | Icon URL |
NativeAdViewBinder
Native ad view binder, struct, using the view.tag pattern. Only titleTag is required; others default to 0/[] to indicate no binding.
| Field | Type | Required | Default | Description |
|---|---|---|---|---|
titleTag | Int | Yes | — | Title view tag |
descTag | Int | No | 0 | Description view tag |
sourceTag | Int | No | 0 | Source view tag |
imageTag | Int | No | 0 | Main image view tag |
mediaViewTag | Int | No | 0 | Media view tag (for video ads) |
iconTag | Int | No | 0 | Icon view tag |
callToActionTag | Int | No | 0 | Call-to-action button tag |
logoTag | Int | No | 0 | Ad logo tag |
clickViewTags | [Int] | No | [] | Additional clickable view tag list |
dislikeTag | Int | No | 0 | Dislike button tag |
AdViewSize
Ad size configuration, struct (Sendable), in points (pt, same unit as UIView sizes). Only effective for banner and native template ads. Since 3.4.6, when set, the SDK uses it as the bid slot size and every budget source's template load size (width capped at the host window's current width); when unset, the current window width is used and follows fold / unfold on foldable devices.
| Field | Type | Description |
|---|---|---|
width | CGFloat | Width (points) |
height | CGFloat | Height (points) |
Preset Sizes (Static Properties)
| Preset Property | Width × Height | Description |
|---|---|---|
AdViewSize.bannerSize320x50 | 320 × 50 | Standard Banner |
AdViewSize.bannerSize320x100 | 320 × 100 | Large Banner |
AdViewSize.bannerSize320x75 | 320 × 75 | Smart Banner |
AdViewSize.nativeSize600x200 | 600 × 200 | Native Self-rendering |
AdViewSize.nativeSize690x388 | 690 × 388 | Native Feed Card |
// 使用预设
let size = AdViewSize.bannerSize320x50
// 自定义尺寸
let custom = AdViewSize(width: 300, height: 250)Listener Interfaces
The SDK provides a set of listener protocols, differentiated by ad type. All ad listeners inherit from BaseAdObjectListener. All methods have default empty implementations, so callers can implement only the callbacks they care about.
Inheritance Hierarchy
BaseAdObjectListener
├── FeedAdObjectListener （横幅 / 原生信息流）
├── SplashAdObjectListener （开屏）
├── InterstitialAdObjectListener （插屏）
└── RewardAdObjectListener （激励视频）
BaseInitListener （SDK 初始化，独立接口）BaseAdObjectListener
Base protocol for all ad object listeners (AnyObject).
| Method Signature | Description |
|---|---|
onLoadSuccess() | Ad loaded successfully (no parameters) |
onLoadError(error: UjuException) | Ad load failed (1 parameter) |
onAdShow() | Ad displayed |
onAdClicked() | Ad clicked |
onAdClosed() | Ad closed |
onAdError(error: UjuException) | Ad show phase error (1 parameter) |
Parameter Count
iOS's onLoadSuccess() has no parameters. Both onLoadError(error:) and onAdError(error:) take 1 parameter (error). This differs from Android (Android's onLoadSuccess has a placementId parameter, and onLoadError has 2 parameters).
FeedAdObjectListener
Banner and native feed listener, inherits BaseAdObjectListener.
| Method Signature | Description |
|---|---|
onAdSizeChanged(width: CGFloat, height: CGFloat) | Ad view size changed (new in 3.4.6, main thread). Called when the container width changes (foldable fold / unfold, Split View, rotation) and the ad re-lays out to a new height; not called for the initial render. List-based hosts can refresh row heights here |
onLpClosed() | Landing page closed |
SplashAdObjectListener
Splash ad listener, inherits BaseAdObjectListener.
| Method Signature | Description |
|---|---|
onAdDismissed() | Splash dismissed (user skipped or countdown ended) |
InterstitialAdObjectListener
Interstitial ad listener, inherits BaseAdObjectListener.
| Method Signature | Description |
|---|---|
onAdPlayComplete() | Interstitial playback completed |
RewardAdObjectListener
Rewarded video listener, inherits BaseAdObjectListener.
| Method Signature | Description |
|---|---|
onAdRewardArrived() | Grant reward (no parameters) |
onAdPlayComplete() | Video playback completed |
onAdSkippedVideo() | User skipped video |
onAdRewardArrived Has No Parameters
onAdRewardArrived() has no parameters. If you need to customize reward information, verify it via S2S callback on the server side.
BaseInitListener
SDK initialization listener, standalone interface (AnyObject, Sendable), callbacks on MainActor (main thread).
| Method Signature | Description |
|---|---|
onInitSuccess() | SDK initialization succeeded |
onInitFailed(error: UjuException) | SDK initialization failed |
Related Links
- SDK Initialization — Initialization configuration and two-phase startup flow
- Preparation — Environment requirements and dependency setup
- Banner Ad — Banner ad integration
- Splash Ad — Splash ad integration
- Native Ad — Native feed ad integration
- Interstitial Ad — Interstitial ad integration
- Rewarded Video — Rewarded video ad integration
- Error Codes — SDK error code descriptions