入门使用

引入依赖

dependencies:
  flutter_adp_ads_global: ^1.1.0

初始化广告

// 导包
import 'package:flutter_adp_ads_global/flutter_adp_ads_global.dart';
/// [appId] 应用ID
final initialized = await FlutterADPAds.initAd(
  appId,
  onSuccess: () => print('广告 SDK 初始化成功'),
  onError: (error) => print('初始化失败: ${error.code} ${error.message}'),
);

个性化广告开关

/// 不调用默认为开，'1'打开，'0'关闭
FlutterADPAds.setUserExtData(personalAdsType: '1');

开屏广告

  • 全屏
/// [posId] 广告位 id
final loaded = await FlutterADPAds.showSplashAd(
  posId,
  onLoad: () => print('开屏广告加载成功'),
  onError: (error) => print('开屏广告加载失败: ${error.code} ${error.message}'),
  onShow: () => print('开屏广告展示'),
  onClick: () => print('开屏广告点击'),
  onClosed: () => print('开屏广告关闭'),
);
  • 半屏广告 + Logo , 国内版本有，国外版本没有
/// [posId] 广告位 id
/// [logo] 如果传值则展示底部logo，不传不展示，则全屏展示
/// [timeout] 加载超时时间
FlutterADPAds.showSplashAd(
  posId,
  logo: 'flutterads_logo',
  timeout: 3.5,
  onLoad: () => print('开屏广告加载成功'),
  onError: (error) => print('开屏广告加载失败: ${error.message}'),
);

initAd 和 showSplashAd 的 Future<bool> 会在原生 SDK 返回加载结果后完成。开屏的 onLoad、onError、onShow、onClick、onClosed 都绑定到该次调用，不需要依赖全局广告事件监听。

推荐的启动开屏接入方式

SplashAdLoader 会在 Flutter 首帧立刻显示 loadingBuilder，随后初始化 SDK 并请求开屏广告。广告关闭、加载失败或超时后自动进入 child。这避免了等待 SDK 初始化后才出现加载页的白屏问题。

MaterialApp(
  home: SplashAdLoader(
    appId: appId,
    posId: splashPosId,
    loadingBuilder: (context) => const Scaffold(
      body: Center(child: CircularProgressIndicator()),
    ),
    onLoad: () => print('开屏广告加载成功'),
    onError: (error) => print('开屏广告加载失败: ${error.message}'),
    onClosed: () => print('广告关闭，进入首页'),
    child: const HomePage(),
  ),
)

系统 Launch Screen 负责 Flutter 首帧前的静态品牌图，loadingBuilder 负责首帧后的任意 Flutter 加载界面。已有的 showSplashAd() 调用无需修改。

如需在应用从后台回到前台后再次展示开屏广告，配置 hotStartInterval。它记录最近一次实际展示开屏广告的时间：热启动时，距离该时间不足 5 秒则不请求；达到 5 秒则立刻显示加载页并请求广告，不会再额外等待 5 秒。

热启动由原生应用生命周期判断：iOS 以真正的进入后台再回到前台为准，Android 以应用进程生命周期为准；原生激励、插屏等全屏广告造成的 Flutter 页面生命周期变化不会触发开屏。

SplashAdLoader(
  appId: appId,
  posId: splashPosId,
  hotStartInterval: const Duration(seconds: 5),
  child: const HomePage(),
)

插屏广告

/// 加载插屏广告
/// [posId] 广告位 id
FlutterADPAds.loadInterstitialAd(AdsConfig.newInterstitialId);

/// 显示插屏广告
FlutterADPAds.showInterstitialAd();

激励视频

/// 加载激励广告
/// [posId] 广告位 id
/// [customData] 设置服务端验证的自定义信息
/// [userId] 设置服务端验证的用户信息
FlutterADPAds.loadRewardVideoAd(
    AdsConfig.rewardVideoId,
    customData: 'customData',
    userId: 'userId',
);

/// 展示激励广告
FlutterADPAds.showRewardVideoAd();




/// [posId] 广告位 id
/// [width] 创建 Banner 广告位时选择的宽度，默认值是 300
/// [height] 创建 Banner 广告位时选择的高度，默认值是 150
/// [interval] 广告轮播间隔，0 或[30~120]之间的数字，单位为 s,默认为 0 不轮播
/// [show] 是否显示广告
/// [autoClose] 是否自动关闭，一般是在用户点击不感兴趣之后的操作
AdBannerWidget(
  posId: AdsConfig.bannerId,
  width: 300,
  height: 150,
  interval: 30,
  show: true,
  autoClose: true,
);

Banner 广告外部需要嵌套一个带有约束布局的 Widget，如：AspectRatio、SizedBox、Container 等，示例如下：

  • 嵌套 SizedBox (推荐)
SizedBox(
  width: 300,
  height: 150,
  child: AdBannerWidget(
    posId: AdsConfig.bannerId,
    width: 300,
    height: 150,
    interval: 30,
    show: true,
  ),
)

信息流

  • 获取信息流广告列表
/// [posId] 广告位 id
/// [width] 宽度
/// [height] 高度
/// [count] 获取广告数量，建议 1~3 个
List<int> feedAdList = await FlutterADPAds.loadFeedAd(
    AdsConfig.feedId,
    width: 375,
    height: 128,
    count: 3,
  );
  • 清除信息流广告列表

当你的广告不再需要时，请一定执行清除操作

/// [list] 信息流广告 id 列表
bool result = await FlutterADPAds.clearFeedAd(feedAdList);
  • 页面中展示信息流广告
/// Feed 信息流广告组件
/// [posId]返回的广告 id，这里不是广告位id
/// [width]组件的宽度
/// [height]组件的高度
/// [show]是否显示
AdFeedWidget(
    posId: '${feedAdList[0]}',
    width: 375,
    height: 128,
    show: true,
  )

width 和 height 需要根据你新建广告位的模板来设置

设置广告事件监听

FlutterADPAds.onEventListener((event) {
  // 普通广告事件
  String _adEvent = 'adId:${event.adId} action:${event.action}';
  if (event is AdErrorEvent) {
    // 错误事件
    _adEvent += ' errCode:${event.errCode} errMsg:${event.errMsg}';
  } else if (event is AdRewardEvent) {
    // 激励事件
        _adEvent +=
            'rewardType:${event.rewardType} rewardVerify:${event.rewardVerify} rewardAmount:${event.rewardAmount} rewardName:${event.rewardName} errCode:${event.errCode} errMsg:${event.errMsg} customData:${event.customData} userId:${event.userId}';
  }
  // 测试关闭 Banner（会员场景）
  if (event.action == AdEventAction.onAdClosed &&
      event.adId == AdsConfig.bannerId02) {
    _adEvent += '仅会员可以关闭广告';
  }
  print('onEventListener:$_adEvent');
});

事件列表

事件 说明
onAdLoaded 广告加载成功
onAdPresent 广告填充
onAdExposure 广告曝光
onAdClosed 广告关闭（开屏计时结束或者用户点击关闭）
onAdClicked 广告点击
onAdSkip 广告跳过
onAdComplete 广告播放或计时完毕
onAdError 广告错误
onAdReward 获得广告激励

其他配置

iOS

信任HTTP请求（

苹果公司在iOS9中升级了应用网络通信安全策略，默认推荐开发者使用HTTPS协议来进行网络通信，并限制HTTP协议的请求。为了避免出现无法拉取到广告的情况，我们推荐开发者在info.plist文件中增加如下配置来实现广告的网络访问

  • 修改 info.plist
<key>NSAppTransportSecurity</key>
<dict>
  <key>NSAllowsArbitraryLoads</key>
  <true/>
</dict>

请求应用跟踪透明度授权

此步骤必须要做，不然上架审核时候会被拒绝

bool result = await FlutterADPAds.requestIDFA;
  • 修改 info.plist
<key>NSUserTrackingUsageDescription</key>
<string>为了向您提供更优质、安全的个性化服务及内容，需要您允许使用相关权限</string>

GADApplicationIdentifier

修改 info.plist

<key>GADApplicationIdentifier</key>
<string>ca-app-pub-5297446075011848~6893150522</string>

其他配置

Android

修改AndroidManifest.xml文件

增加以下节点，具体值需要开通正式广告位

<meta-data
            android:name="com.google.android.gms.ads.APPLICATION_ID"
            android:value="ca-app-pub-3940256099942544~3347511713"/>

 <meta-data
            android:name="applovin.sdk.key"
     android:value="wfF4UGRbFrkIyf_QaZ4__2uqlp8u6bw07FpTU11IKKTomQTTgZJ3xv8y_T2NuZhel6otTSW9lehHq9MT1tddBR" />

混淆

请参考原生说明第5部分

原生 SDK 版本更新方法

  • Android
// build.gradle(android.app)
android{
  configurations.all {
      resolutionStrategy {
          
      }
  }
}

  • iOS

    自己手动更新，自己的项目根目录下执行即可

// 可在 ios/Podfile.lock 中查看 SDK 当前版本
cd ios
rm -rf Podfile.lock
pod repo update
pod install

Libraries

event/ad_error_event
event/ad_event
event/ad_event_action
event/ad_event_handler
event/ad_request_error
event/ad_reward_event
flutter_adp_ads_global
main
options/network_type
view/ad_banner_widget
view/splash_ad_loader