优聚智汇

简体中文

English

简体中文

English

外观

iOS 激励视频广告集成 ​

概述 ​

激励视频广告要求用户观看完整视频后获得奖励，具有用户体验好、eCPM 高的特点。SDK 内置倒计时与跳过控制逻辑，开发者只需关注奖励发放时机。

集成步骤 ​

1. 创建并加载激励视频 ​

swift
import UIKit
import UjuAdCore

final class RewardAdHelper {
    private var rewardAd: UjuAdObject?

    func load(vc: UIViewController) {
        // 激励视频建议传入 userId，用于服务端发奖校验
        let config = UjuAdConfig(
            placementId: "YOUR_REWARD_PLACEMENT_ID",
            userId: "USER_123"
        )
        let reward = UjuAdObject.getRewardObject(vc, config: config)
        reward.setAdObjectListener(RewardListener())
        self.rewardAd = reward
        reward.load()
    }

    func show(vc: UIViewController) {
        // 展示前判断 isReady
        if rewardAd?.isReady() == true {
            rewardAd?.show(vc)
        }
    }

    func destroy() {
        rewardAd?.destroy()
        rewardAd = nil
    }
}

2. 实现激励视频监听器 ​

swift
final class RewardListener: RewardAdObjectListener, @unchecked Sendable {
    func onLoadSuccess() {
        // 广告加载成功，可启用"展示广告"按钮
    }

    func onLoadError(error: UjuException) {
        print("激励视频加载失败: \(error.description)")
    }

    func onAdShow() {
        // 广告开始展示
    }

    func onAdClicked() {
        // 广告被点击
    }

    func onAdClosed() {
        // 广告关闭，恢复 App 交互
    }

    func onAdRewardArrived() {
        // ★ 用户获得奖励（倒计时归零），在此发放奖励
        print("用户获得奖励!")
    }

    func onAdPlayComplete() {
        // 视频播放完成（不直接等于发奖，以 onAdRewardArrived 为准）
    }

    func onAdSkippedVideo() {
        // 用户跳过视频，奖励取消
        print("用户跳过视频，未获得奖励")
    }

    func onAdError(error: UjuException) {
        print("激励视频展示错误: \(error.description)")
    }
}

onAdRewardArrived 无参数

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

奖励判断逻辑 ​

激励视频的发奖判断以回调为准：

回调是否发奖说明
onAdRewardArrived()发放奖励用户观看完整视频（倒计时归零）
onAdSkippedVideo()不发放奖励用户跳过视频
onAdPlayComplete()不直接发奖视频播放完成，以 onAdRewardArrived 为准

15s 跳过规则 ​

SDK 内置激励视频跳过控制逻辑：

  • 未达 15 秒点击跳过：弹出确认弹窗，提供「继续观看」与「确认跳过」两个按钮。用户选择「确认跳过」则触发 onAdSkippedVideo（不发奖）；选择「继续观看」则继续播放。
  • 已达 15 秒点击跳过：直接关闭视频，无需二次确认，且视为正常完成（触发 onAdRewardArrived）。

弹窗与播放状态

跳过确认弹窗展示时，SDK 会自动暂停视频播放与倒计时；关闭弹窗后恢复播放（「确认跳过」除外）。开发者无需自行处理播放暂停逻辑。

userId 透传 ​

激励视频建议在 UjuAdConfig 中传入 userId，用于服务端发奖校验（S2S 回调时匹配用户身份）：

swift
let config = UjuAdConfig(
    placementId: "YOUR_REWARD_PLACEMENT_ID",
    userId: "USER_123"
)

最佳实践 ​

  1. 预加载：在用户可能触发展示的场景前提前 load()，展示时只需 show()
  2. 展示前检查：调用 show() 前务必检查 isReady()
  3. 发奖时机：仅在 onAdRewardArrived 中发放奖励，onAdSkippedVideo 不发奖
  4. 资源释放：广告关闭后调用 destroy()
  5. 服务端校验：建议配合 S2S 回调做服务端发奖校验，避免客户端伪造

常见问题 ​

Q: 如何判断用户应得奖励？ ​

A: 以 onAdRewardArrived() 回调为准。onAdPlayComplete() 仅表示视频播放完成，不直接等于发奖。

Q: 用户跳过视频会发奖吗？ ​

A: 不会。用户跳过视频（未达奖励要求）会触发 onAdSkippedVideo，此时不应发放奖励。已达 15 秒跳过视为正常完成，会触发 onAdRewardArrived。

Q: 激励视频加载失败怎么办？ ​

A: 在 onLoadError 中提示用户，可降级到其他广告位或延迟重试。错误码 102（noFill）表示本次无填充，属正常业务响应。

相关链接 ​