Rewarded Ads

Integrate CloudX rewarded ads in Flutter apps

Rewarded ads are full-screen ads that grant the user a reward when they finish watching.

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

const adUnitId = 'rewarded_coins';

CloudX.setRewardedListener(CloudXRewardedListener(
  onAdLoaded: (ad) {
    debugPrint('Rewarded loaded from ${ad.networkName}');
  },
  onAdLoadFailed: (adUnitId, error) {
    debugPrint('Rewarded load failed: ${error.code} ${error.message}');
  },
  onAdDisplayed: (ad) {
    debugPrint('Rewarded displayed');
  },
  onAdDisplayFailed: (ad, error) {
    // Terminal for this ad: request another fill, or this flow stops here.
    debugPrint('Rewarded display failed: ${error.message}');
    CloudX.loadRewarded(adUnitId: ad.adUnitId);
  },
  onAdReceivedReward: (ad, reward) {
    // Grant the reward here, not in onAdHidden.
    debugPrint('Earned ${reward.amount} ${reward.label}');
  },
  onAdClicked: (ad) {
    debugPrint('Rewarded clicked');
  },
  onAdHidden: (ad) {
    // Destroy before reloading: the ad just shown is still counted as showing.
    CloudX.destroyRewarded(adUnitId: ad.adUnitId);
    CloudX.loadRewarded(adUnitId: ad.adUnitId);
  },
  onAdRevenuePaid: (ad) {
    debugPrint('Revenue: ${ad.revenue}');
  },
));

// Loading creates the ad instance for you; there is no separate create step.
CloudX.loadRewarded(adUnitId: adUnitId);

// At the placement:
if (await CloudX.isRewardedReady(adUnitId: adUnitId)) {
  CloudX.showRewarded(adUnitId: adUnitId);
  // Or tag the impression:
  // CloudX.showRewarded(
  //   adUnitId: adUnitId,
  //   placement: 'bonus_coins',
  //   customData: 'level_3',
  // );
} else {
  debugPrint('Rewarded ad not ready yet');
}

Release the ad when the screen goes away. This belongs in your widget’s dispose(), not in the block above: destroying straight after the show request can cancel the ad before it appears.

CloudX.destroyRewarded(adUnitId: adUnitId);

The Reward

onAdReceivedReward fires when the user earns the reward, which is the only callback that means “pay the user”. It arrives before onAdHidden, and it does not fire when the user dismisses the ad early.

CloudXReward carries:

PropertyTypeDescription
amountintHow much to grant.
labelStringWhat to grant, for example coins.

Both values come from the ad unit’s reward settings in the CloudX dashboard.

Lifecycle

Set the listener before you load, because events dispatched with no listener registered are dropped. One listener serves every rewarded ad unit, so a screen should claim it right before loading and check ad.adUnitId in the callbacks.

Showing a rewarded ad consumes it. Load the next one from onAdHidden, destroying it first in that callback: that lets the next load build a fresh instance and run a new auction straight away. Destroy the ad in your widget’s dispose() as well.

CloudX.setRewardedExtraParameter attaches network or server-side configuration to the next load, including the first one. See per-load extra parameters.

Events

CloudXRewardedListener carries these callbacks.

CallbackSignatureRequired
onAdLoaded(CloudXAd ad)Yes
onAdLoadFailed(String adUnitId, CloudXError error)Yes
onAdDisplayed(CloudXAd ad)Yes
onAdDisplayFailed(CloudXAd ad, CloudXError error)Yes
onAdReceivedReward(CloudXAd ad, CloudXReward reward)Yes
onAdClicked(CloudXAd ad)Yes
onAdHidden(CloudXAd ad)Yes
onAdRevenuePaid(CloudXAd ad)No