AdQuanta Ads SDK for Flutter

AdQuanta Ads SDK 是一个功能强大的移动广告聚合SDK，支持多种广告形式，帮助开发者轻松集成广告功能，实现收益最大化。

功能特性

  • ✅ 多种广告形式：支持 Banner、Splash、Rewarded 等多种广告类型
  • ✅ 统一API接口：提供简洁统一的API，降低集成复杂度
  • ✅ 跨平台支持：同时支持 iOS 和 Android 平台
  • ✅ 完善的回调：提供完整的广告生命周期回调，便于业务处理
  • ✅ 隐私合规：支持GDPR、CCPA等隐私合规配置

系统要求

  • Flutter 3.3.0 或更高版本
  • iOS 14.0 或更高版本
  • Android API Level 24 (Android 7.0) 或更高版本

安装

在您的 pubspec.yaml 文件中添加依赖：

dependencies:
  adquanta_ads_sdk: ^0.0.1

然后运行：

flutter pub get

快速开始

1. 初始化 SDK

在应用启动时初始化 SDK（建议在 main() 函数中）：

import 'package:adquanta_ads_sdk/adquanta_ads_sdk.dart';

void main() async {
  WidgetsFlutterBinding.ensureInitialized();
  
  // 初始化 AdQuanta SDK
  await AdquantaSdk.init(appId: 'YOUR_APP_ID');
  
  runApp(MyApp());
}

2. 使用 Banner 广告

import 'package:adquanta_ads_sdk/adquanta_ads_sdk.dart';

class MyBannerWidget extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return AdquantaBanner(
      adUnitId: 'YOUR_BANNER_AD_UNIT_ID',
      width: 320,
      height: 50,
      listener: MyBannerListener(),
    );
  }
}

class MyBannerListener extends AdquantaBannerListener {
  @override
  void onAdLoaded(AdquantaAdInfo adInfo) {
    print('Banner 广告加载成功: ${adInfo.adSourceName}');
  }

  @override
  void onAdLoadFailed(AdquantaAdError error) {
    print('Banner 广告加载失败: ${error.message}');
  }

  @override
  void onAdClicked(AdquantaAdInfo adInfo) {
    print('Banner 广告被点击');
  }

  @override
  void onAdImpression(AdquantaAdInfo adInfo) {
    print('Banner 广告展示成功');
  }

  @override
  void onAdClosed(AdquantaAdInfo adInfo) {
    print('Banner 广告关闭');
  }
}

3. 使用 Splash 开屏广告

import 'package:adquanta_ads_sdk/adquanta_ads_sdk.dart';

class SplashScreen extends StatefulWidget {
  @override
  _SplashScreenState createState() => _SplashScreenState();
}

class _SplashScreenState extends State<SplashScreen> {
  late AdquantaSplash _splashAd;

  @override
  void initState() {
    super.initState();
    _splashAd = AdquantaSplash(
      adUnitId: 'YOUR_SPLASH_AD_UNIT_ID',
      listener: MySplashListener(),
    );
    _splashAd.loadAd();
  }

  @override
  void dispose() {
    _splashAd.dispose();
    super.dispose();
  }

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      body: Container(
        child: Center(child: CircularProgressIndicator()),
      ),
    );
  }
}

class MySplashListener extends AdquantaSplashListener {
  @override
  void onAdLoaded(AdquantaAdInfo adInfo) {
    // 广告加载成功，显示开屏广告
    // 注意：实际的显示逻辑需要在 Flutter 端处理
    print('Splash 广告加载成功');
  }

  @override
  void onAdLoadFailed(AdquantaAdError error) {
    // 广告加载失败，跳转到主界面
    print('Splash 广告加载失败: ${error.message}');
  }

  @override
  void onAdClosed(AdquantaAdInfo adInfo) {
    // 广告关闭，跳转到主界面
    print('Splash 广告关闭');
  }

  @override
  void onAdClicked(AdquantaAdInfo adInfo) {
    print('Splash 广告被点击');
  }

  @override
  void onAdImpression(AdquantaAdInfo adInfo) {
    print('Splash 广告展示成功');
  }
}

4. 使用 Rewarded 激励视频广告

import 'package:adquanta_ads_sdk/adquanta_ads_sdk.dart';

class RewardedAdExample extends StatefulWidget {
  @override
  _RewardedAdExampleState createState() => _RewardedAdExampleState();
}

class _RewardedAdExampleState extends State<RewardedAdExample> {
  late AdquantaRewarded _rewardedAd;

  @override
  void initState() {
    super.initState();
    _rewardedAd = AdquantaRewarded(
      adUnitId: 'YOUR_REWARDED_AD_UNIT_ID',
      listener: MyRewardedListener(),
    );
    _rewardedAd.loadAd();
  }

  Future<void> _showRewardedAd() async {
    final isReady = await _rewardedAd.isReady();
    if (isReady) {
      await _rewardedAd.showAd();
    } else {
      print('Rewarded 广告还未准备好');
    }
  }

  @override
  void dispose() {
    _rewardedAd.dispose();
    super.dispose();
  }

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(title: Text('激励视频广告')),
      body: Center(
        child: ElevatedButton(
          onPressed: _showRewardedAd,
          child: Text('观看视频获得奖励'),
        ),
      ),
    );
  }
}

class MyRewardedListener extends AdquantaRewardedListener {
  @override
  void onAdLoaded(AdquantaAdInfo adInfo) {
    print('Rewarded 广告加载成功');
  }

  @override
  void onAdLoadFailed(AdquantaAdError error) {
    print('Rewarded 广告加载失败: ${error.message}');
  }

  @override
  void onAdReward(AdquantaAdInfo adInfo) {
    print('获得奖励: ${adInfo.currencyName} ${adInfo.amount}');
    // 在这里处理奖励逻辑
  }

  @override
  void onAdClosed(AdquantaAdInfo adInfo) {
    print('Rewarded 广告关闭');
    // 可以重新加载广告
  }

  @override
  void onAdClicked(AdquantaAdInfo adInfo) {
    print('Rewarded 广告被点击');
  }

  @override
  void onAdImpression(AdquantaAdInfo adInfo) {
    print('Rewarded 广告展示成功');
  }

  @override
  void onAdVideoStart(AdquantaAdInfo adInfo) {
    print('视频开始播放');
  }

  @override
  void onAdVideoEnd(AdquantaAdInfo adInfo) {
    print('视频播放结束');
  }

  @override
  void onAdVideoError(AdquantaAdInfo adInfo, AdquantaAdError error) {
    print('视频播放错误: ${error.message}');
  }
}

API 参考

AdquantaSdk

SDK 主类，用于初始化和配置。

方法

  • init({required String appId}) - 初始化 SDK
  • setLogLevel(int level) - 设置日志级别 (0=关闭, 1=错误, 2=警告, 3=信息, 4=调试)
  • setGDPRDataCollection(bool canDataCollection) - 设置 GDPR 数据收集
  • setCCPADoNotSell(bool doNotSell) - 设置 CCPA 不销售数据
  • setCOPPAIsAgeRestrictedUser(bool isAgeRestrictedUser) - 设置 COPPA 年龄限制
  • setLGPDIsConsentEnabled(bool isConsentEnabled) - 设置 LGPD 同意状态
  • setDevAllowTracking(bool allowTracking) - 设置是否允许追踪

AdquantaBanner

Banner 广告类，是一个 Widget。

属性

  • adUnitId - 广告单元 ID
  • listener - 广告监听器
  • width - Banner 宽度（可选）
  • height - Banner 高度（可选，默认 50）

方法

  • loadAd({String? sceneId}) - 加载广告
  • showAd({String? sceneId}) - 显示广告

AdquantaSplash

Splash 开屏广告类。

方法

  • loadAd({double? bottomViewHeight}) - 加载广告
  • showAd() - 显示广告
  • dispose() - 销毁广告实例

AdquantaRewarded

Rewarded 激励视频广告类。

方法

  • loadAd() - 加载广告
  • showAd({String? sceneId}) - 显示广告
  • isReady() - 检查广告是否已准备好
  • dispose() - 销毁广告实例

隐私合规配置

GDPR（欧盟）

await AdquantaSdk.setGDPRDataCollection(true);  // 用户同意
// 或
await AdquantaSdk.setGDPRDataCollection(false); // 用户拒绝

CCPA（加州）

await AdquantaSdk.setCCPADoNotSell(false);  // 允许销售数据
// 或
await AdquantaSdk.setCCPADoNotSell(true);   // 不销售数据

常见问题

1. 广告无法加载

  • 检查 App ID 和 Ad Unit ID 是否正确
  • 确保网络连接正常
  • 确认在应用启动时调用了 AdquantaSdk.init()

2. Banner 广告不显示

  • 确保 Banner Widget 已添加到 Widget 树中
  • 检查广告尺寸设置是否正确
  • 确保容器有足够的空间显示广告

3. Rewarded 广告无法显示

  • 在显示前使用 isReady() 检查广告是否已准备好
  • 确保广告加载完成后再调用 showAd()

更新日志

Version 0.0.1

  • 初始版本发布
  • 支持 Banner、Splash、Rewarded 广告
  • 支持 iOS 和 Android 平台
  • 提供统一的 API 接口

许可证

本项目采用 GPL-3.0 许可证，详见 LICENSE 文件。

技术支持

如有问题或建议，请联系技术支持团队：[email protected]

Libraries

adquanta_ads_sdk
adquanta_ads_sdk_method_channel
adquanta_ads_sdk_platform_interface