DeepAdx Android 接入文档
本文面向第三方 Android App,说明 DeepAdx 聚合 SDK 的 Maven / AAR 集成、初始化与各广告位调用。
1. 环境要求
| 项目 | 建议版本 |
|---|---|
| Android Gradle Plugin | 8.10+ |
| Gradle | 8.14+ |
| JDK | 17(AGP 8.x 运行要求) |
| compileSdk | 36 |
| targetSdk | 36 |
| minSdk | 24 |
2. 渠道模块与三方 SDK 成对表(按需引入)
核心原则:每个渠道都是 adapter + 原始 SDK 两行一组,缺一不可。未用的渠道把整组两行一起删掉。
csj与pag不能出现在同一变体。
核心(必选)
| 模块 | DeepAdx(第 1 行) | 原始 SDK |
|---|---|---|
| 核心 | deepadx-core(单独一行) | — |
国内(按需):CSJ / GDT / BD / KS
| 渠道 | DeepAdx adapter(第 1 行) | 原始 SDK(第 2 行,必须成对) |
|---|---|---|
| CSJ | deepadx-adapter-csj | com.pangle_beta.cn:mediation-sdk:7.4.1.4 |
| GDT | deepadx-adapter-gdt | com.deepadx.thirdparty:gdt-union-normal:4.640.1510 |
| BD | deepadx-adapter-bd | com.deepadx.thirdparty:baidu-mobads-sdk:9.432 |
| KS | deepadx-adapter-ks | com.deepadx.thirdparty:kssdk-ad:5.1.20.1 |
海外(按需):GG / PAG(PAG 与国内 CSJ 二选一)
| 渠道 | DeepAdx adapter(第 1 行) | 原始 SDK(第 2 行,必须成对) |
|---|---|---|
| GG | deepadx-adapter-gg | com.google.android.gms:play-services-ads:24.9.0 |
| PAG | deepadx-adapter-pag | com.pangle.global:ads-sdk:6.5.1.2 |
Gradle 必须写成「注释标题 + adapter + 原始 SDK」三行一组。完整可复制示例见 §3.2。
3. Maven 集成(推荐)
3.1 配置仓库
在项目根 settings.gradle 或 build.gradle 中:
dependencyResolutionManagement {
repositories {
maven { url "https://maven.deepadx.com/repository/maven-releases/" }
mavenCentral()
google()
// 接入 PAG 时需要
maven { url 'https://artifact.bytedance.com/repository/pangle' }
}
}3.2 添加依赖(成对引入,按需删减)
版本号请以 Maven 仓库 最新发布为准,下文以 2.1.8 为例。
每一组都是 adapter + 原始 SDK 两行;组与组之间用注释分开。未用渠道删除整组,不要只留 adapter 或只留原始 SDK。国内四个与海外两个分区引入;CSJ 与 PAG 二选一。
def sdkVer = '2.1.8'
dependencies {
implementation "com.deepadx.sdk:deepadx-core:${sdkVer}"
// ===== 国内(按需):CSJ / GDT / BD / KS =====
// --- CSJ(与 PAG 二选一)---
implementation "com.deepadx.sdk:deepadx-adapter-csj:${sdkVer}"
implementation 'com.pangle_beta.cn:mediation-sdk:7.4.1.4' // 与 csj 成对
// --- GDT ---
implementation "com.deepadx.sdk:deepadx-adapter-gdt:${sdkVer}"
implementation 'com.deepadx.thirdparty:gdt-union-normal:4.640.1510' // 与 gdt 成对
// --- BD ---
implementation "com.deepadx.sdk:deepadx-adapter-bd:${sdkVer}"
implementation 'com.deepadx.thirdparty:baidu-mobads-sdk:9.432' // 与 bd 成对
// --- KS ---
implementation "com.deepadx.sdk:deepadx-adapter-ks:${sdkVer}"
implementation 'com.deepadx.thirdparty:kssdk-ad:5.1.20.1' // 与 ks 成对
// ===== 海外(按需):GG / PAG =====
// 启用 PAG 时请删掉上面整组 CSJ(二者不能同包)
// --- GG ---
implementation "com.deepadx.sdk:deepadx-adapter-gg:${sdkVer}"
implementation 'com.google.android.gms:play-services-ads:24.9.0' // 与 gg 成对
// --- PAG(与 CSJ 二选一,国内包请保持注释)---
// implementation "com.deepadx.sdk:deepadx-adapter-pag:${sdkVer}"
// implementation 'com.pangle.global:ads-sdk:6.5.1.2' // 与 pag 成对
}漏掉组内第二行(原始 SDK)会导致该渠道初始化失败或运行时崩溃(如 BD 开屏)。成对坐标见上文 §2。
合规说明:SDK 不内置 Consent 弹窗。请在用户同意隐私政策后调用
DeepAdx.init();若需 GDPR 合规,请由 App 自行处理后再初始化 SDK。
3.3 国内 / 海外 Flavor(推荐)
官方 Example 用 Product Flavor 拆国内/海外:默认 china。csj 与 pag 不能打进同一 APK。
| Flavor | 地区 | 渠道 | 构建 | 包名 | 蒲公英 |
|---|---|---|---|---|---|
china(默认) | 国内 | CSJ / GDT / BD / KS | ./gradlew :example:assembleChinaRelease | com.deepadx.example | deepadxsdk-android-cn |
global | 海外 | GG / PAG | ./gradlew :example:assembleGlobalRelease | com.deepadx.example.global | deepadxsdk-android-global |
安装后看 Logcat:region=china(国内) / region=global(海外)。测试 ID 对照见 示例测试 ID。
Flavor 下同样是 一组两行:
dependencies {
def sdkVer = '2.1.8'
implementation "com.deepadx.sdk:deepadx-core:${sdkVer}"
// ===== 国内 china:CSJ / GDT / BD / KS =====
// --- CSJ ---
chinaImplementation "com.deepadx.sdk:deepadx-adapter-csj:${sdkVer}"
chinaImplementation 'com.pangle_beta.cn:mediation-sdk:7.4.1.4' // 与 csj 成对
// --- GDT ---
chinaImplementation "com.deepadx.sdk:deepadx-adapter-gdt:${sdkVer}"
chinaImplementation 'com.deepadx.thirdparty:gdt-union-normal:4.640.1510' // 与 gdt 成对
// --- BD ---
chinaImplementation "com.deepadx.sdk:deepadx-adapter-bd:${sdkVer}"
chinaImplementation 'com.deepadx.thirdparty:baidu-mobads-sdk:9.432' // 与 bd 成对
// --- KS ---
chinaImplementation "com.deepadx.sdk:deepadx-adapter-ks:${sdkVer}"
chinaImplementation 'com.deepadx.thirdparty:kssdk-ad:5.1.20.1' // 与 ks 成对
// ===== 海外 global:GG / PAG =====
// --- GG ---
globalImplementation "com.deepadx.sdk:deepadx-adapter-gg:${sdkVer}"
globalImplementation 'com.google.android.gms:play-services-ads:24.9.0' // 与 gg 成对
// --- PAG(与 CSJ 二选一)---
globalImplementation "com.deepadx.sdk:deepadx-adapter-pag:${sdkVer}"
globalImplementation 'com.pangle.global:ads-sdk:6.5.1.2' // 与 pag 成对
}4. 本地 AAR 集成
将发布包放入 app/libs/,并配置:
repositories {
flatDir { dirs 'libs' }
}
dependencies {
def sdkVer = '2.1.8'
implementation(name: "deepadx-core_${sdkVer}", ext: 'aar')
// ===== 国内:CSJ / GDT / BD / KS =====
// --- CSJ(与 mediation-sdk 成对;原始 SDK 仍走 Maven 或自行放入 libs)---
chinaImplementation(name: "deepadx-adapter-csj_${sdkVer}", ext: 'aar')
chinaImplementation 'com.pangle_beta.cn:mediation-sdk:7.4.1.4'
// --- BD(adapter AAR + 原始 SDK AAR 成对)---
chinaImplementation(name: "deepadx-adapter-bd_${sdkVer}", ext: 'aar')
chinaImplementation(name: 'Baidu_MobAds_SDK-release_v9.432', ext: 'aar')
// GDT / KS 同样:adapter AAR 下一行必须是该渠道原始 SDK
// ===== 海外:GG / PAG =====
// GG / PAG 同样成对;PAG 与 CSJ 不要打进同一变体
}本地 AAR 可从 Gitee deepadx-android-sdk checkout tag
2.1.8,使用libs/或Example/libs/下*_2.1.8.aar。
5. AndroidManifest
<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
<application android:name=".MyApplication">
<!-- 接入 GG 时必填 -->
<meta-data
android:name="com.google.android.gms.ads.APPLICATION_ID"
android:value="ca-app-pub-xxxxxxxxxxxxxxxx~yyyyyyyyyy" />
</application>权限请按业务场景与隐私合规要求配置,勿盲目照搬 Demo 中的全量权限。
6. SDK 初始化
重要:请在用户同意隐私政策 之后 初始化,不要放在 Application.onCreate() 第一时间调用。
DeepAdx.setDebug(true, DeepAdxLogLevel.DEFAULT);
// 海外广告全局静音 / 音量(可选,可在 init 前后调用;未调用不干预渠道默认声音)
// 静音:广告不出声。setAdMuted 与 setAdVolume 相互独立,要静音建议两行都调。
// DeepAdx.setAdMuted(true);
// DeepAdx.setAdVolume(0f);
DeepAdx.setAdMuted(false);
DeepAdx.setAdVolume(1f);
DeepAdx.init(activity, "YOUR_APP_ID", new InitCallBack() {
@Override
public void onInitSuccess() {
Log.d("DeepAdx", "SDK 初始化成功");
}
@Override
public void onInitFail(DeepAdxError error) {
Log.e("DeepAdx", "初始化失败: " + error.getErrorMessage());
}
});7. 广告位 ID(placementId)
后台「广告单元」的 placement_id 用于标识具体广告位。接入时请始终传入 placementId。
测试用 ID 见 示例测试 ID。
// 激励视频
DeepAdxRewardVideo reward = new DeepAdxRewardVideo(activity, "YOUR_PLACEMENT_ID", listener);
// 开屏
DeepAdxSplash splash = new DeepAdxSplash(activity, adContainer, "YOUR_PLACEMENT_ID", listener);
// Banner
DeepAdxBanner banner = new DeepAdxBanner(activity, bannerContainer, "YOUR_PLACEMENT_ID", listener);DeepAdxInterstitial、DeepAdxNativeExpress 等均提供带 placementId 的构造函数。
8. 各广告位 API
| 广告位 | 类名 |
|---|---|
| 开屏 | DeepAdxSplash |
| 横幅 | DeepAdxBanner |
| 插屏 | DeepAdxInterstitial |
| 激励视频 | DeepAdxRewardVideo |
| 原生模板 / 信息流 | DeepAdxNativeExpress |
| 全屏视频 | DeepAdxFullScreenVideo |
| Draw 信息流 | DeepAdxDraw |
8.1 开屏示例
DeepAdxSplash splashAd = new DeepAdxSplash(activity, adContainer, "YOUR_PLACEMENT_ID", listener);
splashAd.loadAndShow();8.2 插屏示例(先加载后展示)
DeepAdxInterstitial interstitial = new DeepAdxInterstitial(activity, "YOUR_PLACEMENT_ID", listener);
interstitial.loadOnly();
// 合适时机
interstitial.show();8.3 激励视频示例
加载前建议设置业务参数:
DeepAdxRewardVideo rewardVideo = new DeepAdxRewardVideo(activity, "YOUR_PLACEMENT_ID", listener);
rewardVideo.setUserId("user_10001");
rewardVideo.setExtra("order_20260614");
rewardVideo.setRewardName("金币");
rewardVideo.setRewardAmount(100);
rewardVideo.loadOnly();服务端发奖见 激励视频服务端回调。
8.4 Banner 示例
DeepAdxBanner banner = new DeepAdxBanner(activity, bannerContainer, "YOUR_PLACEMENT_ID", listener);
banner.loadAndShow();页面销毁时调用 destroy() 释放广告对象。
9. 激励视频客户端回调
DeepAdxRewardVideoListener 中与发奖相关:
| 回调 | 说明 |
|---|---|
onAdReward() | 激励达成通知,可用于 UI 提示 |
onRewardServerInf(...) | 服务端校验信息,严格发奖建议关注此回调 |
onVideoCached() | 视频缓存完成,适合此时展示 |
正式发奖请以 服务端回调 为准,详见 REWARD 文档。
10. 常见问题
Q:为什么 csj 和 pag 不能同时接入?
A:同一 APK 内会冲突。按发行市场二选一,或用 Flavor 拆成 china / global。
Q:为什么在 Application 里初始化?
A:不建议。应在隐私协议同意后再初始化,符合合规要求。
Q:Maven 拉不到依赖?
A:检查 maven.deepadx.com 仓库是否已配置,版本号是否与仓库发布一致(当前最新 2.1.8)。
Q:BD 开屏崩溃 / R$drawable 找不到?
A:自 2.1.2 起 adapter-bd 不再 fat-embed BD SDK,请确认已额外依赖 com.deepadx.thirdparty:baidu-mobads-sdk:9.432(或本地 Baidu_MobAds_SDK-release_v9.432.aar)。请勿与 2.1.1 及更早 fat 版 adapter-bd 混用。
Q:PAG 初始化失败?
A:deepadx-adapter-pag 必须与 com.pangle.global:ads-sdk:6.5.1.2 成对引入,并配置 https://artifact.bytedance.com/repository/pangle。
Q:Demo 工程在哪?国内和海外怎么区分?
A:Gitee deepadx-android-sdk 仓库 Example 目录。Flavor 默认 china(国内),海外用 global;包名分别为 com.deepadx.example / com.deepadx.example.global,可同时安装。蒲公英:国内 · 海外。详见 china / global 说明。Flutter Demo:国内 · 海外。
