Android API 参考

本文档是优聚智汇 Android SDK 的 API 参考手册，涵盖全部公共枚举与核心类的完整签名。所有内容均基于 SDK 源码验证，供开发者在集成过程中查阅。

阅读建议

首次接入请先阅读 SDK 初始化与准备工作。
各广告类型的具体用法请参考广告类型集成系列文档。
本文仅列出 API 签名与字段含义，不包含完整集成示例。

枚举参考

FeedType

信息流广告渲染类型，用于区分横幅、模板信息流与自渲染信息流。

枚举值	含义
`BANNER`	横幅广告，由 SDK 内部渲染并绑定到容器
`EXPRESS`	模板信息流，使用平台提供的模板渲染
`UNIFIED`	自渲染信息流，由开发者自行绘制广告视图

kotlin

// 获取当前广告对象的渲染类型
val feedType = adObject.getFeedType()
when (feedType) {
    FeedType.BANNER -> {
        // 横幅广告，调用 show(activity, viewGroup) 展示
    }
    FeedType.EXPRESS -> {
        // 模板渲染，调用 show(activity, viewGroup) 展示
    }
    FeedType.UNIFIED -> {
        // 自渲染，需调用 getAdData() 获取物料并自行绑定视图
    }
    else -> {
        // 未知类型，做空指针保护处理
    }
}

AdMediaType

自渲染广告的媒体素材类型，用于判断物料是单图、多图还是视频。

枚举值	数值	含义
`SINGLE_IMAGE`	1	单图素材
`MULTI_IMAGE`	2	多图素材（组图）
`VIDEO`	3	视频素材

kotlin

// 根据媒体类型选择不同的渲染布局
val data = adObject.getAdData()
data?.let { adData ->
    when (adData.mediaType) {
        AdMediaType.SINGLE_IMAGE -> {
            // 单图布局，使用 imageUrl 加载图片
        }
        AdMediaType.MULTI_IMAGE -> {
            // 多图布局，使用 imageUrlList 加载组图
        }
        AdMediaType.VIDEO -> {
            // 视频布局，需要 mediaViewId 承载视频播放
        }
    }
}

AdBidType

广告竞价类型，标识广告位的竞价模式。

枚举值	数值	含义
`NORMAL`	1	瀑布流模式，按优先级顺序请求
`ADX`	2	SDK 内部竞价模式
`C2S`	3	客户端竞价（Client-to-Server）
`S2S`	4	服务端竞价（Server-to-Server）

AdPlatformType

广告平台标识枚举，用于标识广告来源的 ADN 平台。

枚举值	数值	平台名称	说明
`CSJ`	1	穿山甲	字节跳动穿山甲（Pangle）
`YLH`	2	优量汇	腾讯优量汇（GDT）
`BD`	3	百度	百度百青藤
`KS`	4	快手	快手广告
`VIVO`	13	VIVO	VIVO 广告平台
`OPPO`	14	OPPO	OPPO 广告平台

ADX 自有广告源

SDK 内置 ADX 自有广告源（引入 uju-ad-adx 后自动启用），其内部 DSP 平台标识为 SDK 内部实现细节，开发者无需关注。通过 UjuAdInfo.platformId 获取到的 ADX 广告平台 ID 统一为 100。

kotlin

// 通过 platformId 判断广告来源平台
val adInfo = adObject.getAdInfo()
adInfo?.let { info ->
    val platform = AdPlatformType.fromValue(info.platformId)
    // platform 即为广告来源平台枚举
}

UjuAdInitStatus

SDK 初始化状态枚举，可通过 UjuAdSdk.getInitializeState() 获取。

枚举值	含义
`IDLE`	空闲状态，尚未调用 `start()`
`INITIALIZING`	初始化中，正在采集设备信息并拉取策略
`INITIALIZED`	已初始化，可以正常加载广告
`INITIALIZATION_FAILED`	初始化失败

kotlin

// 检查 SDK 初始化状态
when (UjuAdSdk.getInitializeState()) {
    UjuAdInitStatus.IDLE -> {
        // 尚未启动，需调用 UjuAdSdk.start()
    }
    UjuAdInitStatus.INITIALIZING -> {
        // 正在初始化中，请等待
    }
    UjuAdInitStatus.INITIALIZED -> {
        // 已初始化完成，可以加载广告
    }
    UjuAdInitStatus.INITIALIZATION_FAILED -> {
        // 初始化失败，需排查原因后重试
    }
}

CurrencyType

货币类型枚举，标识广告平台结算货币。

枚举值	含义
`CNY`	人民币
`USD`	美元

EcpmType

eCPM 单位类型枚举，标识广告平台返回的价格单位。

枚举值	含义
`YUAN`	元
`CENT`	分

换算说明

部分平台（如优量汇）返回的 eCPM 单位为「分」，SDK 内部会根据 EcpmType 自动换算为「元」统一对外输出。

公共 API 参考

UjuAdSdk

SDK 全局入口，object 单例。负责 SDK 初始化、启动、状态查询与资源释放。

方法列表

方法签名	返回值	说明
`init(context: Context, config: UjuAdInitConfig)`	`Unit`	第一阶段初始化，轻量操作，不采集隐私信息。传入 Application 上下文与初始化配置
`start(listener: BaseInitListener)`	`Unit`	第二阶段启动，采集设备信息并拉取策略，完成后回调 `listener`
`isSdkInitialized()`	`Boolean`	判断是否已完成 `init`（仅判断 init，不判断 start 是否成功）
`getVersion()`	`String`	获取当前 SDK 版本号
`getOAID()`	`String`	获取 OAID（未获取到时返回空字符串）
`getGoogleAdId()`	`String`	获取 Google Advertising ID（未获取到时返回空字符串）
`getInitializeState()`	`UjuAdInitStatus`	获取 SDK 初始化状态枚举
`getAppId()`	`String`	获取当前应用 ID
`updateChannel(channel: String, subChannel: String)`	`Unit`	更新渠道与子渠道信息，用于数据统计与分账
`destroy()`	`Unit`	释放 SDK 资源，按初始化逆序释放

kotlin

// 第一阶段：初始化（轻量，不采集隐私）
UjuAdSdk.init(application, config)

// 第二阶段：启动 SDK 并监听回调
UjuAdSdk.start(object : BaseInitListener {
    override fun onInitSuccess() {
        // 初始化成功，可以开始加载广告
    }

    override fun onInitFailed(error: UjuException) {
        // 初始化失败，记录错误信息
        Log.e("UjuAd", "初始化失败: ${error.message}")
    }
})

// 判断是否已完成 init
if (UjuAdSdk.isSdkInitialized()) {
    // 已完成 init，可调用 start
}

// 获取 SDK 版本号
val version = UjuAdSdk.getVersion()

// 更新渠道信息
UjuAdSdk.updateChannel("新渠道", "新子渠道")

// 释放资源（通常在应用退出时调用）
UjuAdSdk.destroy()

两阶段初始化

init() 仅保存配置，不执行任何耗时操作；start() 才会真正采集设备信息、拉取策略并初始化适配器。必须先调用 init()，再调用 start()。

UjuAdObject

统一广告对象，通过静态工厂方法创建，承载广告的加载、展示、销毁等生命周期。

工厂方法（静态）

方法签名	说明
`getBannerObject(activity: Activity, adConfig: UjuAdConfig): UjuAdObject`	创建横幅广告对象
`getSplashObject(activity: Activity, adConfig: UjuAdConfig): UjuAdObject`	创建开屏广告对象
`getNativeObject(activity: Activity, adConfig: UjuAdConfig): UjuAdObject`	创建原生/信息流广告对象
`getInterstitialObject(activity: Activity, adConfig: UjuAdConfig): UjuAdObject`	创建插屏广告对象
`getRewardObject(activity: Activity, adConfig: UjuAdConfig): UjuAdObject`	创建激励视频广告对象

实例方法

方法签名	返回值	说明
`setAdObjectListener(listener)`	`Unit`	设置广告监听器，listener 类型需与广告类型匹配
`load()`	`Unit`	加载广告，触发竞价与请求流程
`show(activity: Activity)`	`Unit`	展示广告（无容器），适用于激励视频、插屏
`show(activity: Activity, viewGroup: ViewGroup)`	`Unit`	展示广告（需容器），适用于开屏、横幅、原生模板
`isReady()`	`Boolean`	判断广告是否就绪可展示
`destroy()`	`Unit`	销毁广告对象，释放资源
`getAdInfo()`	`UjuAdInfo?`	获取广告信息（价格、平台等），未加载时返回 `null`
`getFeedType()`	`FeedType?`	获取信息流渲染类型（仅原生/横幅有效）
`getAdData()`	`NativeAdData?`	获取自渲染原生广告物料数据（仅自渲染有效）
`registerViewForInteraction(activity, adView, viewGroup, binder)`	`Unit`	注册自渲染广告视图，绑定点击交互与物料

无 pause/resume 方法

UjuAdObject 没有 pause() 和 resume() 方法。如需暂停展示，请调用 destroy() 销毁后重新创建对象。

kotlin

// 创建激励视频广告对象
val rewardAd = UjuAdObject.getRewardObject(activity, adConfig)

// 设置监听器
rewardAd.setAdObjectListener(object : RewardAdObjectListener {
    override fun onLoadSuccess(placementId: String) {
        // 广告加载成功
    }

    override fun onLoadError(error: UjuException, placementId: String) {
        // 广告加载失败
    }

    override fun onAdShow() {
        // 广告展示
    }

    override fun onAdError(error: UjuException) {
        // 广告展示出错（注意：仅 1 个参数）
    }

    override fun onAdPlayComplete() {
        // 视频播放完成
    }

    override fun onAdClicked() {
        // 广告被点击
    }

    override fun onAdSkippedVideo() {
        // 用户跳过视频
    }

    override fun onAdRewardArrived() {
        // 发放奖励（注意：无参数，无 RewardItem）
    }

    override fun onAdClosed() {
        // 广告关闭
    }
})

// 加载广告
rewardAd.load()

// 展示前检查是否就绪
if (rewardAd.isReady()) {
    rewardAd.show(activity)
}

UjuAdInitConfig

SDK 初始化配置，data class。

构造参数

参数	类型	必填	默认值	说明
`appId`	`String`	是	—	应用 ID，从优聚智汇后台获取
`appKey`	`String`	是	—	RSA 公钥，从后台获取，原样传入
`channel`	`String`	是	—	渠道标识，用于数据统计与分账（无默认值）
`subChannel`	`String`	否	`""`	子渠道
`isDebug`	`Boolean`	否	`false`	调试模式，开发阶段建议开启
`wxAppId`	`String`	否	`""`	微信 AppId，用于微信广告渠道
`presetStrategyFileName`	`String?`	否	—	预置策略文件名，如 `"placement_config.json"`
`privacyConfig`	`UjuPrivacyConfig?`	否	—	隐私配置
`personalization`	`UjuPersonalizedConfig?`	否	—	个性化配置

kotlin

// 创建初始化配置
val config = UjuAdInitConfig(
    appId = "YOUR_APP_ID",                       // 必填，应用 ID
    appKey = "YOUR_APP_KEY",                     // 必填，RSA 公钥
    channel = "main_channel",                    // 必填，渠道标识
    subChannel = "sub_channel",                  // 可选，子渠道
    isDebug = BuildConfig.DEBUG,                 // 可选，调试模式
    wxAppId = "wx_xxxxx",                        // 可选，微信 AppId
    presetStrategyFileName = "strategy.json",    // 可选，预置策略文件
    privacyConfig = UjuPrivacyConfig(            // 可选，隐私配置
        androidId = getAndroidId(context)
    ),
    personalization = UjuPersonalizedConfig(     // 可选，个性化配置
        userId = "user_001",
        userAge = 25
    )
)

UjuAdConfig

广告请求配置，data class。每次创建广告对象时传入。

字段

字段	类型	必填	默认值	说明
`placementId`	`String`	是	—	广告位 ID
`scenarioKey`	`String?`	否	—	场景标识，用于数据统计
`adViewSize`	`AdViewSize`	否	`AdViewSize()`	广告尺寸，仅模板渲染（横幅/原生）必填
`adFormat`	`Int?`	否	—	广告格式
`userId`	`String?`	否	—	用户 ID，激励视频常用
`customData`	`Map<String, String>?`	否	—	自定义数据

kotlin

// 创建广告配置
val adConfig = UjuAdConfig(
    placementId = "YOUR_PLACEMENT_ID",           // 必填，广告位 ID
    scenarioKey = "reward_scene",                // 可选，场景标识
    userId = "user_001",                         // 可选，用户 ID（激励视频常用）
    customData = mapOf("key" to "value")         // 可选，自定义数据
)

UjuPrivacyConfig

隐私配置，data class。开发者可主动传入设备标识，传入后 SDK 将使用开发者提供的标识，不主动获取。同时可控制 SDK 是否采集特定类型的信息。

字段

字段	类型	必填	默认值	说明
`useLocation`	`Boolean`	否	`true`	是否允许 SDK 使用地理位置信息
`useAppList`	`Boolean`	否	`true`	是否允许 SDK 读取应用列表
`usePhoneState`	`Boolean`	否	`true`	是否允许 SDK 读取手机状态
`useWifiState`	`Boolean`	否	`true`	是否允许 SDK 读取 WiFi 状态
`imei`	`String?`	否	`null`	IMEI，开发者主动传入
`macAddress`	`String?`	否	`null`	MAC 地址，开发者主动传入
`oaid`	`String?`	否	`null`	OAID，开发者主动传入
`androidId`	`String?`	否	`null`	AndroidId，开发者主动传入

kotlin

// 创建隐私配置
val privacyConfig = UjuPrivacyConfig(
    androidId = getAndroidId(context),           // 传入 AndroidId
    oaid = UjuAdSdk.getOAID(),                   // 传入 OAID
    useLocation = true,                          // 允许使用地理位置
    useAppList = false                           // 禁止读取应用列表（按需配置）
)

隐私合规

通过 UjuPrivacyConfig 主动传入设备标识（如 AndroidId、OAID），有助于满足隐私合规要求。开发者应在获得用户同意后再传入相关标识。同时可通过 useLocation/useAppList/usePhoneState/useWifiState 控制 SDK 的信息采集范围。

UjuPersonalizedConfig

个性化配置，data class。用于提供用户相关数据，支持个性化广告策略。

字段

字段	类型	必填	默认值	说明
`userId`	`String`	是	—	用户唯一标识
`userAge`	`Int`	是	—	用户年龄
`userGender`	`Int`	否	`0`	性别：`0` 未知 / `1` 男 / `2` 女
`userKeywords`	`List<String>`	否	`emptyList()`	用户标签关键词，如 `["game", "sports"]`

kotlin

// 创建个性化配置
val personalization = UjuPersonalizedConfig(
    userId = "user_001",                         // 用户唯一标识
    userAge = 25,                                // 用户年龄
    userGender = 1,                              // 性别：1 男 / 2 女 / 0 未知
    userKeywords = listOf("game", "sports")      // 用户标签关键词
)

UjuAdInfo

广告信息模型，data class。通过 UjuAdObject.getAdInfo() 获取。

字段

字段	类型	说明
`ecpm`	`Double`	广告价格（eCPM，单位：元）
`placementId`	`String`	广告位 ID
`soltId`	`String`	广告位槽位 ID（注意：源码拼写为 `soltId`）
`platformId`	`Int`	平台 ID，对应 `AdPlatformType` 的数值
`adFormat`	`AdFormat`	广告类型

字段拼写注意

UjuAdInfo 中的槽位 ID 字段拼写为 soltId（非 slotId），这是源码中的实际拼写，使用时请注意保持一致。

kotlin

// 获取广告信息
val adInfo = adObject.getAdInfo()
adInfo?.let { info ->
    // 获取 eCPM 价格（单位：元）
    val ecpm = info.ecpm
    // 获取广告位 ID
    val placementId = info.placementId
    // 获取平台 ID
    val platformId = info.platformId
}

NativeAdData

原生广告自渲染物料数据，data class。通过 UjuAdObject.getAdData() 获取。

字段

字段	类型	说明
`title`	`String?`	广告标题（短文字）
`desc`	`String?`	广告描述（长文字）
`source`	`String?`	广告来源（如广告主名称）
`iconUrl`	`String?`	Icon 图片地址
`mediaType`	`AdMediaType`	媒体类型，默认 `SINGLE_IMAGE`
`imageUrl`	`String?`	主图片链接
`imageUrlList`	`List<String>?`	多图链接列表
`callToAction`	`String?`	行动号召文案（如"立即下载"、"查看详情"）

kotlin

// 获取自渲染物料数据
val adData = adObject.getAdData()
adData?.let { data ->
    // 填充标题与描述
    titleView.text = data.title ?: ""            // 空指针保护
    descView.text = data.desc ?: ""
    sourceView.text = data.source ?: ""
    // 行动号召按钮
    ctaButton.text = data.callToAction ?: "查看详情"
    // 根据 mediaType 加载图片或视频
    when (data.mediaType) {
        AdMediaType.VIDEO -> {
            // 视频素材，使用 mediaViewId 播放
        }
        AdMediaType.MULTI_IMAGE -> {
            // 多图素材，使用 imageUrlList 加载
        }
        else -> {
            // 单图素材，使用 imageUrl 加载
        }
    }
}

NativeAdViewBinder

原生广告视图绑定器，data class。用于将自渲染布局中的控件 ID 绑定到广告物料字段。

字段

字段	类型	说明
`titleId`	`Int?`	标题控件 ID
`descId`	`Int?`	描述控件 ID
`sourceId`	`Int?`	广告来源控件 ID
`iconId`	`Int?`	小图（Icon）控件 ID
`imageId`	`Int?`	大图控件 ID
`imageViews`	`List<ImageView>?`	ImageView 控件列表，自定义布局包含图片时必传
`mediaViewId`	`Int?`	视频控件 ID，自定义布局包含视频时必传
`callToActionId`	`Int?`	按钮控件 ID
`logoLayoutId`	`Int?`	Logo 布局 ID
`clickViewsIds`	`List<Int>?`	可选，指定响应点击的控件 ID 列表（不传则默认全区域点击）
`dislikeId`	`Int?`	可选，不感兴趣按钮控件 ID

kotlin

// 创建视图绑定器
val binder = NativeAdViewBinder(
    titleId = R.id.tv_ad_title,                  // 标题控件 ID
    descId = R.id.tv_ad_desc,                    // 描述控件 ID
    sourceId = R.id.tv_ad_source,                // 来源控件 ID
    iconId = R.id.iv_ad_icon,                    // Icon 控件 ID
    imageId = R.id.iv_ad_image,                  // 大图控件 ID
    mediaViewId = R.id.mv_ad_media,              // 视频控件 ID
    callToActionId = R.id.btn_ad_cta,            // 按钮控件 ID
    logoLayoutId = R.id.ll_ad_logo,              // Logo 布局 ID
    clickViewsIds = listOf(                      // 可选，指定可点击区域
        R.id.iv_ad_image,
        R.id.btn_ad_cta
    ),
    dislikeId = R.id.iv_ad_dislike               // 可选，不感兴趣按钮
)

// 注册视图以启用交互
adObject.registerViewForInteraction(
    activity,                                    // Activity 上下文
    adView,                                      // 广告根视图
    container,                                   // 容器 ViewGroup
    binder                                       // 视图绑定器
)

AdViewSize

广告尺寸配置，data class。单位为 dp，仅对横幅与原生模板广告生效。

字段

字段	类型	默认值	说明
`width`	`Int`	屏幕宽度（dp）	广告宽度，单位 dp
`height`	`Int`	`200`	广告高度，单位 dp

kotlin

// 使用默认尺寸（屏幕宽 × 200dp）
val defaultSize = AdViewSize()

// 自定义尺寸
val customSize = AdViewSize(
    width = 320,                                 // 宽度 320dp
    height = 50                                  // 高度 50dp
)

Listener 接口

SDK 提供一组监听器接口，按广告类型区分。所有广告监听器均继承自 BaseAdObjectListener。

继承关系

BaseAdObjectListener
├── FeedAdObjectListener        （横幅 / 原生信息流）
├── SplashAdObjectListener      （开屏）
├── InterstitialAdObjectListener（插屏）
└── RewardAdObjectListener      （激励视频）

BaseInitListener                （SDK 初始化，独立接口）

BaseAdObjectListener

所有广告对象监听器的基类接口。

方法签名	说明
`onLoadSuccess(placementId: String)`	广告加载成功，返回广告位 ID
`onLoadError(error: UjuException, placementId: String)`	广告加载失败，返回错误信息与广告位 ID

参数数量区分

onLoadError 是 2 个参数：error 与 placementId。
onAdError（子接口中）是 1 个参数：仅 error。两者不要混淆。

FeedAdObjectListener

横幅广告与原生信息流广告监听器，继承 BaseAdObjectListener。

方法签名	说明
`onAdError(error: UjuException)`	广告展示出错（1 个参数）
`onAdShow()`	广告成功展示
`onAdClicked()`	广告被点击
`onAdClosed()`	广告关闭
`onLpClosed()`	落地页关闭

SplashAdObjectListener

开屏广告监听器，继承 BaseAdObjectListener。

方法签名	说明
`onAdError(error: UjuException)`	广告展示出错（1 个参数）
`onAdShow()`	广告成功展示
`onAdClicked()`	广告被点击
`onAdClosed()`	广告关闭

InterstitialAdObjectListener

插屏广告监听器，继承 BaseAdObjectListener。

方法签名	说明
`onAdError(error: UjuException)`	广告展示出错（1 个参数）
`onAdShow()`	广告成功展示
`onAdPlayComplete()`	广告播放结束
`onAdClicked()`	广告被点击
`onLpClosed()`	落地页关闭
`onAdClosed()`	广告关闭

RewardAdObjectListener

激励视频广告监听器，继承 BaseAdObjectListener。

方法签名	说明
`onAdShow()`	广告成功展示
`onAdError(error: UjuException)`	广告展示出错（1 个参数）
`onAdPlayComplete()`	视频播放完成
`onAdClicked()`	广告被点击
`onAdSkippedVideo()`	用户跳过视频
`onAdRewardArrived()`	发放奖励（无参数，无 RewardItem）
`onAdClosed()`	广告关闭

onAdRewardArrived 无参数

onAdRewardArrived() 没有任何参数，不存在 RewardItem 参数。如需自定义奖励信息，请在服务端通过 Server-to-Server（S2S）回调验证。

BaseInitListener

SDK 初始化监听器，独立接口，不继承 BaseAdObjectListener。

方法签名	说明
`onInitSuccess()`	SDK 初始化成功
`onInitFailed(error: UjuException)`	SDK 初始化失败，返回错误信息

kotlin

// SDK 初始化监听器示例
UjuAdSdk.start(object : BaseInitListener {
    override fun onInitSuccess() {
        // 初始化成功，可开始加载广告
    }

    override fun onInitFailed(error: UjuException) {
        // 初始化失败，处理错误
        Log.e("UjuAd", "初始化失败: code=${error.code}, msg=${error.message}")
    }
})

Android API 参考 ​

枚举参考 ​

FeedType ​

AdMediaType ​

AdBidType ​

AdPlatformType ​

UjuAdInitStatus ​

CurrencyType ​

EcpmType ​

公共 API 参考 ​

UjuAdSdk ​

方法列表 ​

UjuAdObject ​

工厂方法（静态） ​

实例方法 ​

UjuAdInitConfig ​

构造参数 ​

UjuAdConfig ​

字段 ​

UjuPrivacyConfig ​

字段 ​

UjuPersonalizedConfig ​

字段 ​

UjuAdInfo ​

字段 ​

NativeAdData ​

字段 ​

NativeAdViewBinder ​

字段 ​

AdViewSize ​

字段 ​

Listener 接口 ​

继承关系 ​

BaseAdObjectListener ​

FeedAdObjectListener ​

SplashAdObjectListener ​

InterstitialAdObjectListener ​

RewardAdObjectListener ​

BaseInitListener ​

相关链接 ​

Android API 参考

枚举参考

FeedType

AdMediaType

AdBidType

AdPlatformType

UjuAdInitStatus

CurrencyType

EcpmType

公共 API 参考

UjuAdSdk

方法列表

UjuAdObject

工厂方法（静态）

实例方法

UjuAdInitConfig

构造参数

UjuAdConfig

字段

UjuPrivacyConfig

字段

UjuPersonalizedConfig

字段

UjuAdInfo

字段

NativeAdData

字段

NativeAdViewBinder

字段

AdViewSize

字段

Listener 接口

继承关系

BaseAdObjectListener

FeedAdObjectListener

SplashAdObjectListener

InterstitialAdObjectListener

RewardAdObjectListener

BaseInitListener

相关链接