Skip to content

Flutter 接入 ​

本文面向 Flutter 应用,说明 DeepAdx Flutter SDK 的 pub.dev 集成、初始化、五种广告形态的调用方式、事件回调与常见问题。

本文对应 SDK 版本:deepadx_sdk: ^1.0.3(Flutter Plugin,基于 deepadx-android 2.1.8 + DeepAdxSDK(iOS) 2.0.6 封装)


1. 支持的广告形态 ​

形态Dart 控制器视图组件说明
开屏DeepAdxSplashDeepAdxSplashViewPlatformView 全屏容器承载,冷启展示
插屏DeepAdxInterstitial—无视图组件,直接全屏覆盖展示
激励视频DeepAdxRewardVideo—无视图组件,全屏展示 + 服务端奖励校验
横幅DeepAdxBannerDeepAdxBannerViewPlatformView 固定尺寸容器承载
原生信息流DeepAdxNativeExpressDeepAdxNativeExpressViewPlatformView 容器,支持动态高度自适应

2. 环境要求 ​

项最低要求验证版本
Flutter SDK≥ 3.10.03.44.x
Dart≥ 3.0.03.5+
Android minSdk24—
Android compileSdk36—
iOS 最低系统版本12.0(示例工程可设为 13.0)—
deepadx-android 聚合核心—2.1.8(自动引入)
DeepAdxSDK(iOS) 聚合核心—2.0.6(自动引入)

3. 集成配置 ​

3.1 pub.dev 引入 ​

在 Flutter 工程的 pubspec.yaml 中添加:

yaml
dependencies:
  flutter:
    sdk: flutter
  deepadx_sdk: ^1.0.3

或直接命令行:

bash
flutter pub add deepadx_sdk

插件会自动桥接原生聚合核心(Android Maven deepadx-core + iOS CocoaPods DeepAdxSDK/Core)。 渠道适配器(CSJ、GDT 等)需在宿主工程中按需成对引入,见下文 3.2 / 3.3。


3.2 Android 端配置 ​

3.2.1 仓库配置 ​

在宿主工程根目录的 settings.gradle.kts(或老版本 build.gradle 的 allprojects.repositories)中添加 DeepAdx Maven 仓库及渠道源:

kotlin
dependencyResolutionManagement {
    repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
    repositories {
        google()
        mavenCentral()
        maven(url = "https://maven.deepadx.com/repository/maven-releases/")   // DeepAdx
        maven(url = "https://maven.aliyun.com/repository/public/")          // 可选:阿里云镜像
        maven(url = "https://artifact.bytedance.com/repository/pangle")     // CSJ(国内/海外)
        maven(url = "https://jitpack.io")                                   // KS 等渠道
    }
}

3.2.2 minSdk 与渠道依赖 ​

在宿主 App 的 android/app/build.gradle.kts 中:

kotlin
android {
    defaultConfig {
        minSdk = 24                          // deepadx-core 硬性要求
        // targetSdk / compileSdk 建议 ≥ 34
    }
}

// 渠道适配器与三方 SDK 必须成对引入;按实际渠道删减
dependencies {
    val sdkVer = "2.1.8"

    // ===== 国内:CSJ / GDT / BD / KS =====
    implementation("com.deepadx.sdk:deepadx-adapter-csj:$sdkVer")
    implementation("com.pangle_beta.cn:mediation-sdk:7.4.1.4")
    implementation("com.deepadx.sdk:deepadx-adapter-gdt:$sdkVer")
    implementation("com.deepadx.thirdparty:gdt-union-normal:4.640.1510")
    implementation("com.deepadx.sdk:deepadx-adapter-bd:$sdkVer")
    implementation("com.deepadx.thirdparty:baidu-mobads-sdk:9.432")
    implementation("com.deepadx.sdk:deepadx-adapter-ks:$sdkVer")
    implementation("com.deepadx.thirdparty:kssdk-ad:5.1.20.1")

    // ===== 海外:GG / PAG(与 CSJ 二选一)=====
    // implementation("com.deepadx.sdk:deepadx-adapter-gg:$sdkVer")
    // implementation("com.google.android.gms:play-services-ads:24.9.0")
    // implementation("com.deepadx.sdk:deepadx-adapter-pag:$sdkVer")
    // implementation("com.pangle.global:ads-sdk:6.5.1.2")
}

CSJ 国内(csj)与海外 PAG(pag)不可在同一 build 中同时引入,二者互斥。 可在宿主 gradle.properties 用 deepadx.version=2.1.8 覆盖插件默认 Android 原生版本。

官方 example 已拆 Flavor:flutter run --flavor china(国内)/ flutter run --flavor global(海外)。海外包名带 .global 后缀,可与国内包同时安装。

3.2.3 AndroidManifest ​

若宿主集成 CSJ 渠道,注意以下两点(示例工程已处理):

  1. 因 CSJ 7.x 的 mediation-sdk 移除了旧版 TTFileProvider,若你在 AndroidManifest.xml 的 <application> 中声明过 com.bytedance.sdk.openadsdk.TTFileProvider,请用 tools:node="remove" 移除。
  2. 打开 Jetifier(gradle.properties 中 android.enableJetifier=true)。

3.3 iOS 端配置 ​

Flutter 插件的 deepadx_sdk.podspec 已声明依赖 DeepAdxSDK/Core,pod install 会自动拉取。 渠道适配器通过 subspec 方式在宿主 Podfile 中按需追加:

ruby
target 'Runner' do
  flutter_install_all_ios_pods File.dirname(File.realpath(__FILE__))

  # 国内:CSJ / GDT / KS / BD
  pod 'DeepAdxSDK/CSJ'
  pod 'DeepAdxSDK/GDT'
  pod 'DeepAdxSDK/KS'
  pod 'DeepAdxSDK/BD'
  # 海外:GG / PAG(iOS 可与 CSJ 同时接入;官方 example 已全部引入)
  pod 'DeepAdxSDK/GG'
  pod 'DeepAdxSDK/PAG'
end

3.3.1 Info.plist 配置 ​

在 ios/Runner/Info.plist 的 Source Code 视图中添加:

xml
<!-- iOS 14+ IDFA / ATT 权限 -->
<key>NSUserTrackingUsageDescription</key>
<string>用于提升广告个性化推荐与投放效果</string>

<!-- ATS(建议按示例工程完整配置) -->
<key>NSAppTransportSecurity</key>
<dict>
    <key>NSAllowsArbitraryLoads</key>
    <true/>
</dict>

<!-- 若接入 Google AdMob: -->
<!--
<key>GADApplicationIdentifier</key>
<string>你的 AdMob AppID</string>
-->

<!-- SKAdNetwork 归因:各渠道会在 subspec 中自动注入;
     建议按示例工程的 Info.plist 打开 SKAdNetworkItems,避免漏配影响归因 -->

完成后执行:

bash
cd ios
rm -rf Podfile.lock Pods
flutter clean && flutter pub get
pod install --repo-update

4. SDK 初始化 ​

在 main() 中、runApp() 之前调用 DeepAdxFlutterSdk.init()。 DeepAdx 后台的应用分 Android / iOS 分别注册(包名 / BundleID 不同,AppID 也不同),各自传入对应参数;双端共用同一 AppID 时可仅传 appId。

dart
import 'package:flutter/material.dart';
import 'package:deepadx_sdk/deepadx_sdk.dart';

void main() async {
  WidgetsFlutterBinding.ensureInitialized();

  // 1. 初始化聚合 SDK
  final initResult = await DeepAdxFlutterSdk.init(
    androidAppId: '你的 Android AppID',
    iosAppId: '你的 iOS AppID',
    // appId: '若双端 AppID 相同,可只传该字段作为回退',
  );
  if (!initResult.success) {
    // 初始化失败时 error 非空;code 为 2000–2017 聚合层错误码
    debugPrint('[DeepAdx] 初始化失败: ${initResult.error}');
  }

  // 2. 开发阶段:开启日志(生产环境设为 false)
  await DeepAdxFlutterSdk.setDebug(
    true,
    logLevel: DeepAdxLogLevel.simple,
  );

  // 3. 可选:Android 专属开发者模式(打印更详细日志)
  await DeepAdxFlutterSdk.openDev(true);

  // 4. 海外广告全局静音 / 音量(可选;未调用不干预渠道默认声音)
  // await DeepAdxFlutterSdk.setAdMuted(true);
  // await DeepAdxFlutterSdk.setAdVolume(0);
  await DeepAdxFlutterSdk.setAdMuted(false);
  await DeepAdxFlutterSdk.setAdVolume(1);

  runApp(const MyApp());
}

4.1 全局方法 ​

方法返回值说明
DeepAdxFlutterSdk.init({appId, androidAppId, iosAppId})Future<DeepAdxInitResult>初始化聚合 SDK,success=false 时 error 非空
DeepAdxFlutterSdk.sdkVersion()Future<String>原生聚合 SDK 版本号
DeepAdxFlutterSdk.setDebug(bool, {DeepAdxLogLevel logLevel})Future<void>开关调试模式及日志级别
DeepAdxFlutterSdk.openDev(bool)Future<void>Android 专属开发者模式
DeepAdxFlutterSdk.setAdMuted(bool)Future<void>海外广告全局静音;可在 init 前后调用
DeepAdxFlutterSdk.setAdVolume(double)Future<void>海外广告相对音量 0.0~1.0;与静音相互独立

4.2 DeepAdxLogLevel 枚举 ​

与原生数值对齐:

枚举值数值说明
DeepAdxLogLevel.none0不打印任何日志
DeepAdxLogLevel.defaultLevel1核心方法日志(默认)
DeepAdxLogLevel.simple2适合一般接入查看
DeepAdxLogLevel.high3详细执行信息
DeepAdxLogLevel.max10全部信息
DeepAdxLogLevel.custom-1自定义

5. 广告形态接入 ​

广告位 ID 双端独立:DeepAdx 后台的广告位同样按平台注册(Android / iOS 各自独立的 placementId)。 实际接入可用 Platform.isAndroid ? androidId : iosId 选择对应 ID。

5.1 生命周期方法(所有形态通用) ​

方法说明
loadOnly()仅拉取广告素材、不展示;完成后通过 onSucceed 通知
loadAndShow()加载并立即展示(最常用)
show()展示已通过 loadOnly() 预加载的广告
destroy()销毁实例(幂等)。插屏 / 激励在使用完须手动调用;开屏 / 横幅 / 原生 由视图 dispose 自动销毁

5.2 开屏广告 ​

使用 DeepAdxSplashView(PlatformView 全屏承载)。典型场景:在应用首页覆盖一层全屏容器,onClose 回调中移除该视图。

dart
bool _showSplash = true;

@override
Widget build(BuildContext context) {
  return Stack(
    children: [
      const HomePage(),
      if (_showSplash)
        Positioned.fill(
          child: DeepAdxSplashView(
            autoLoad: true,   // 视图创建后自动 loadAndShow;false 则手动调用
            ad: DeepAdxSplash(
              placementId: Platform.isAndroid ? '安卓开屏位ID' : 'iOS开屏位ID',
              showAsExpress: false,  // CSJ 是否模板样式,仅 Android
              timeout: 5,            // 总超时秒,仅 iOS(0=SDK默认)
              onSucceed: () => debugPrint('[开屏] 加载成功'),
              onFailed: (err) {
                debugPrint('[开屏] 加载失败 $err');
                setState(() => _showSplash = false);
              },
              onExposure: () => debugPrint('[开屏] 曝光'),
              onClicked:  () => debugPrint('[开屏] 点击'),
              onClose:    () => setState(() => _showSplash = false),
              // 以下两个仅 iOS 原生透出(Android 只有 onClose)
              onSkip:              () => debugPrint('[开屏] 点击跳过'),
              onCountdownToZero:   () => debugPrint('[开屏] 倒计时结束'),
            ),
          ),
        ),
    ],
  );
}

Android 语义:跳过 / 倒计时结束 / 关闭统一回调 onClose,不会单独回调 onSkip / onCountdownToZero。


5.3 插屏广告 ​

无视图组件,直接 loadAndShow() 全屏展示。使用完毕手动 destroy()。

dart
void showInterstitial() async {
  final ad = DeepAdxInterstitial(
    placementId: '插屏广告位ID',
    onSucceed:  () => debugPrint('[插屏] 加载成功'),
    onFailed:   (e) => debugPrint('[插屏] 加载失败 $e'),
    onExposure: () => debugPrint('[插屏] 曝光'),
    onClicked:  () => debugPrint('[插屏] 点击'),
    onClose: () {
      debugPrint('[插屏] 关闭');
      ad.destroy();  // 关闭后务必销毁
    },
  );
  await ad.loadAndShow();
}

5.4 激励视频 ​

激励视频在全屏播放完成后,通过 onReward 回调触发奖励发放。建议仅在 onReward 里发放奖励,而不是 onVideoComplete。

dart
void showReward() async {
  final ad = DeepAdxRewardVideo(
    placementId: '激励广告位ID',
    userId:       'user_123',          // 透传到服务端奖励回调的用户ID
    rewardName:   '金币',              // 奖励名称(CSJ)
    rewardAmount: 100,                 // 奖励数量
    orientation:  DeepAdxRewardOrientation.vertical,  // 竖屏
    mute:         true,                // 默认静音
    extra:        'roomId=1001',       // 自定义字段,服务端透传
    onSucceed:  () => debugPrint('[激励] 加载成功'),
    onFailed:   (e) => debugPrint('[激励] 加载失败 $e'),
    onExposure: () => debugPrint('[激励] 曝光'),
    onClicked:  () => debugPrint('[激励] 点击'),
    onClose: () {
      ad.destroy();
    },
    onVideoCached:   () => debugPrint('[激励] 视频缓存完成'),
    onVideoComplete: () => debugPrint('[激励] 视频播放完成'),
    onVideoSkip:     () => debugPrint('[激励] 用户跳过视频'),
    onReward: () {
      debugPrint('[激励] 奖励生效 → 发放金币 100');
    },
    onRewardServerInf: (inf) {
      // 仅 Android CSJ/BD 会回传服务端校验信息
      debugPrint('[激励] 服务端回调 verify=${inf.rewardVerify}, '
          'amount=${inf.rewardAmount}, name=${inf.rewardName}, '
          'error=${inf.errorCode}/${inf.errorMessage}');
    },
  );
  await ad.loadAndShow();
}

DeepAdxRewardOrientation 枚举 ​

枚举数值说明
vertical1竖屏
horizontal2横屏

DeepAdxRewardServerInf 字段(服务端奖励回调) ​

字段类型说明
rewardVerifybool服务端是否校验通过
rewardAmountint校验通过的奖励数量
rewardNameString奖励名称
errorCodeint服务端返回错误码(0 表示无错)
errorMessageString错误信息

iOS 原生 SDK 暂未透出服务端奖励回调;onRewardServerInf 仅在 Android CSJ / BD 渠道触发。


5.5 横幅广告 ​

DeepAdxBannerView + DeepAdxBanner,以固定 width / height 承载原生横幅容器:

dart
DeepAdxBannerView(
  width:  320,
  height: 50,
  ad: DeepAdxBanner(
    placementId: '横幅广告位ID',
    refreshInterval:  30,   // 自动刷新间隔秒;0=不刷新(GDT/CSJ 生效)
    expressWidthDp:  320,   // CSJ 模板宽;默认取容器宽
    expressHeightDp: 50,    // CSJ 模板高;0=自适应
    showType: 0,            // 仅 iOS:0 锚定、1 内嵌
    y: 0,                   // 仅 iOS 锚定类型:Y 轴位置
    onSucceed:  () => debugPrint('[横幅] 加载成功'),
    onFailed:   (e) => debugPrint('[横幅] 加载失败 $e'),
    onExposure: () => debugPrint('[横幅] 曝光'),
    onClicked:  () => debugPrint('[横幅] 点击'),
    onClose:    () => debugPrint('[横幅] 关闭'),
  ),
)

5.6 原生信息流广告 ​

DeepAdxNativeExpressView + DeepAdxNativeExpress,支持动态高度自适应:

dart
DeepAdxNativeExpressView(
  width:  350,            // 容器宽(必填)
  // height: 280,         // 可选;不传则按实际渲染高度自适应(推荐)
  ad: DeepAdxNativeExpress(
    placementId: '原生广告位ID',
    expressWidthDp:  350,   // 模板宽(dp);0=取容器宽
    expressHeightDp: 0,     // 0=按模板自适应高度
    videoMute: true,        // 视频类广告默认静音
    ggTemplateType: 'small',// AdMob 模板:small / medium(仅 Android)
    onSucceed:       () => debugPrint('[原生] 加载成功'),
    onFailed:        (e) => debugPrint('[原生] 加载失败 $e'),
    onExposure:      () => debugPrint('[原生] 曝光'),
    onClicked:       () => debugPrint('[原生] 点击'),
    onClose:         () => debugPrint('[原生] 关闭'),
    onRenderSuccess: () => debugPrint('[原生] 模板渲染成功,高度已自适应'),
    onRenderFailed:  () => debugPrint('[原生] 模板渲染失败'),
  ),
)

自适应高度:height 为 null 时,组件在渲染成功前使用占位高度 280;原生回调 onRenderSuccess 会回传实际 dp 高度,组件内部自动 setState 更新为真实高度,无需外部处理。


6. 事件回调总览 ​

6.1 通用事件(所有形态均支持) ​

事件回调签名触发时机
加载成功onSucceed()广告素材加载完成
加载失败onFailed(DeepAdxError error)加载失败,error.code 为 2000–2017
曝光onExposure()广告首次展示在屏幕上
点击onClicked()用户点击广告
关闭onClose()用户关闭广告(插屏 / 激励全屏退出)

6.2 开屏专属 ​

事件回调平台
跳过onSkip()仅 iOS;Android 合并到 onClose
倒计时结束onCountdownToZero()仅 iOS;Android 合并到 onClose

6.3 激励视频专属 ​

事件回调说明
视频缓存完成onVideoCached()视频文件下载完毕
视频播放完成onVideoComplete()播放到结尾(不代表已达奖励条件)
视频跳过onVideoSkip()用户主动跳过
奖励生效onReward()⚠️ 请在此回调中执行发奖逻辑
服务端奖励回调onRewardServerInf(DeepAdxRewardServerInf)仅 Android CSJ/BD,可选

6.4 原生信息流专属 ​

事件回调说明
渲染成功onRenderSuccess()模板渲染完成,视图已可展示;高度自适应由组件内部自动处理
渲染失败onRenderFailed()模板渲染失败

7. 错误码 ​

DeepAdxError.code 与 iOS / Android 聚合层完全对齐(2000–2017),完整列表见 错误码汇总。常用错误码速查:

错误码含义常见排查方向
2000App ID 为空或错误检查双端 AppID 是否正确传入
2002广告信息为空placementId 错误或后台未配置
2006全部渠道执行失败渠道依赖未成对引入 / 网络异常 / 渠道包名不匹配
2008请求超时设备网络不佳;可重试
2009超过展示频控测试设备添加至后台白名单
2011Activity/VC 不存在页面已销毁再触发 show / 上下文空
2012无广告返回测试设备未加白 / 当前时段无填充 / 地区屏蔽
2013地区屏蔽海外渠道在国内请求,或国内渠道在海外请求
2016其他打开 setDebug + high 日志,查看原生日志定位
2017环境不匹配例如在海外 AppID 下使用国内测试 ID

8. 平台差异速查 ​

特性AndroidiOS
开屏跳过 / 倒计时事件仅回调 onCloseonSkip + onCountdownToZero → 最后 onClose
激励服务端回调onRewardServerInf(CSJ/BD)暂不支持
横幅锚定 / 内嵌默认内嵌showType:0=锚定,1=内嵌;锚定可用 y 控制偏移
开屏模板样式showAsExpress—
AdMob 模板类型ggTemplateType: 'small'/'medium'—
开屏超时配置—timeout(秒);0 或 null 表示 SDK 默认
openDev 开发者模式支持忽略(不执行任何操作)

9. 资源与示例 ​

资源地址
Flutter SDK 仓库(含完整 example)Gitee: deepadx-flutter-sdk
Flutter 在线体验(蒲公英)Android 国内 · Android 海外 · iOS
Flutter SDK 完整对接文档(example 内)仓库路径:example/INTEGRATION.md
原生 iOS SDK 示例Gitee: deepadx-ios-sdk
原生 Android SDK 示例Gitee: deepadx-android-sdk
pub.dev 包地址pub.dev/packages/deepadx_sdk
示例测试 AppID / 广告位示例测试 ID
激励视频服务端回调协议激励视频服务端
Q&A 与常见问题Q&A

10. FAQ 常见问题 ​

Q1:Android 启动闪退 ClassNotFoundException: TTFileProvider? ​

CSJ 7.x(mediation-sdk)已将旧版 TTFileProvider 移除。若宿主 AndroidManifest.xml 仍声明了该 Provider,请在 <application> 标签内用以下代码移除,并打开 android.enableJetifier=true:

xml
<provider
    android:name="com.bytedance.sdk.openadsdk.TTFileProvider"
    tools:node="remove" />

Q2:iOS pod install 提示找不到 DeepAdxSDK? ​

执行 pod install --repo-update 更新 spec 仓库;如仍失败,检查宿主 Podfile 是否启用了私有源或 source 限定。

Q3:onAdFailed 一直返回 2006(全部渠道执行失败)? ​

检查:

  1. Android 端 dependencies 中 adapter 与三方 SDK 是否成对引入(缺一不可)
  2. iOS 端 Podfile 是否正确添加对应 subspec 并 pod install
  3. 是否使用测试 AppID 但没在后台添加测试设备
  4. minSdk ≥ 24、iOS ≥ 12.0

Q4:开屏加载成功后白屏? ​

onClose / onFailed 回调中务必用 setState 移除 DeepAdxSplashView(如示例中 _showSplash = false),否则视图会以空容器的形式留在视图树上。

Q5:激励视频什么时候发奖? ​

必须在 onReward 回调中发奖。onVideoComplete 只表示播放到结尾,可能因跳过未达观看时长阈值而不触发 onReward。

Q6:同一广告实例可以多次 loadAndShow 吗? ​

不支持。每个控制器实例为「一次性使用」。若要重复展示:

  • 在 onClose 中 destroy() 当前实例,然后重新 new 一个再 loadAndShow();或
  • 用 loadOnly() 预加载新实例后再在需要时 show()。

Q7:如何查看更详细的 SDK 日志? ​

dart
await DeepAdxFlutterSdk.setDebug(true, logLevel: DeepAdxLogLevel.high);
await DeepAdxFlutterSdk.openDev(true); // 仅 Android,可再追加更多链路日志

其他问题欢迎参考 Q&A 或 联系我们。

DeepAdx SDK 官方文档