Banner & MREC Ads

Integrate CloudX banner and MREC ads in Flutter apps

Banner ads are 320x50 and MREC ads are 300x250. Both render as a programmatic overlay: you create one at a screen position, then show and hide it as your app needs.

Programmatic Overlay Banner

The overlay attaches to the host Activity or root view controller and stays at a fixed screen position while your content scrolls underneath.

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

const adUnitId = 'home_banner';

CloudX.setBannerListener(CloudXAdViewListener(
  onAdLoaded: (ad) {
    // Fires again on every auto-refresh fill, so do not force visibility here:
    // it would undo a hideBanner the app did in the meantime.
    debugPrint('Banner loaded from ${ad.networkName}');
  },
  onAdLoadFailed: (adUnitId, error) {
    debugPrint('Banner failed: ${error.code} ${error.message}');
  },
  onAdClicked: (ad) => debugPrint('Banner clicked'),
  onAdRevenuePaid: (ad) => debugPrint('Banner revenue: ${ad.revenue}'),
));

// Creating the banner loads it and starts auto-refresh.
CloudX.createBanner(
  adUnitId: adUnitId,
  position: CloudXAdViewPosition.bottomCenter,
);

Creating the banner attaches the overlay hidden and starts an asynchronous load, so the calls below belong to later moments in the screen’s life rather than to the block above.

Show the overlay when the placement should be on screen. Until this runs, the banner loads and refreshes without being visible:

CloudX.showBanner(adUnitId: adUnitId);

Hide it again when the placement goes away:

CloudX.hideBanner(adUnitId: adUnitId);

Destroy it in your widget’s dispose(), which releases the ad and its refresh timer:

CloudX.destroyBanner(adUnitId: adUnitId);

Positions come from CloudXAdViewPosition: topLeft, topCenter, topRight, centerLeft, centered, centerRight, bottomLeft, bottomCenter, bottomRight. The position is fixed when the overlay is created. To move one, destroy it and create it again at the new position.

Programmatic Overlay MREC

MREC mirrors the banner API method for method.

const adUnitId = 'home_mrec';

CloudX.setMrecListener(CloudXAdViewListener(
  onAdLoaded: (ad) {
    // Fires again on every auto-refresh fill; see the banner note above.
    debugPrint('MREC loaded from ${ad.networkName}');
  },
  onAdLoadFailed: (adUnitId, error) => debugPrint('MREC failed: ${error.message}'),
  onAdClicked: (ad) => debugPrint('MREC clicked'),
));

CloudX.createMrec(adUnitId: adUnitId, position: CloudXAdViewPosition.centered);

The rest of the MREC lifecycle follows the same rule as the banner: the overlay is attached hidden, and each call belongs to its own moment rather than to the block above.

CloudX.showMrec(adUnitId: adUnitId);   // when the placement should be visible
CloudX.hideMrec(adUnitId: adUnitId);   // when it goes away

And, in dispose():

CloudX.destroyMrec(adUnitId: adUnitId);

Auto-Refresh Control

These calls address an ad by its ad unit id, so they reach only ads you created with createBanner or createMrec.

Overlay banner and MREC ads refresh on their own once created. Pause and resume that cycle when the placement leaves or returns to the screen:

CloudX.stopBannerAutoRefresh(adUnitId: adUnitId);
CloudX.startBannerAutoRefresh(adUnitId: adUnitId);

CloudX.stopMrecAutoRefresh(adUnitId: adUnitId);
CloudX.startMrecAutoRefresh(adUnitId: adUnitId);

CloudX.loadBanner and CloudX.loadMrec request one new fill. You only need them after pausing auto-refresh, because creating the ad already loads it.

Auto-refresh can also be disabled for an ad unit in its dashboard configuration. That setting outranks the app: startBannerAutoRefresh and startMrecAutoRefresh are ignored with a warning on such an ad unit, and loadBanner or loadMrec is how you request each fill there.

CloudX.loadBanner(adUnitId: adUnitId);

Placement and Custom Data

Tag the ad with the in-app placement it fills and any custom string your reporting needs. These setters also address the ad by its ad unit id, so call them after createBanner or createMrec: with no overlay created for that ad unit, the call is ignored with a log line.

Neither createBanner nor createMrec takes these values, and creating the ad already starts its first load, so that first request carries no placement and no custom data. Both are attached from the next refresh or loadBanner / loadMrec onward.

CloudX.setBannerPlacement(adUnitId: adUnitId, placement: 'home_screen');
CloudX.setBannerCustomData(adUnitId: adUnitId, customData: 'level_3');

CloudX.setMrecPlacement(adUnitId: adUnitId, placement: 'article_feed');
CloudX.setMrecCustomData(adUnitId: adUnitId, customData: 'level_3');

CloudX.setBannerExtraParameter and CloudX.setMrecExtraParameter carry network or server-side configuration on a load, and they do not follow that rule: a value set before createBanner or createMrec is held for the ad unit and applied at creation, so the first request carries it. See per-load extra parameters.

Events

CloudXAdViewListener carries the banner and MREC callbacks.

The listeners are global: setBannerListener serves every banner ad unit and setMrecListener serves every MREC ad unit, so read ad.adUnitId there to tell placements apart.