插屏广告

在 Flutter 应用中接入 CloudX 插屏广告

插屏广告是全屏广告，适合在自然的转场时机展示，例如关卡之间或某项任务完成之后。

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

const adUnitId = 'level_complete';

CloudX.setInterstitialListener(CloudXInterstitialListener(
  onAdLoaded: (ad) {
    debugPrint('插屏广告已加载，来自 ${ad.networkName}');
  },
  onAdLoadFailed: (adUnitId, error) {
    debugPrint('插屏广告加载失败：${error.code} ${error.message}');
  },
  onAdDisplayed: (ad) {
    debugPrint('插屏广告已展示');
  },
  onAdDisplayFailed: (ad, error) {
    // 这条广告已终止：需要重新请求填充，否则流程到此为止。
    debugPrint('插屏广告展示失败：${error.message}');
    CloudX.loadInterstitial(adUnitId: ad.adUnitId);
  },
  onAdClicked: (ad) {
    debugPrint('插屏广告被点击');
  },
  onAdHidden: (ad) {
    // 此刻刚展示的广告仍被视为展示中，因此先销毁再加载。
    // 下一次加载会创建新的实例并发起新的竞价。
    CloudX.destroyInterstitial(adUnitId: ad.adUnitId);
    CloudX.loadInterstitial(adUnitId: ad.adUnitId);
  },
  onAdRevenuePaid: (ad) {
    debugPrint('收入：${ad.revenue}');
  },
));

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

// 在广告位处：
if (await CloudX.isInterstitialReady(adUnitId: adUnitId)) {
  CloudX.showInterstitial(adUnitId: adUnitId);
  // 也可以为该次展示打标记：
  // CloudX.showInterstitial(
  //   adUnitId: adUnitId,
  //   placement: 'level_complete',
  //   customData: 'level_3',
  // );
} else {
  debugPrint('插屏广告尚未就绪');
}

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

CloudX.destroyInterstitial(adUnitId: adUnitId);

生命周期

请在加载之前设置监听器。没有注册监听器时派发的事件会被丢弃，因此在 loadInterstitial 之后才设置监听器，可能会错过加载结果。

一个监听器服务于所有插屏广告单元。如果多个页面都会加载插屏广告，每个页面都应在自己加载前重新认领监听器，并在回调中读取 ad.adUnitId 以确认事件属于哪个广告位。

请在组件的 dispose() 中销毁广告。展示插屏广告会消耗掉它，因此请在 onAdHidden 中加载下一条，并在该回调中先销毁：这样下一次加载会立即创建新的实例并发起新的竞价。

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

事件

CloudXInterstitialListener 包含以下回调。

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