激励视频广告

在 Flutter 应用中接入 CloudX 激励视频广告

激励视频广告是全屏广告,用户看完后可以获得奖励。

import 'package:cloudx_flutter/cloudx.dart';
import 'package:flutter/foundation.dart';

const adUnitId = 'rewarded_coins';

CloudX.setRewardedListener(CloudXRewardedListener(
  onAdLoaded: (ad) {
    debugPrint('激励视频广告已加载,来自 ${ad.networkName}');
  },
  onAdLoadFailed: (adUnitId, error) {
    debugPrint('激励视频广告加载失败:${error.code} ${error.message}');
  },
  onAdDisplayed: (ad) {
    debugPrint('激励视频广告已展示');
  },
  onAdDisplayFailed: (ad, error) {
    // 这条广告已终止:需要重新请求填充,否则流程到此为止。
    debugPrint('激励视频广告展示失败:${error.message}');
    CloudX.loadRewarded(adUnitId: ad.adUnitId);
  },
  onAdReceivedReward: (ad, reward) {
    // 在这里发放奖励,而不是在 onAdHidden 中。
    debugPrint('获得 ${reward.amount} ${reward.label}');
  },
  onAdClicked: (ad) {
    debugPrint('激励视频广告被点击');
  },
  onAdHidden: (ad) {
    // 先销毁再重新加载:刚展示的广告此刻仍被视为展示中。
    CloudX.destroyRewarded(adUnitId: ad.adUnitId);
    CloudX.loadRewarded(adUnitId: ad.adUnitId);
  },
  onAdRevenuePaid: (ad) {
    debugPrint('收入:${ad.revenue}');
  },
));

// 加载时会自动创建广告实例,无需单独的创建步骤。
CloudX.loadRewarded(adUnitId: adUnitId);

// 在广告位处:
if (await CloudX.isRewardedReady(adUnitId: adUnitId)) {
  CloudX.showRewarded(adUnitId: adUnitId);
  // 也可以为该次展示打标记:
  // CloudX.showRewarded(
  //   adUnitId: adUnitId,
  //   placement: 'bonus_coins',
  //   customData: 'level_3',
  // );
} else {
  debugPrint('激励视频广告尚未就绪');
}

页面销毁时释放广告。该调用属于 Widget 的 dispose(),而不属于上面的代码块:在 请求展示之后立即销毁,可能会让广告还没出现就被取消。

CloudX.destroyRewarded(adUnitId: adUnitId);

奖励

onAdReceivedReward 在用户赢得奖励时触发,它是唯一表示”应当给用户发奖”的回调。该回调先于 onAdHidden;如果用户提前关闭广告,则不会触发。

CloudXReward 包含:

属性类型说明
amountint发放数量。
labelString奖励名称,例如 coins

两个值都来自 CloudX 控制台中该广告单元的奖励设置。

生命周期

请在加载之前设置监听器,因为没有注册监听器时派发的事件会被丢弃。一个监听器服务于所有激励视频广告单元,因此页面应在加载前重新认领监听器,并在回调中检查 ad.adUnitId

展示激励视频广告会消耗掉它。请在 onAdHidden 中加载下一条,并在该回调中先销毁:这样下一次加载会立即创建新的实例并发起新的竞价。此外也要在组件的 dispose() 中销毁广告。

CloudX.setRewardedExtraParameter 可为下一次加载(包括首次加载)附加广告网络或服务端配置。参见单次加载的额外参数

事件

CloudXRewardedListener 包含以下回调。

回调签名是否必需
onAdLoaded(CloudXAd ad)
onAdLoadFailed(String adUnitId, CloudXError error)
onAdDisplayed(CloudXAd ad)
onAdDisplayFailed(CloudXAd ad, CloudXError error)
onAdReceivedReward(CloudXAd ad, CloudXReward reward)
onAdClicked(CloudXAd ad)
onAdHidden(CloudXAd ad)
onAdRevenuePaid(CloudXAd ad)