Android SDK 初始化
初始化时机
必须在 Application 类的 onCreate() 方法中初始化优聚智汇广告 SDK，确保在应用启动时就完成初始化，为后续的广告加载做好准备。
基本初始化
1. 创建 Application 类，添加初始化方法
如果您的应用还没有自定义 Application 类，需要先创建一个：
kotlin
class MyApplication : Application() {
override fun onCreate() {
super.onCreate()
initializeSdk()
}
private fun initializeSdk() {
// 创建配置对象
val config = UjuAdInitConfig(
appId = "YOUR_APP_ID", // 必填，应用ID
appKey = "YOUR_APP_KEY", // 必填，应用Key（RSA 公钥，后台分配，原样传入，勿自行修改）
channel = "测试渠道", // 必填，渠道标识，用于数据统计与分账
subChannel = "测试子渠道", // 可选，子渠道
isDebug = false, // 调试模式，建议开发时开启
wxAppId = "wx_xxxxx", // 微信AppId，用于微信广告渠道
// 预置策略
presetStrategyFileName = "placement_config.json",
// 隐私协议控制，开发者可传入AndroidId，传入后聚合SDK将使用开发者提供的ID，不主动获取
privacyConfig = UjuPrivacyConfig(
androidId = getAndroidId(this)
)
)
// 步骤1：初始化
UjuAdSdk.init(this, config)
// 步骤2：启动SDK并监听回调
UjuAdSdk.start(object : BaseInitListener {
override fun onInitSuccess() {
// SDK启动成功，此时可以开始加载广告
}
override fun onInitFailed(error: UjuException) {
// 初始化失败处理
Log.e("UjuAd", "SDK初始化失败: ${error.message}")
}
})
}
}2. 配置参数说明
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
appId | String | 是 | 应用ID，从优聚智汇后台获取 |
appKey | String | 是 | 应用Key（RSA 公钥），从优聚智汇后台获取，请原样传入，勿自行修改 |
channel | String | 是 | 渠道标识，用于数据统计与分账，无默认值（必填） |
subChannel | String | 否 | 子渠道标识，用于渠道下的细分，默认 "" |
isDebug | Boolean | 否 | 调试模式开关，建议开发阶段开启，默认 false |
wxAppId | String | 否 | 微信AppId，用于微信广告渠道 |
presetStrategyFileName | String | 否 | 预置策略文件名，如 "placement_config.json"，用于本地预置广告策略 |
privacyConfig | UjuPrivacyConfig | 否 | 隐私协议控制配置，开发者可传入 AndroidId，传入后聚合SDK将使用开发者提供的ID，不主动获取 |
personalization | UjuPersonalizedConfig | 否 | 个性化配置，需用户同意后传入，用于个性化广告策略 |
3. 个性化配置
UjuPersonalizedConfig 用于提供用户相关数据，辅助个性化广告策略。需在获得用户同意后方可传入，字段如下：
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
userId | String | 是 | 用户唯一标识符，用于个性化策略 |
userAge | Int | 是 | 用户年龄，如 25 |
userGender | Int | 否 | 用户性别：0 未知（默认）/ 1 男 / 2 女 |
userKeywords | List<String> | 否 | 用户标签关键词数组，如 ["game","sports"]，默认空列表 |
kotlin
// 示例：在用户同意后传入个性化配置
val personalization = UjuPersonalizedConfig(
userId = "user_123", // 用户唯一标识
userAge = 25, // 用户年龄
userGender = 1, // 1=男，2=女，0=未知
userKeywords = listOf("game", "sports") // 用户标签关键词
)
val config = UjuAdInitConfig(
appId = "YOUR_APP_ID",
appKey = "YOUR_APP_KEY", // RSA 公钥
channel = "YOUR_CHANNEL",
personalization = personalization // 传入个性化配置
)更新渠道信息
SDK 初始化完成后，您可以通过 updateChannel 方法动态更新渠道和子渠道信息：
kotlin
// 更新渠道信息
UjuAdSdk.updateChannel("新的渠道", "新的子渠道")初始化状态检查
您可以在任何时候检查 SDK 的初始化状态：
kotlin
// 检查 SDK 是否已完成 init（第一阶段）
if (UjuAdSdk.isSdkInitialized()) {
// SDK 已初始化，可以加载广告
}SDK 其他公共方法
除 init/start/updateChannel 外，UjuAdSdk 还提供以下公共方法：
| 方法 | 返回值 | 说明 |
|---|---|---|
isSdkInitialized() | Boolean | 判断 SDK 是否已完成 init（第一阶段） |
getVersion() | String | 获取 SDK 版本号 |
getOAID() | String | 获取设备 OAID |
getGoogleAdId() | String | 获取 Google 广告 ID |
getInitializeState() | UjuAdInitStatus | 获取初始化状态枚举（IDLE/INITIALIZING/INITIALIZED/INITIALIZATION_FAILED） |
getAppId() | String | 获取当前应用 ID |
destroy() | void | 释放 SDK 资源 |
kotlin
// 获取 SDK 版本号
val version = UjuAdSdk.getVersion()
Log.d("UjuAd", "SDK 版本: $version")
// 获取初始化状态枚举
val state = UjuAdSdk.getInitializeState()
when (state) {
UjuAdInitStatus.IDLE -> Log.d("UjuAd", "未初始化")
UjuAdInitStatus.INITIALIZING -> Log.d("UjuAd", "初始化中")
UjuAdInitStatus.INITIALIZED -> Log.d("UjuAd", "已初始化")
UjuAdInitStatus.INITIALIZATION_FAILED -> Log.d("UjuAd", "初始化失败")
}混淆配置（ProGuard）
如果您的应用开启了代码混淆，请在 proguard-rules.pro 文件中添加以下混淆规则，以确保 SDK 正常运行。
UJU AD-SDK 核心混淆规则（必选）
groovy
# UJU AD-SDK 混淆
-keep class com.ujusdk.**. *AdapterFactory {
public <init>();
*;
}
-keep class com.ujusdk.adsdk.public.base.BaseAdapterFactory { *; }OAID 相关混淆规则（必选）
groovy
# OAID相关混淆
-keep class repeackage.com.uodis.opendevice.aidl.** { *; }
-keep interface repeackage.com.uodis.opendevice.aidl.** { *; }
-keep class repeackage.com.asus.msa.SupplementaryDID.** { *; }
-keep interface repeackage.com.asus.msa.SupplementaryDID.** { *; }
-keep class repeackage.com.bun.lib.** { *; }
-keep interface repeackage.com.bun.lib.** { *; }
-keep class repeackage.com.heytap.openid.** { *; }
-keep interface repeackage.com.heytap.openid.** { *; }
-keep class repeackage.com.samsung.android.deviceidservice.** { *; }
-keep interface repeackage.com.samsung.android.deviceidservice.** { *; }
-keep class repeackage.com.zui.deviceidservice.** { *; }
-keep interface repeackage.com.zui.deviceidservice.** { *; }
-keep class repeackage.com.coolpad.deviceidsupport.** { *; }
-keep interface repeackage.com.coolpad.deviceidsupport.** { *; }
-keep class repeackage.com.android.creator.** { *; }
-keep interface repeackage.com.android.creator.** { *; }
-keep class repeackage.com.google.android.gms.ads.identifier.internal.** { *; }
-keep interface repeackage.com.google.android.gms.ads.identifier.internal.* { *; }
-keep class repeackage.com.oplus.stdid.** {*; }
-keep interface repeackage.com.oplus.stdid.** {*; }
-keep class com.huawei.hms.ads.** {*; }
-keep interface com.huawei.hms.ads.** {*; }
-keep class com.hihonor.ads.** {*; }
-keep interface com.hihonor.ads.** {*; }
-keep class repeackage.com.qiku.id.** { *; }
-keep interface repeackage.com.qiku.id.** { *; }Gromore 聚合混淆（可选 — 不接入 Gromore 可以不引入）
groovy
# Gromore聚合混淆，不接入gromore可以不引入
-keep class bykvm*.**
-keep class com.bytedance.msdk.adapter.**{ public *; }
-keep class com.bytedance.msdk.api.** {
public *;
}百度 SDK 混淆（可选 — 不接入百度 SDK 可以不引入）
groovy
# baidu sdk 不接入baidu sdk可以不引入
-ignorewarnings
-dontwarn com.baidu.mobads.sdk.api.**
-keepclassmembers class * extends android.app.Activity {
public void *(android.view.View);
}
-keepclassmembers enum * {
public static **[] values();
public static ** valueOf(java.lang.String);
}
-keep class com.baidu.mobads.** { *; }
-keep class com.style.widget.** {*;}
-keep class com.component.** {*;}
-keep class com.baidu.ad.magic.flute.** {*;}
-keep class com.baidu.mobstat.forbes.** {*;}快手 SDK 混淆（可选 — 不接入快手 SDK 可以不引入）
groovy
#ks 不接入ks sdk可以不引入
-keep class org.chromium.** {*;}
-keep class org.chromium.** { *; }
-keep class aegon.chrome.** { *; }
-keep class com.kwai.**{ *; }
-keep class com.yxcorp.kuaishou.addfp.android.Orange {*;}
-dontwarn com.kwai.**
-dontwarn com.kwad.**
-dontwarn com.ksad.**
-dontwarn aegon.chrome.**微信 SDK 混淆（可选 — 不接入微信小游戏调起可以不引入）
groovy
#如果接入微信小游戏调起，需按微信要求添加以下keep
-keep class com.tencent.mm.opensdk.** {
*;
}
-keep class com.tencent.wxop.** {
*;
}
-keep class com.tencent.mm.sdk.** {
*;
}常见问题
Q: 初始化失败怎么办？
A: 初始化失败可能的原因：
- 网络问题：检查网络连接是否正常
- App ID/Key 错误：确认 App ID 和 App Key 是否正确
- 设备限制：某些设备可能被限制访问
- 版本问题：检查 SDK 版本是否兼容
Q: 如何提高初始化成功率？
A: 建议：
- 在应用启动时尽早初始化
- 确保网络连接稳定
- 避免在初始化过程中进行耗时操作
- 正确处理初始化失败的情况
Q: privacyConfig 中的 AndroidId 应该如何处理？
A: 开发者应主动获取 AndroidId 并通过 UjuPrivacyConfig 传入 SDK。传入后，聚合SDK将使用开发者提供的ID，不再主动获取设备ID，这有助于满足隐私合规要求。
最佳实践
- 尽早初始化：在
Application.onCreate()中初始化，确保广告就绪 - 处理失败情况：添加失败回调，确保应用在初始化失败时仍能正常运行
- 测试模式：开发阶段使用测试设备和测试广告，
isDebug设为true - 监控初始化：在生产环境中监控初始化成功率
- 版本管理：及时更新 SDK 版本
- 隐私合规：通过
privacyConfig传入 AndroidId，遵循隐私协议要求 - 混淆配置：根据实际接入的广告渠道，按需添加对应的混淆规则
下一步
完成 SDK 初始化后，您可以开始集成具体的广告类型：
相关文档
- API 参考 — 完整 API 签名与字段说明