Interstitial Ads

Integrate CloudX interstitial ads in Flutter apps

Interstitial ads are full-screen ads shown at natural transition points, such as between levels or after a task completes.

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

const adUnitId = 'level_complete';

CloudX.setInterstitialListener(CloudXInterstitialListener(
  onAdLoaded: (ad) {
    debugPrint('Interstitial loaded from ${ad.networkName}');
  },
  onAdLoadFailed: (adUnitId, error) {
    debugPrint('Interstitial load failed: ${error.code} ${error.message}');
  },
  onAdDisplayed: (ad) {
    debugPrint('Interstitial displayed');
  },
  onAdDisplayFailed: (ad, error) {
    // Terminal for this ad: request another fill, or this flow stops here.
    debugPrint('Interstitial display failed: ${error.message}');
    CloudX.loadInterstitial(adUnitId: ad.adUnitId);
  },
  onAdClicked: (ad) {
    debugPrint('Interstitial clicked');
  },
  onAdHidden: (ad) {
    // The ad just shown still counts as showing here, so destroy it before
    // loading again. The next load builds a fresh instance and a new auction.
    CloudX.destroyInterstitial(adUnitId: ad.adUnitId);
    CloudX.loadInterstitial(adUnitId: ad.adUnitId);
  },
  onAdRevenuePaid: (ad) {
    debugPrint('Revenue: ${ad.revenue}');
  },
));

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

// At the placement:
if (await CloudX.isInterstitialReady(adUnitId: adUnitId)) {
  CloudX.showInterstitial(adUnitId: adUnitId);
  // Or tag the impression:
  // CloudX.showInterstitial(
  //   adUnitId: adUnitId,
  //   placement: 'level_complete',
  //   customData: 'level_3',
  // );
} else {
  debugPrint('Interstitial 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.destroyInterstitial(adUnitId: adUnitId);

Lifecycle

Set the listener before you load. Events dispatched with no listener registered are dropped, so a listener installed after loadInterstitial can miss the load result.

One listener serves every interstitial ad unit. If several screens load interstitials, each one should claim the listener right before it loads, and read ad.adUnitId in the callbacks to confirm which placement the event belongs to.

Destroy the ad in your widget’s dispose(). Showing an interstitial consumes it, so 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.

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

Events

CloudXInterstitialListener carries these callbacks.

Callback	Signature	Required
`onAdLoaded`	`(CloudXAd ad)`	Yes
`onAdLoadFailed`	`(String adUnitId, CloudXError error)`	Yes
`onAdDisplayed`	`(CloudXAd ad)`	Yes
`onAdDisplayFailed`	`(CloudXAd ad, CloudXError error)`	Yes
`onAdClicked`	`(CloudXAd ad)`	Yes
`onAdHidden`	`(CloudXAd ad)`	Yes
`onAdRevenuePaid`	`(CloudXAd ad)`	No