fast_ads

本地 Flutter 广告封装包，集成 google_mobile_ads，支持 Banner、插屏、激励、原生广告，内置广告池、优先级兜底、重试等高级特性。

A local Flutter ad package based on google_mobile_ads, supporting Banner, Interstitial, Rewarded, and Native ads, with built-in ad pool, fallback, and retry features.

安装 Installation

在主项目 pubspec.yaml 添加依赖：

dependencies:
  fast_ads:
    path: ./fast_ads

Add to your pubspec.yaml:

dependencies:
  fast_ads:
    path: ./fast_ads

初始化 Initialization

建议在 main() 函数中初始化广告 SDK：

import 'package:fast_ads/fast_ads.dart';

void main() async {
  WidgetsFlutterBinding.ensureInitialized();
  await FastAds.initialize();
  runApp(MyApp());
}

import 'package:fast_ads/fast_ads.dart';

FastBannerAd(
  adUnitId: 'ca-app-pub-3940256099942544/6300978111', // Google 测试广告位
  size: AdSize.banner, // 可选，默认 banner
  margin: EdgeInsets.only(bottom: 16), // 可选
)

插屏广告 Interstitial Ad

import 'package:fast_ads/fast_ads.dart';

final ad = FastInterstitialAd(adUnitId: 'ca-app-pub-3940256099942544/1033173712');
ad.load();
ad.show();

激励广告 Rewarded Ad

import 'package:fast_ads/fast_ads.dart';

final ad = FastRewardedAd(adUnitId: 'ca-app-pub-3940256099942544/5224354917');
ad.onUserEarnedReward = (ad, reward) {
  // 用户获得奖励回调
};
ad.load();
ad.show();

原生广告 Native Ad

import 'package:fast_ads/fast_ads.dart';

FastNativeAd(
  adUnitId: 'ca-app-pub-3940256099942544/2247696110',
  size: AdSize(width: 320, height: 150),
  builder: (context, ad) => AdWidget(ad: ad), // 可自定义渲染
)

需在原生端注册 factoryId（如 'adFactoryExample'），详见 google_mobile_ads 文档。

广告池与优先级兜底 Ad Pool & Fallback

  • 支持多实例广告池，自动轮换、过期检测、指数退避重试。
  • 支持 showWithFallback，按优先级依次尝试多种广告类型，最大化填充率。

快速弹窗（优先级兜底）

FastAds.show(
  type: FastAdsType.interstitial, // 首选类型
  priority: [
    FastAdsType.interstitial,
    FastAdsType.rewarded,
    FastAdsType.appOpen,
    FastAdsType.native,
  ],
  onUserEarnedReward: (ad, reward) {
    // 激励广告奖励回调
  },
);

高级用法 Advanced

  • 支持自定义广告池（FastAdPool）、广告对象（FastBaseAd）扩展。
  • 支持多监听（ValueNotifier/ChangeNotifier），可用于广告状态 UI。
  • 内置重试、过期检测、挂起 show 等机制。

支持平台 Supported Platforms

  • Android / iOS
  • Web 端不会显示广告（自动兼容）

依赖 Dependencies

License

MIT

Libraries

fast_ads