adquanta_ads_sdk 1.5.2

AdQuanta Ads SDK for Flutter - 专业的移动广告聚合SDK

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: ^1.0.0

然后运行：

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',
      padding: const EdgeInsets.only(bottom: 12),
      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 广告关闭');
  }
}

AdquantaBanner starts collapsed, reveals itself after a successful load, and collapses itself after a load or show failure. The optional padding is part of the collapsible area, so host applications do not need to manage Banner size or visibility. Listeners are optional and should only observe lifecycle events.

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 文件。

技术支持

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