优聚智汇

简体中文

English

简体中文

English

外观

iOS SDK 初始化 ​

初始化时机 ​

必须在 AppDelegate 的 didFinishLaunchingWithOptions 方法中初始化优聚智汇广告 SDK，确保在应用启动时就完成初始化，为后续的广告加载做好准备。

iOS SDK 采用 两阶段初始化 机制以满足隐私合规：

  1. 阶段 1（initialize）：同步保存配置，不进行网络/设备操作，不采集任何隐私信息。
  2. 阶段 2（start）：异步执行初始化，采集设备信息并拉取策略，完成后回调 listener。

基本初始化 ​

1. 在 AppDelegate 中完成两阶段初始化 ​

swift
import UIKit
import UjuAdCore

@main
final class AppDelegate: UIResponder, UIApplicationDelegate {

    private let initListener = AppInitListener()

    func application(
        _ application: UIApplication,
        didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?
    ) -> Bool {
        // 阶段 1：构造配置 + initialize（同步，无网络/设备操作，可安全在主线程调用）
        let config = UjuAdInitConfig.create(
            appId: "YOUR_APP_ID",                       // 必填，优聚智汇平台分配
            appKey: "YOUR_APP_KEY",                     // 必填，RSA 公钥（后台分配，原样传入）
            channel: "AppStore",                        // 渠道，默认 AppStore
            isDebug: true,                              // 调试模式，发布前改为 false
            region: .domestic,                          // 服务区域：.domestic（国内）/ .singapore（海外）
            rsaPublicKey: "YOUR_RSA_PUBLIC_KEY"         // 用于服务端通信加密（可空，空时不加密）
        )
        UjuAdCore.shared.initialize(application, config: config)

        // 阶段 2：异步启动 SDK（内部按多步骤执行，完成后回调 listener）
        UjuAdCore.shared.start(initListener)

        return true
    }
}

// MARK: - InitListener

final class AppInitListener: BaseInitListener, @unchecked Sendable {
    func onInitSuccess() {
        // SDK 启动成功，可以开始加载广告
        print("SDK 初始化成功(version=\(UjuAdCore.shared.getVersion()))")
    }

    func onInitFailed(error: UjuException) {
        // SDK 初始化失败
        print("SDK 初始化失败: \(error.description)")
    }
}

回调线程

onInitSuccess / onInitFailed 在 MainActor（主线程） 回调，可安全更新 UI。

2. 配置参数说明（UjuAdInitConfig.create） ​

UjuAdInitConfig 的 init 为 private，必须通过 create(...) 工厂方法构造。

参数类型必填默认值说明
appIdString是—应用 ID，从优聚智汇后台获取
appKeyString是—RSA 公钥，从后台获取，原样传入，勿自行修改
channelString否"AppStore"渠道标识，用于数据统计与分账
subChannelString否""子渠道
isDebugBool否false调试模式，开发阶段建议开启（输出 SDK 内部 NSLog）
wxAppIdString?否nil微信 AppId，用于 Deeplink 归因
privacyConfigUjuPrivacyConfig否UjuPrivacyConfig()隐私授权配置
personalizationUjuPersonalizedConfig否UjuPersonalizedConfig()个性化推荐配置
presetStrategyFileNameString?否nil预置策略文件名，如 "placement_config.json"
regionUjuAdRegion否.domestic服务区域，SDK 内部据此推导各服务 host
rsaPublicKeyString否""RSA 公钥（PEM），用于服务端通信加密，空时不加密
loggerBackendUjuLoggerBackend否.nsLog日志后端类型（.nsLog / .osLog / .fileLog / .hybrid）
debugBidRequestBool否false是否输出 BidRequest JSON 调试日志（仅 isDebug=true 时生效）
crashReportingEnabledBool否true是否启用崩溃上报

region 说明

集成方只需选择 region（.domestic 国内 / .singapore 海外），各服务地址由 SDK 内部根据 region 自动推导，不暴露给集成方。请勿尝试自行配置服务器地址。

3. UjuAdRegion 枚举 ​

枚举值说明
.domestic国内
.singapore海外
swift
let region = UjuAdCore.shared.getRegion()  // .domestic / .singapore

隐私配置 UjuPrivacyConfig ​

描述业务方允许 SDK 采集的隐私数据范围。所有字段默认为 false（最严格隐私合规），业务方需显式开启授权。

字段类型默认值说明
canUseIDFABoolfalse是否允许使用 IDFA（需 ATT 授权）
canUseIDFVBoolfalse是否允许使用 IDFV
canUseLocationBoolfalse是否允许使用地理位置
canUseImeiBoolfalse是否允许使用 IMEI（iOS 通常不允许，字段保留兼容）
canUseOaidBoolfalse是否允许使用 OAID（iOS 无对应，字段保留兼容）
canUseMacBoolfalse是否允许使用 MAC 地址（iOS 通常不允许，字段保留兼容）
swift
let privacyConfig = UjuPrivacyConfig(
    canUseIDFA: true,       // 需 ATT 授权
    canUseIDFV: true,
    canUseLocation: true
)
let config = UjuAdInitConfig.create(
    appId: "YOUR_APP_ID",
    appKey: "YOUR_APP_KEY",
    privacyConfig: privacyConfig
)

隐私合规

建议在获得用户明确同意后再开启 canUseIDFA / canUseLocation 等授权字段。未开启时 SDK 仍可工作，但归因精度可能下降。

个性化配置 UjuPersonalizedConfig ​

符合《个人信息保护法》合规要求。所有字段默认为 false（最严格合规），业务方需显式开启。

字段类型默认值说明
personalizedRecommendBoolfalse是否允许个性化推荐
programmaticRecommendedBoolfalse是否允许程序化推荐
swift
let personalization = UjuPersonalizedConfig(
    personalizedRecommend: true,
    programmaticRecommended: true
)
let config = UjuAdInitConfig.create(
    appId: "YOUR_APP_ID",
    appKey: "YOUR_APP_KEY",
    personalization: personalization
)

更新渠道信息 ​

SDK 初始化完成后，可通过 updateChannel 动态更新渠道和子渠道：

swift
UjuAdCore.shared.updateChannel(channel: "新渠道", subChannel: "新子渠道")

初始化状态检查 ​

swift
// 是否已完成 initialize（第一阶段）
if UjuAdCore.shared.isSdkInitialized() {
    // 已完成 init，可调用 start
}

// 获取初始化状态枚举
let state = UjuAdCore.shared.getInitializeState()
switch state {
case .idle: print("未初始化")
case .initializing: print("初始化中")
case .initialized: print("已初始化")
case .failed: print("初始化失败")
}

UjuAdInitStatus 枚举 ​

枚举值说明
.idle空闲状态，尚未调用 start()
.initializing初始化中，正在采集设备信息并拉取策略
.initialized已初始化，可以正常加载广告
.failed初始化失败

SDK 其他公共方法 ​

除 initialize / start / updateChannel 外，UjuAdCore 还提供以下公共方法：

方法返回值说明
isSdkInitialized()Bool是否已完成 initialize（第一阶段）
getInitializeState()UjuAdInitStatus获取初始化状态枚举
getVersion()String获取 SDK 版本号（当前 3.4.2）
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注入位置信息
registerAdapterFactory(_:)Bool注册单个适配器工厂
destroy()Void释放 SDK 资源
getConnectionSnapshots()[ConnectionSnapshot]诊断：获取 gRPC 连接池快照（联调用，正常集成无需调用）
getConnectionCount()Int诊断：获取当前连接总数
getRecentConnectionEventLogs(limit:)[ConnectionEventLog]诊断：获取最近连接事件日志
swift
// 获取 SDK 版本号
print("SDK 版本: \(UjuAdCore.shared.getVersion())")  // 3.4.2

销毁 SDK（可选） ​

App 退出或需要重置 SDK 时调用：

swift
UjuAdCore.shared.destroy()

注意：destroy 后如需重新使用 SDK，需重新调用 initialize + start。

常见问题 ​

Q: 初始化失败怎么办？ ​

A: 可能的原因：

  • appId / appKey（RSA 公钥）是否正确
  • region 是否选对（.domestic 国内 / .singapore 海外）
  • 网络连接是否正常
  • 开启 isDebug = true，查看控制台日志中的具体失败原因

Q: 为什么不需要配置服务器地址？ ​

A: 集成方只需选择 region，各服务 host 由 SDK 内部根据 region 自动推导，不暴露给集成方。这是平台内部固定配置，不属于集成方应决定的范畴。

Q: IDFA 获取不到怎么办？ ​

A: iOS 14+ 需用户授权 ATT。请确认：

  • Info.plist 已配置 NSUserTrackingUsageDescription
  • UjuPrivacyConfig.canUseIDFA 已设为 true
  • 用户已授权 ATTrackingManager.AuthorizationStatus.authorized
  • 未授权时 SDK 仍可工作（使用 IDFV 替代），但归因精度下降

最佳实践 ​

  1. 尽早初始化：在 didFinishLaunchingWithOptions 中完成两阶段初始化
  2. 严格两阶段顺序：必须先 initialize，再 start
  3. 处理失败情况：实现 onInitFailed，确保应用在初始化失败时仍能正常运行
  4. 调试模式：开发阶段 isDebug = true，发布前改为 false
  5. 隐私合规：UjuPrivacyConfig 默认全 false，按需显式开启授权字段
  6. 资源释放：应用退出时调用 destroy()

下一步 ​

完成 SDK 初始化后，您可以开始集成具体的广告类型：

相关文档 ​