横幅广告和 MREC

在 Flutter 应用中接入 CloudX 横幅广告和 MREC 广告

横幅广告尺寸为 320x50，MREC 广告为 300x250。两种格式都以程序化浮层展示：在指定的屏幕位置创建广告，再按需要展示或隐藏。

程序化浮层：横幅广告

浮层会附加到宿主 Activity 或根视图控制器上，固定在屏幕某个位置，您的内容在其下方滚动。

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

const adUnitId = 'home_banner';

CloudX.setBannerListener(CloudXAdViewListener(
  onAdLoaded: (ad) {
    // 每次自动刷新拿到新填充时都会触发，因此不要在这里强制显示：
    // 那会撤销应用此前调用的 hideBanner。
    debugPrint('横幅广告已加载，来自 ${ad.networkName}');
  },
  onAdLoadFailed: (adUnitId, error) {
    debugPrint('横幅广告加载失败：${error.code} ${error.message}');
  },
  onAdClicked: (ad) => debugPrint('横幅广告被点击'),
  onAdRevenuePaid: (ad) => debugPrint('横幅广告收入：${ad.revenue}'),
));

// 创建横幅广告会同时触发加载并开启自动刷新。
CloudX.createBanner(
  adUnitId: adUnitId,
  position: CloudXAdViewPosition.bottomCenter,
);

创建横幅广告时，浮层以隐藏状态附加，并启动一次异步加载，因此下面这些调用属于页面生命周期中较晚的时刻，而不属于上面的代码块。

当该广告位应当出现在屏幕上时展示浮层。在此之前，横幅广告会照常加载和刷新，只是不可见：

CloudX.showBanner(adUnitId: adUnitId);

当该广告位离开时再隐藏：

CloudX.hideBanner(adUnitId: adUnitId);

在组件的 dispose() 中销毁，以释放广告及其刷新定时器：

CloudX.destroyBanner(adUnitId: adUnitId);

位置取值来自 CloudXAdViewPosition：topLeft、topCenter、topRight、centerLeft、centered、centerRight、bottomLeft、bottomCenter、bottomRight。浮层广告的位置在创建时确定。若要移动它，请先销毁再按新位置重新创建。

程序化浮层：MREC

MREC 的 API 与横幅广告一一对应。

const adUnitId = 'home_mrec';

CloudX.setMrecListener(CloudXAdViewListener(
  onAdLoaded: (ad) {
    // 每次自动刷新拿到新填充时都会触发，参见上文横幅广告的说明。
    debugPrint('MREC 已加载，来自 ${ad.networkName}');
  },
  onAdLoadFailed: (adUnitId, error) => debugPrint('MREC 加载失败：${error.message}'),
  onAdClicked: (ad) => debugPrint('MREC 被点击'),
));

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

MREC 其余的生命周期调用与横幅广告遵循同样的规则：浮层同样以隐藏状态附加，每个调用都属于各自的时刻，而不属于上面的代码块。

CloudX.showMrec(adUnitId: adUnitId);   // 该广告位应当可见时
CloudX.hideMrec(adUnitId: adUnitId);   // 该广告位离开时

以及在 dispose() 中：

CloudX.destroyMrec(adUnitId: adUnitId);

自动刷新控制

这些调用通过广告单元 ID 定位广告，因此只作用于用 createBanner 或 createMrec 创建的广告。

浮层横幅广告和 MREC 创建后会自动刷新。当广告位离开或回到屏幕时，可以暂停和恢复该循环：

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

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

CloudX.loadBanner 和 CloudX.loadMrec 会请求一次新的填充。由于创建广告时已经加载过，只有在暂停自动刷新之后才需要它们。

广告单元也可能在控制台配置中被关闭自动刷新。该设置优先于应用：此时 startBannerAutoRefresh 和 startMrecAutoRefresh 会被忽略并记录警告，需要改用 loadBanner 或 loadMrec 来逐次请求填充。

CloudX.loadBanner(adUnitId: adUnitId);

广告位与自定义数据

为广告标记它所填充的应用内广告位，以及报表需要的自定义字符串。这些设置同样通过广告单元 ID 定位广告，因此请在 createBanner 或 createMrec 之后调用：若该广告单元没有已创建的浮层广告，调用会被忽略并仅记录一条日志。

createBanner 和 createMrec 都不接受这两个值，而创建广告本身就会发起首次加载，因此首次请求不会带上广告位和自定义数据。它们从下一次刷新或 loadBanner / loadMrec 开始生效。

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 和 CloudX.setMrecExtraParameter 用于为一次加载附加广告网络或服务端配置，但它们不遵循上面这条规则：在 createBanner 或 createMrec 之前设置的值会按广告单元暂存，并在创建时应用，因此首次请求也会带上它们。参见单次加载的额外参数。

事件

横幅广告和 MREC 的回调都在 CloudXAdViewListener 中。

回调	签名	是否必需
`onAdLoaded`	`(CloudXAd ad)`	是
`onAdLoadFailed`	`(String adUnitId, CloudXError error)`	是
`onAdClicked`	`(CloudXAd ad)`	是
`onAdRevenuePaid`	`(CloudXAd ad)`	否

监听器是全局的：setBannerListener 服务于所有横幅广告单元，setMrecListener 服务于所有 MREC 广告单元，因此请读取 ad.adUnitId 来区分不同广告位。