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 控制器 | 视图组件 | 说明 |
|---|---|---|---|
| 开屏 | DeepAdxSplash | DeepAdxSplashView | PlatformView 全屏容器承载,冷启展示 |
| 插屏 | DeepAdxInterstitial | — | 无视图组件,直接全屏覆盖展示 |
| 激励视频 | DeepAdxRewardVideo | — | 无视图组件,全屏展示 + 服务端奖励校验 |
| 横幅 | DeepAdxBanner | DeepAdxBannerView | PlatformView 固定尺寸容器承载 |
| 原生信息流 | DeepAdxNativeExpress | DeepAdxNativeExpressView | PlatformView 容器,支持动态高度自适应 |
2. 环境要求
| 项 | 最低要求 | 验证版本 |
|---|---|---|
| Flutter SDK | ≥ 3.10.0 | 3.44.x |
| Dart | ≥ 3.0.0 | 3.5+ |
| Android minSdk | 24 | — |
| Android compileSdk | 36 | — |
| iOS 最低系统版本 | 12.0(示例工程可设为 13.0) | — |
| deepadx-android 聚合核心 | — | 2.1.8(自动引入) |
| DeepAdxSDK(iOS) 聚合核心 | — | 2.0.6(自动引入) |
3. 集成配置
3.1 pub.dev 引入
在 Flutter 工程的 pubspec.yaml 中添加:
dependencies:
flutter:
sdk: flutter
deepadx_sdk: ^1.0.3或直接命令行:
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 仓库及渠道源:
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 中:
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 渠道,注意以下两点(示例工程已处理):
- 因 CSJ 7.x 的
mediation-sdk移除了旧版TTFileProvider,若你在AndroidManifest.xml的<application>中声明过com.bytedance.sdk.openadsdk.TTFileProvider,请用tools:node="remove"移除。 - 打开 Jetifier(
gradle.properties中android.enableJetifier=true)。
3.3 iOS 端配置
Flutter 插件的 deepadx_sdk.podspec 已声明依赖 DeepAdxSDK/Core,pod install 会自动拉取。 渠道适配器通过 subspec 方式在宿主 Podfile 中按需追加:
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'
end3.3.1 Info.plist 配置
在 ios/Runner/Info.plist 的 Source Code 视图中添加:
<!-- 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,避免漏配影响归因 -->完成后执行:
cd ios
rm -rf Podfile.lock Pods
flutter clean && flutter pub get
pod install --repo-update4. SDK 初始化
在 main() 中、runApp() 之前调用 DeepAdxFlutterSdk.init()。 DeepAdx 后台的应用分 Android / iOS 分别注册(包名 / BundleID 不同,AppID 也不同),各自传入对应参数;双端共用同一 AppID 时可仅传 appId。
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.none | 0 | 不打印任何日志 |
DeepAdxLogLevel.defaultLevel | 1 | 核心方法日志(默认) |
DeepAdxLogLevel.simple | 2 | 适合一般接入查看 |
DeepAdxLogLevel.high | 3 | 详细执行信息 |
DeepAdxLogLevel.max | 10 | 全部信息 |
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 回调中移除该视图。
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()。
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。
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 枚举
| 枚举 | 数值 | 说明 |
|---|---|---|
vertical | 1 | 竖屏 |
horizontal | 2 | 横屏 |
DeepAdxRewardServerInf 字段(服务端奖励回调)
| 字段 | 类型 | 说明 |
|---|---|---|
rewardVerify | bool | 服务端是否校验通过 |
rewardAmount | int | 校验通过的奖励数量 |
rewardName | String | 奖励名称 |
errorCode | int | 服务端返回错误码(0 表示无错) |
errorMessage | String | 错误信息 |
iOS 原生 SDK 暂未透出服务端奖励回调;
onRewardServerInf仅在 Android CSJ / BD 渠道触发。
5.5 横幅广告
DeepAdxBannerView + DeepAdxBanner,以固定 width / height 承载原生横幅容器:
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,支持动态高度自适应:
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),完整列表见 错误码汇总。常用错误码速查:
| 错误码 | 含义 | 常见排查方向 |
|---|---|---|
| 2000 | App ID 为空或错误 | 检查双端 AppID 是否正确传入 |
| 2002 | 广告信息为空 | placementId 错误或后台未配置 |
| 2006 | 全部渠道执行失败 | 渠道依赖未成对引入 / 网络异常 / 渠道包名不匹配 |
| 2008 | 请求超时 | 设备网络不佳;可重试 |
| 2009 | 超过展示频控 | 测试设备添加至后台白名单 |
| 2011 | Activity/VC 不存在 | 页面已销毁再触发 show / 上下文空 |
| 2012 | 无广告返回 | 测试设备未加白 / 当前时段无填充 / 地区屏蔽 |
| 2013 | 地区屏蔽 | 海外渠道在国内请求,或国内渠道在海外请求 |
| 2016 | 其他 | 打开 setDebug + high 日志,查看原生日志定位 |
| 2017 | 环境不匹配 | 例如在海外 AppID 下使用国内测试 ID |
8. 平台差异速查
| 特性 | Android | iOS |
|---|---|---|
| 开屏跳过 / 倒计时事件 | 仅回调 onClose | onSkip + 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:
<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(全部渠道执行失败)?
检查:
- Android 端
dependencies中 adapter 与三方 SDK 是否成对引入(缺一不可) - iOS 端 Podfile 是否正确添加对应 subspec 并
pod install - 是否使用测试 AppID 但没在后台添加测试设备
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 日志?
await DeepAdxFlutterSdk.setDebug(true, logLevel: DeepAdxLogLevel.high);
await DeepAdxFlutterSdk.openDev(true); // 仅 Android,可再追加更多链路日志