logo

一款优质的 Flutter 广告插件(腾讯广告、广点通、优量汇)

插件特点

  • 🔨 接入简单快速(封装原生端配置,仅需引入即可开始)
  • 📡 事件统一返回(将原生端各种重要回调事件统一返回,方便业务处理和埋点统计等需求)
  • 🎁 注重优化体验(无闪烁 Logo 开屏、权限申请、隐私跟踪申请等)
  • 🏆 极客代码封装(原生端代码不凑合,两端统一基础框架、广告事件封装抽象、易扩展新广告形式、方便开发个性化需求)

支持功能

下载体验

入门使用

引入依赖

dependencies:
  flutter_qq_ads: ^1.2.0 # 非 Null Safety 版本
  flutter_qq_ads: ^2.2.0 # Null Safety 版本

初始化广告

/// [appId] 应用媒体ID
FlutterQqAds.initAd(appId);

开屏广告

  • 半屏广告 + Logo
/// [posId] 广告位 id
/// [logo] 如果传值则展示底部logo,不传不展示,则全屏展示
/// [fetchDelay] 拉取广告的超时时间,默认值 3 秒,取值范围[1.5~5]秒
FlutterQqAds.showSplashAd(
    AdsConfig.splashId,
    logo: 'flutterads_logo',
    fetchDelay: 3,
  );
FlutterQqAds.showSplashAd(posId);

插屏广告

  • 插屏半屏
/// [posId] 广告位 id
/// [showPopup] Popup 形式显示(仅 Android)
/// [autoPlayOnWifi] 是否仅在 WiFi 网络下自动播放
/// [autoPlayMuted] 自动播放是否静音
/// [detailPageMuted] 详情页是否静音
FlutterQqAds.showInterstitialAd(
    posId,
    showPopup: false,
    autoPlayMuted: false,
    autoPlayOnWifi: false,
    detailPageMuted: false,
  );
  • 插屏全屏视频
/// [posId] 广告位 id
/// [showFullScreenVideo] 插屏全屏视频形式显示
FlutterQqAds.showInterstitialAd(
    posId,
    showFullScreenVideo: true,
  );
  • 插屏激励视频
/// [posId] 广告位 id
/// [showRewardVideo] 插屏激励视频形式显示
/// [customData] 设置服务端验证的自定义信息
/// [userId] 设置服务端验证的用户信息
FlutterQqAds.showInterstitialAd(
    posId,
    showRewardVideo: true,
    customData: 'customData',
    userId: 'userId',
  );

激励视频

/// [posId] 广告位 id
/// [playMuted] 是否静音播放
/// [customData] 设置服务端验证的自定义信息
/// [userId] 设置服务端验证的用户信息
FlutterQqAds.showRewardVideoAd(
    posId,
    playMuted: false,
    customData: 'customData',
    userId: 'userId',
  );
/// [posId] 广告位 id
/// [interval] 广告刷新间隔,0 或[30~120]之间的数字,单位为 s,默认 30s 
///  Android:0 表示不自动轮播 
///  iOS:0 表示关闭轮播动画,因为 iOS 没有不轮播
/// [show] 是否显示广告
AdBannerWidget(
  posId: AdsConfig.bannerId02,
  interval: 120,
  show: true,
)

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

  • 嵌套 AspectRatio (推荐)
AspectRatio(
  aspectRatio: 6.4 / 1, // 6.4:1 的比例
  child: AdBannerWidget(
    posId: AdsConfig.bannerId02,
    interval: 120,
  ),
),
  • 嵌套 SizedBox
SizedBox(
  width: 375,
  height: 100,
  child: AdBannerWidget(
    posId: AdsConfig.bannerId01,
  ),
)
  • 嵌套 Container
Container(
  width: double.infinity,
  height: 80,
  child: AdBannerWidget(
    posId: AdsConfig.bannerId,
    interval: 0,
    show: true,
  ),
)

设置广告事件监听

FlutterQqAds.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 +=
        ' transId:${event.transId} customData:${event.customData} userId:${event.userId}';
  }
  print('onEventListener:$_adEvent');
});

事件列表

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

这里做了统一的抽象,iOS 和 Android 原生 SDK 名称不同,如果觉得对应不上,可以提 Issues(一定要加上 log 截图)

其他配置

信任HTTP请求

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

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

信任HTTP请求

请求应用跟踪透明度授权

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

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

请求应用跟踪透明度授权

  • 效果

预览效果

原生 SDK 版本更新方法

如果是大版本,我会第一时间适配更新,小版本可以自己更新,方法如下:

  • Android

    方法1:可以给我提 Issues 提示我更新,版本号 x.y.z,会更新 z 版本迭代

    方法2:可以自己指定版本,方法如下:

// build.gradle(android.app)
android{
  configurations.all {
      resolutionStrategy {
          force 'com.qq.e.union:union:版本号'
      }
  }
}
  • iOS

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

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

分支说明

分支说明
develop开发分支,接受 PR
master稳定分支,非 Null Safety
2x稳定分支,Null Safety

遇到问题

如果你遇到问题请提 Issues 给我(提问前建议先搜索尝试,没有再提问)

支持开源

支持开源项目最好的方式就是用 1 秒点个免费的 Star

FlutterAds 系列插件

插件描述
flutter_qq_ads腾讯广告、广点通、优量汇 Flutter 广告插件
flutter_pangle_ads字节跳动、穿山甲 Flutter 广告插件
flutter_baidu_ads百度、百青藤 Flutter 广告插件(开发中)

Libraries

ad_banner_widget
ad_error_event
ad_event
ad_event_action
ad_event_handler
ad_reward_event
flutter_qq_ads