deepadx_sdk 0.1.0

DeepAdx Flutter 聚合广告 SDK，支持开屏、插屏、激励视频、原生（信息流）、横幅五种广告形态， 基于原生聚合 SDK 封装，提供统一的 Dart 侧 API。

DeepAdx Flutter SDK

DeepAdx 聚合广告 Flutter 插件，基于 deepadx-android 与 deepadx-ios 原生聚合 SDK 封装，提供统一的 Dart 侧 API。

支持广告形态：

形态	Dart API	说明
开屏	DeepAdxSplashView / DeepAdxSplash	PlatformView 全屏容器承载
插屏	DeepAdxInterstitial	无视图，全屏展示
激励视频	DeepAdxRewardVideo	无视图，全屏展示，含奖励回调
原生信息流	DeepAdxNativeExpressView / DeepAdxNativeExpress	PlatformView 容器承载
横幅	DeepAdxBannerView / DeepAdxBanner	PlatformView 容器承载

目录结构

deepadx-flutter-sdk/
├── lib/                     # Dart API
│   └── src/
│       ├── deepadx_sdk.dart        # 初始化入口 DeepAdxFlutterSdk
│       ├── ads/                    # 5 种广告控制器（基类 DeepAdxAd）
│       ├── widgets/                # PlatformView 组件（开屏/横幅/原生）
│       ├── models/                 # DeepAdxError / 日志级别 / 奖励信息
│       └── internal/               # channel 协议
├── android/                 # Android 桥接（Java）
│   └── src/main/java/com/deepadx/flutter_sdk/
│       ├── DeepAdxFlutterSdkPlugin.java   # 全局 channel + 工厂注册
│       ├── AdSession.java                 # 会话基类（事件回传）
│       ├── *AdSession.java                # 5 种广告会话
│       └── DeepAdxContainerViewFactory.java
├── ios/Classes/             # iOS 桥接（Swift）
│   ├── DeepAdxFlutterSdkPlugin.swift
│   ├── DeepAdxAdSession.swift
│   ├── DeepAdxAdSessions.swift           # 5 种广告会话（实现原生 delegate）
│   └── DeepAdxContainerViewFactory.swift
├── example/                 # 示例应用（含 android/ios 平台工程）
│   ├── INTEGRATION.md                   # 完整对接文档
│   └── lib/main.dart                     # 五种广告演示
└── sh/
    ├── publish-android-local.sh  # 发布 deepadx-android 到 mavenLocal
    └── publish-flutter-sdk.sh   # 发布 deepadx_sdk 到 pub.dev

详细对接文档见 example/INTEGRATION.md （集成配置、各广告形态完整代码、事件回调表、错误码、平台差异、FAQ）

快速接入

1. 初始化

void main() async {
  WidgetsFlutterBinding.ensureInitialized();
  // 双端后台应用分开注册（包名/BundleID 不同），各自 AppID
  await DeepAdxFlutterSdk.init(
    androidAppId: '你的 Android AppID',
    iosAppId: '你的 iOS AppID',
    // appId: '通用 AppID',  // 双端相同时可只传 appId
  );
  await DeepAdxFlutterSdk.setDebug(true, logLevel: DeepAdxLogLevel.simple);
  runApp(const MyApp());
}

2. 开屏

bool _showSplash = true;

Stack(children: [
  YourHomePage(),
  if (_showSplash)
    Positioned.fill(
      child: DeepAdxSplashView(
        ad: DeepAdxSplash(
          placementId: '开屏广告位ID',
          onSucceed: () => print('加载成功'),
          onFailed: (e) => setState(() => _showSplash = false),
          onClose: () => setState(() => _showSplash = false), // 跳过/倒计时结束/关闭
        ),
      ),
    ),
]);

3. 插屏 / 激励视频

final ad = DeepAdxInterstitial(
  placementId: '插屏广告位ID',
  onSucceed: () => print('加载成功'),
  onFailed: (e) => print('失败 $e'),
  onClose: () => ad.destroy(),
);
await ad.loadAndShow();

final ad = DeepAdxRewardVideo(
  placementId: '激励广告位ID',
  userId: 'user_123',
  rewardName: '金币',
  rewardAmount: 100,
  onReward: () => 发放奖励,
  onFailed: (e) => print('失败 $e'),
);
await ad.loadAndShow();

4. 横幅 / 原生信息流

DeepAdxBannerView(
  ad: DeepAdxBanner(
    placementId: '横幅广告位ID',
    onSucceed: () => print('加载成功'),
    onFailed: (e) => print('失败 $e'),
  ),
  width: 320,
  height: 50,
)

DeepAdxNativeExpressView(
  ad: DeepAdxNativeExpress(
    placementId: '原生广告位ID',
    onSucceed: () => print('加载成功'),
    onRenderSuccess: () => print('渲染成功'),
    onFailed: (e) => print('失败 $e'),
  ),
  width: 350,
)

原生依赖配置

Android

插件依赖 com.deepadx.sdk:deepadx-core（默认版本 2.1.6，可在宿主 gradle.properties 中用 deepadx.version 覆盖）。

# 1. 将 deepadx-android 发布到 mavenLocal
sh/publish-android-local.sh

# 2. 按需在宿主 App 的 build.gradle 添加渠道适配器，例如：
implementation "com.deepadx.sdk:deepadx-adapter-csj:2.1.6"
implementation "com.deepadx.sdk:deepadx-adapter-ylh:2.1.6"
implementation "com.deepadx.sdk:deepadx-adapter-bd:2.1.6"
implementation "com.deepadx.sdk:deepadx-adapter-ks:2.1.6"
implementation "com.deepadx.sdk:deepadx-adapter-admob:2.1.6"
implementation "com.deepadx.sdk:deepadx-adapter-pag:2.1.6"

iOS

插件 podspec 依赖 DeepAdxSDK/Core（含 DeepAdxCore + DeepAdxAdspot xcframework）， 已声明 static_framework = true 以兼容 DeepAdxSDK 静态 xcframework。 按需在宿主 Podfile 中追加渠道 subspec（如 DeepAdxSDK/CSJ、DeepAdxSDK/GG）：

target 'Runner' do
  flutter_install_all_ios_pods File.dirname(File.realpath(__FILE__))
  pod 'DeepAdxSDK/CSJ'   # 穿山甲
  pod 'DeepAdxSDK/GG'    # Google AdMob
  # ...其他渠道 subspec
end

事件语义（双端对齐）

事件	说明
onAdSucceed / onAdFailed	加载成功/失败（DeepAdxError.code 为 2000–2017 聚合层错误码）
onAdExposure / onAdClicked	曝光 / 点击
onAdClose	广告关闭；开屏跳过/倒计时结束在双端均以 onAdClose 收尾
onAdSkip / onAdCountdownToZero	仅 iOS 透出，作为 onAdClose 前的补充信息
激励：onVideoCached / onVideoComplete / onVideoSkip / onAdReward	视频缓存完成/播放完成/跳过/奖励生效
激励：onRewardServerInf	服务端奖励回调（仅 Android 穿山甲/百度）
原生：onRenderSuccess / onRenderFailed	模板渲染成功/失败

设计说明

• 命令/事件分离：Dart → 原生命令统一走全局 channel（携带 instanceId）， 原生 → Dart 事件走每实例 channel，彻底规避 channel 注册时序竞态；
• 实例生命周期：Dart 侧 DeepAdxAd 构造即绑定事件 channel， destroy() 幂等，视图组件 dispose 时自动销毁原生实例；
• 视图类广告：PlatformView 工厂以 instanceId 注册容器， 视图创建完成后 Dart 发起 create，原生将容器绑定到广告实例；
• 错误码统一：双端对齐 2000–2017 聚合层错误码，DeepAdxError 统一建模。

版本

组件	版本
deepadx_sdk	0.1.0
deepadx-android	2.1.6
DeepAdxSDK (iOS)	2.0.5

编译验证

验证项	结果
flutter analyze	0 issues
flutter build apk --debug	✓ 构建成功
flutter build ios --debug --no-codesign	✓ 构建成功

发布

发布 Flutter 插件到 pub.dev

# 1. dry-run 验证（版本一致性 / CHANGELOG / analyze / publish dry-run）
sh/publish-flutter-sdk.sh

# 2. 实际发布并打 git tag
sh/publish-flutter-sdk.sh --publish

发布前需移除 pubspec.yaml 中的 publish_to: none。 脚本会自动校验 pubspec / podspec / build.gradle 三处版本号一致。