优聚智汇

简体中文

English

简体中文

English

外观

Android 激励视频广告集成 ​

概述 ​

激励视频广告是一种全屏视频广告，用户观看完整视频后可以获得奖励，具有以下特点：

  • 高用户参与度
  • 高收益潜力
  • 良好的用户体验
  • 适合游戏、工具类应用

集成步骤 ​

参考demo示例的RewardAdHelper

1. 初始化激励视频广告 ​

在 Activity 或 Fragment 中加载激励视频广告：

kotlin
class RewardAdHelper(private val activity: Activity, private val logger: PrintLogger) {
    private var rewardAd: UjuAdObject? = null

    /**
     * 加载激励广告
     * 
     * 该方法会创建广告配置，通过工厂方法获取激励广告对象，并设置广告监听器
     * 最后调用load()方法开始加载广告
     */
    fun load() {
        // 创建广告配置对象，设置广告位ID
        // scenarioKey 为可选参数，用于统计广告展示场景
        val adConfig = UjuAdConfig(
            placementId = DemoConfig.REWARD_ID, // 激励广告位ID
            // scenarioKey = "your_scenario_key", // 可选，用于统计广告展示场景
            // userId = "user_123", // 可选，用户 ID，用于服务端奖励验证
            // customData = mapOf("key" to "value"), // 可选，自定义数据，透传给服务端
        )
        
        // 通过 UjuAdObject 工厂方法获取激励广告对象
        rewardAd = UjuAdObject.getRewardObject(activity, adConfig)
        
        // 设置广告监听器，监听广告的各种事件
        rewardAd?.setAdObjectListener(object : RewardAdObjectListener {
            /**
             * 广告加载成功回调
             * 
             * @param placementId 广告位ID
             */
            override fun onLoadSuccess(placementId: String) {
                // 广告加载成功，此时可以展示，建议展示前判断isReady
                logger.add("Reward: onLoadSuccess")
            }

            /**
             * 广告加载失败回调
             * 
             * @param error 错误信息
             * @param placementId 广告位ID
             */
            override fun onLoadError(
                error: UjuException,
                placementId: String
            ) {
                // 加载失败，记录错误信息
                logger.add("Reward: onLoadError：${error.message}")
            }

            /**
             * 广告展示成功回调
             */
            override fun onAdShow() {
                // 获取广告信息，记录ecpm值
                val ecpm = rewardAd?.getAdInfo()?.ecpm
                logger.add("Reward: onAdShow: ecpm:$ecpm")
            }

            /**
             * 广告展示过程中出错回调
             *
             * @param error 错误信息
             */
            override fun onAdError(
                error: UjuException
            ) {
                // 记录广告错误信息
                logger.add("Reward: onAdError：${error.message}")
            }

            /**
             * 广告播放完成回调
             */
            override fun onAdPlayComplete() {
                // 记录广告播放完成事件
                logger.add("Reward: onAdPlayComplete")
            }

            /**
             * 广告被点击回调
             */
            override fun onAdClicked() {
                // 记录广告点击事件
                logger.add("Reward: onAdClicked")
            }

            /**
             * 用户跳过视频回调
             */
            override fun onAdSkippedVideo() {
                // 记录用户跳过视频事件
                logger.add("Reward: onAdSkippedVideo")
            }

            /**
             * 奖励到达回调
             * 
             * 当用户观看完广告后，会触发此回调，在此处发放奖励
             */
            override fun onAdRewardArrived() {
                // 记录奖励到达事件
                logger.add("Reward: onAdRewardArrived")
                // 注意：实际应用中，应在此回调中向用户发放奖励
            }

            /**
             * 广告关闭回调
             */
            override fun onAdClosed() {
                // 销毁广告对象，释放资源
                rewardAd?.destroy()
                rewardAd = null
                // 记录广告关闭事件
                logger.add("Reward: onAdClosed")
            }
        })
        
        // 开始加载广告
        rewardAd?.load()
        // 记录加载广告的事件
        logger.add("Reward: load, placementId:${adConfig.placementId}")
    }

    /**
     * 展示激励广告
     * 
     * 在展示广告前，会检查广告是否已准备就绪
     * 只有当广告状态为ready时，才会调用show()方法展示广告
     */
    fun show() {
        // 检查广告是否已准备就绪
        if (rewardAd?.isReady() == true) {
            // 广告已准备就绪，展示广告
            rewardAd?.show(activity)
        } else {
            // 广告未准备就绪，记录日志
            logger.add("Reward: 广告还未准备好")
        }
    }

    /**
     * 检查广告是否已加载
     * 
     * @return true表示广告对象已创建，false表示未创建
     * 注意：此方法仅检查广告对象是否存在，不保证广告已准备就绪
     * 要检查广告是否可展示，请使用isReady()方法
     */
    fun isLoaded(): Boolean {
        return rewardAd != null
    }

    /**
     * 销毁广告对象
     * 
     * 当不再需要广告时，调用此方法销毁广告对象，释放资源
     */
    fun destroy() {
        // 销毁广告对象
        rewardAd?.destroy()
        // 置空广告对象引用
        rewardAd = null
    }

}

UjuAdConfig 配置说明 ​

参数类型必填说明
placementIdString是广告位ID
scenarioKeyString否广告展示场景标识，用于统计广告展示场景
userIdString否用户 ID，用于服务端奖励验证（推荐传入，便于服务端校验奖励发放）
customDataMap<String, String>否自定义数据，透传给广告服务端，可用于奖励回调校验
adViewSizeAdViewSize否广告尺寸（激励视频一般无需设置）

2. 展示激励视频广告 ​

当用户触发观看广告的行为时（如点击"观看广告获取奖励"按钮），展示广告：

kotlin
fun show() {
    if (rewardAd?.isReady() == true) {
        rewardAd?.show(activity)
    } else {
        logger.add("Reward: 广告还未准备好")
    }
}

3. 发放奖励 ​

在 onAdRewardArrived() 回调中直接发放开发者预定义的奖励。SDK 不回传奖励类型/数量，奖励逻辑由开发者自定义：

kotlin
// 在 RewardAdObjectListener 中实现奖励回调
override fun onAdRewardArrived() {
    // SDK 不回传奖励类型/数量，开发者在此处发放预定义的奖励
    // 例如：发放固定数量的金币
    userCoins += 100
    updateCoinsDisplay()
    // 显示奖励提示
    showRewardToast("获得 100 金币")
}

4. 广告生命周期管理 ​

SDK 内部通过 AppLifecycleObserver 自动处理前后台切换与视频暂停/恢复，开发者无需手动调用 pause()/resume()。只需在 Activity 销毁时释放广告资源：

kotlin
/**
 * 当Activity销毁时调用
 *
 * 在此方法中销毁广告，释放资源，避免内存泄漏
 */
override fun onDestroy() {
    super.onDestroy()
    // 销毁广告
    if (rewardAd != null) {
        rewardAd?.destroy()
        rewardAd = null
    }
}

最佳实践 ​

1. 广告触发时机 ​

  • 游戏关卡失败后：提供观看广告继续游戏的选项
  • 资源不足时：提供观看广告获得额外资源
  • 解锁内容前：提供观看广告解锁高级内容
  • 每日奖励：提供观看广告获得额外每日奖励

2. 优化建议 ​

  • 预加载广告：在需要展示广告前提前加载
  • 广告状态检查：在展示前检查广告是否已加载
  • 奖励发放：确保奖励发放的可靠性
  • 用户体验：提供清晰的奖励提示
  • 频率控制：避免过度展示广告

3. 避免的问题 ​

  • 不要在用户关键操作时强制展示广告
  • 不要虚假宣传奖励
  • 不要在广告加载失败时影响应用正常功能
  • 不要在用户未完成观看时发放奖励

常见问题 ​

Q: 激励视频广告为什么不显示？ ​

A: 可能的原因：

  • 广告单元 ID 不正确
  • 网络连接问题
  • 广告库存不足
  • 广告未加载完成
  • 设备限制

Q: 如何确保奖励发放的可靠性？ ​

A: 建议：

  • 在 onAdRewardArrived 回调中发放奖励
  • 服务端验证奖励的有效性
  • 本地存储奖励记录，防止意外情况
  • 提供奖励发放失败的重试机制

Q: 如何提高激励视频广告的收益？ ​

A: 建议：

  • 选择合适的广告触发时机
  • 提供有吸引力的奖励
  • 优化广告展示频率
  • 确保广告与应用内容相关
  • 提高应用用户活跃度

相关链接 ​