激励视频广告

在 Android 应用中集成 CloudX 激励视频广告

激励视频广告在用户观看全屏广告后给予奖励,通常为应用内货币或额外内容。

CloudX 渲染的素材

CloudX 下发的素材由内置渲染器渲染,渲染器已内置于核心 SDK,无需单独的渲染器适配器模块。素材类型根据出价响应自动选择,发布者无需额外集成即可渲染任一格式。渲染器在各广告格式中支持 MRAID 3.0(HTML)和 VAST 素材:

广告格式HTML(MRAID 3.0)VAST
Banner✓—
MREC✓✓
Interstitial✓✓
Rewarded✓✓
class MainActivity : AppCompatActivity(), CloudXRewardedListener, CloudXAdRevenueListener {
    private lateinit var rewardedAd: CloudXRewardedAd
    private var retryAttempt = 0

    private fun createRewardedAd() {
        rewardedAd = CloudX.createRewarded(this, "your-rewarded-ad-unit-id")
        rewardedAd.listener = this
        rewardedAd.revenueListener = this
        rewardedAd.load()
    }

    private fun showRewardedAd() {
        if (rewardedAd.isAdReady) {
            // 基本展示
            rewardedAd.show(this)

            // 或带有可选的广告位和自定义数据用于跟踪
            // rewardedAd.show(this, "bonus_coins", "level:5,coins:100")
        } else {
            Log.w("CloudX", "激励视频广告尚未准备好")
        }
    }

    // CloudXRewardedListener 回调
    override fun onAdLoaded(cloudXAd: CloudXAd) {
        Log.d("CloudX", "激励视频广告已加载,来自 ${cloudXAd.networkName}")
        retryAttempt = 0
    }

    /**
     * Retries loading with exponential backoff: delay doubles with each attempt
     * (2s → 4s → 8s … 32s max) to avoid hammering the server during transient
     * failures. [retryAttempt] resets to 0 in [onAdLoaded].
     */
    override fun onAdLoadFailed(adUnitId: String, cloudXError: CloudXError) {
        Log.e("CloudX", "激励视频广告加载失败: ${cloudXError.message}")
        retryAttempt++
        val delayMillis = TimeUnit.SECONDS.toMillis(2.0.pow(retryAttempt.coerceAtMost(5)).toLong())
        Handler(Looper.getMainLooper()).postDelayed({ rewardedAd.load() }, delayMillis)
    }

    override fun onAdDisplayed(cloudXAd: CloudXAd) {
        Log.d("CloudX", "激励视频广告已展示")
    }

    override fun onAdDisplayFailed(cloudXAd: CloudXAd, cloudXError: CloudXError) {
        Log.e("CloudX", "激励视频广告展示失败: ${cloudXError.message}")
        rewardedAd.load()
    }

    override fun onAdHidden(cloudXAd: CloudXAd) {
        Log.d("CloudX", "激励视频广告已隐藏")
        // 为下次使用重新加载
        rewardedAd.load()
    }

    override fun onAdClicked(cloudXAd: CloudXAd) {
        Log.d("CloudX", "激励视频广告被点击")
    }

    override fun onUserRewarded(cloudXAd: CloudXAd, reward: CloudXReward) {
        Log.d("CloudX", "用户获得奖励: ${reward.amount} ${reward.label}")
        // 为用户发放奖励
    }

    // CloudXAdRevenueListener 回调
    override fun onAdRevenuePaid(cloudXAd: CloudXAd) {
        Log.d("CloudX", "激励视频竞价时收入: ${cloudXAd.revenue},来自 ${cloudXAd.networkName}")
    }

    override fun onDestroy() {
        super.onDestroy()
        rewardedAd.destroy()
    }
}

广告就绪状态

isAdReady 从广告加载完成起保持为 true,直到您展示该广告或销毁广告对象。广告网络可能在未通知 SDK 的情况下无法再展示某个广告。此时 isAdReady 仍为 true,该问题会在您调用 show() 时被发现。如果广告网络确实报告其广告已过期,广告将不再就绪。

  • 如果对广告网络已无法展示的广告调用 show(),会触发 onAdDisplayFailed,广告不再就绪。请调用 load() 获取新广告。
  • 在这种情况下,如果 CloudX 已为您的应用和广告单元启用展示恢复,SDK 会加载并展示一个替换广告。您会收到替换广告的展示和收益回调,不会收到 onAdDisplayFailed。如果过期广告的替换广告已在加载中,SDK 会使用它,并在展示前触发 onExpiredAdReloaded。如果替换广告加载失败,或未能在 CloudX 设定的时限内就绪,会触发 onAdDisplayFailed。
  • 如果在广告已就绪时调用 load(),不会发起新请求,并会立即以该广告触发 onAdLoaded。
  • 在广告展示期间调用 load(),会在广告关闭后执行。在 show() 等待恢复替换广告期间调用 load(),同样会在展示结束后执行,并且只会收到一次 onAdLoaded 或 onAdLoadFailed。

过期广告

已加载但在过期前未展示的广告,会在同一广告对象上自动重新加载。在替换广告就绪之前,当前广告保持就绪状态,仍可展示。

  • 如需在替换广告就绪时收到通知,请设置 expirationListener。自动加载完成的替换广告不会再次触发 onAdLoaded。
  • 如果在替换广告加载期间展示广告,替换广告会被保留。如果广告关闭时替换广告已就绪,或在其就绪前没有调用 load(),替换广告会在广告对象上变为就绪,届时会调用 expirationListener。如果在广告关闭后、替换广告仍在加载时调用 load(),该 load() 会发起自己的请求并收到 onAdLoaded,之后不会再针对该替换广告调用 expirationListener。
  • 如果在过期广告仍处于已加载状态时调用 load(),不会发起新请求,并会立即以该过期广告触发 onAdLoaded。替换广告会继续加载,就绪时会调用 expirationListener。
  • 如果在过期广告仍处于已加载状态时替换广告加载失败,会触发 onAdLoadFailed,广告不再就绪。重新加载及其重试由 CloudX 按广告单元配置,且默认不重试,因此一次无填充就会在此结束。这是正常结果,并非集成错误:请在延迟一段时间后再次调用 load(),避免立即循环重试。
rewardedAd.expirationListener = CloudXAdExpirationListener { expiredAd, newAd ->
    Log.d("CloudX", "Expired rewarded ad replaced by an ad from ${newAd.networkName}")
}