1. onemore
文档站
  • onemore
    • onemore 鸿蒙对接文档
    • 一盟广告 Android SDK接入文档
    • 一盟广告 iOS SDK接入文档
  • YMTrack
    • Cocos 微信小游戏接入文档
  1. onemore

一盟广告 Android SDK接入文档

1. SDK概述#


2. 接入准备#

2.1 添加依赖#

在项目根目录的 build.gradle 中添加仓库:
在应用模块的 build.gradle 中添加依赖:

2.2 配置权限#

在 AndroidManifest.xml 中添加必要权限:
<!-- 必需权限 -->
<uses-permission android:name="android.permission.INTERNET" />

<!-- 可选权限 - 根据业务需求添加 -->
<uses-permission android:name="android.permission.ACCESS_WIFI_STATE" />
<uses-permission android:name="android.permission.READ_PHONE_STATE" />
<uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE" />
<uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />
权限与合规说明:
INTERNET 是基础必需权限。
设备标识、位置、安装列表等敏感能力建议通过 QLCustomController 按需开放。
Android 11+ 如果要使用安装探测、scheme 探测等能力,需要宿主补充对应 <queries>,否则这些能力会降级。
SDK 自带 FileProvider,authority 为 ${applicationId}.fileProvider,宿主如果已经占用同名 authority,需要提前规避冲突。

2.3 信通院送审 Demo 说明#

信通院送审演示工程目录统一命名为 caict_demo,用于和普通开发 Demo 区分。
当前送审 Demo 的基础信息如下:
项目说明
工程目录caict_demo/
应用包名com.qiliang.mindemo
应用名称一盟广告 Demo
最低系统版本Android 7.0 / API 24
目标系统版本API 33
实际声明权限android.permission.INTERNET、android.permission.ACCESS_NETWORK_STATE
归档文件output/caict_demo/caict_demo_信通院送审版_20260817_unsigned.apk
送审 Demo 仅用于展示 SDK 基础广告能力,权限声明以 APK 实际解析结果为准。

2.4 混淆配置#

在 proguard-rules.pro 中添加以下规则:
# ========== QL SDK 混淆规则(必需) ==========

# 基本规则 - 保留所有 QL SDK 公共 API
-dontwarn com.qiliang.**

# AndroidX 库(如果还没有)
-keep class androidx.** {*;}
-keep interface androidx.** {*;}
-dontwarn androidx.**

# 保持注解
-keep @androidx.annotation.Keep class *
-keepclassmembers class * {
    @androidx.annotation.Keep *;
}

# 保留 native 方法
-keepclasseswithmembernames class * {
    native <methods>;
}

# 保留 Parcelable
-keep class * implements android.os.Parcelable {
  public static final android.os.Parcelable$Creator *;
}

# 保留 Serializable
-keepnames class * implements java.io.Serializable
-keepclassmembers class * implements java.io.Serializable {
    static final long serialVersionUID;
    private static final java.io.ObjectStreamField[] serialPersistentFields;
    private void writeObject(java.io.ObjectOutputStream);
    private void readObject(java.io.ObjectInputStream);
    java.lang.Object writeReplace();
    java.lang.Object readResolve();
}

# QL SDK 公共类
-keep public class com.qiliang.agg.QLSdk { public *; public static *; }
-keep public class com.qiliang.agg.QLSdk$Callback { public *; }
-keep public class com.qiliang.agg.QLSdkConfig { public *; }
-keep public class com.qiliang.agg.QLSdkConfig$Builder { public *; }
-keep public class com.qiliang.agg.models.QLAdSlot { public *; }
-keep public class com.qiliang.agg.models.QLAdSlot$Builder { public *; }
-keep public class com.qiliang.agg.models.QLAdError { public *; }
-keep public class com.qiliang.agg.models.QLAdLoadType { public *; }
-keep public class com.qiliang.agg.models.QLAdLocation { public *; }
-keep public class com.qiliang.agg.models.QLAppInfo { public *; }
-keep public class com.qiliang.agg.models.QLImageInfo { public *; }
-keep public class com.qiliang.agg.utils.devices.QLScreenUtils { public static *; }

# QL SDK 公共接口和抽象类
-keep public abstract class com.qiliang.agg.interfaces.QLCustomController { public *; }
-keep public interface com.qiliang.agg.interfaces.** { public *; }
-keep public class com.qiliang.agg.core.provider.QLAdNative { public *; }
-keep public interface com.qiliang.agg.core.provider.QLAdNative$* { public *; }

# QL SDK 常量
-keep public class com.qiliang.agg.constants.QLRewardConstant { public *; }
-keep public class com.qiliang.agg.constants.QLRewardConstant$REWARD_PARAMS { public static final *; }
重要说明:
以上规则是必需的,缺少可能导致 SDK 功能异常或编译错误
如果您的项目已有 AndroidX 相关规则,可以跳过重复的部分
务必在 Release 构建后测试所有广告功能

3. SDK初始化#

3.1 在Application中初始化#

3.2 初始化配置说明#

配置项是否必需说明
MediaId是媒体ID,联系商务获取
MediaSecret是媒体密钥,联系商务获取
AppName否应用名称,用于日志标识
Debug否调试日志开关,不建议将业务联调策略绑定到该开关
SupportMultiProcess否多进程支持,默认false

3.3 隐私与多进程建议#

QLCustomController 建议在用户隐私同意后再按需放开 Android ID、OAID、位置、安装列表等能力。
多进程场景下,建议仅在明确需要时开启 setSupportMultiProcess(true),并在宿主侧自行确认主进程与 WebView/服务进程初始化策略。
如果宿主要用安装探测或 scheme 探测能力,Android 11+ 需要额外提供对应的 <queries>。

4. 开屏广告接入#

4.2 接入步骤#

4.2.1 构建广告请求#

4.2.2 布局文件#

<?xml version="1.0" encoding="utf-8"?>
<FrameLayout xmlns:android="http://schemas.android.com/apk/res/android"
    android:id="@+id/splash_container"
    android:layout_width="match_parent"
    android:layout_height="match_parent"
    android:background="@color/white" />

4.3 注意事项#

1.
容器高度要求:容器高度必须大于400dp
2.
超时保护:建议设置3.5秒超时,避免用户等待时间过长
3.
生命周期:在onDestroy中及时销毁广告对象
4.
跳转处理:正确处理onPause/onResume,避免落地页返回问题

5. 横幅广告接入#

5.2 接入步骤#

5.2.1 加载和展示广告#

5.2.2 布局文件#

<LinearLayout
    android:id="@+id/banner_container"
    android:layout_width="match_parent"
    android:layout_height="wrap_content"
    android:layout_gravity="bottom"
    android:orientation="vertical" />

5.3 常用尺寸#

尺寸类型宽x高(dp)适用场景
标准横幅320x50页面顶部/底部
大横幅320x100页面底部
全屏横幅屏幕宽x90页面底部

6. 插屏广告接入#

6.2 接入步骤#

6.3 展示时机建议#

游戏关卡结束
文章阅读完成
用户主动触发(如点击按钮)
避免在用户正在操作时弹出

7. 激励视频接入#

7.2 接入步骤#

7.3 服务端奖励验证#

如需使用服务端奖励验证,需要:
1.
在开发者后台配置回调URL
2.
在请求广告时设置RewardName、RewardAmount、UserID、MediaExtra
3.
在onRewardVerify回调中根据verify参数判断是否发放奖励
4.
MediaExtra仅支持单层JSON对象

8. 原生广告接入#

8.2 接入步骤#


9. GroMore自定义Adapter接入#

本章节介绍如何将一盟广告SDK作为GroMore(穿山甲聚合)的自定义Adapter接入。

9.1 概述#

支持的广告类型:
广告类型Adapter类名GroMore接口
开屏广告QLSplashAdapterGMCustomSplashAdapter
信息流广告QLNativeExpressAdapterGMCustomNativeAdapter
激励视频QLRewardVideoAdapterGMCustomRewardedVideoAdapter
插屏广告QLInterstitialAdapterGMCustomInterstitialAdapter
Banner广告QLBannerAdapterGMCustomBannerAdapter

9.2 接入准备#

9.2.1 添加依赖#

将AAR文件放入项目的 libs 目录,并在 build.gradle 中配置:
注意:最低 Android SDK 版本要求为 24 (Android 7.0),请确保 minSdkVersion >= 24。

9.2.2 混淆配置#

如果开启了代码混淆,请添加以下规则:
# 一盟广告 GroMore Adapter
-keep class com.qiliang.mediation.** { *; }
-keep class com.qiliang.agg.** { *; }

9.3 SDK初始化#

一盟SDK支持两种初始化方式:

方式一:通过GroMore后台配置自动初始化(推荐)#

在GroMore后台创建自定义广告网络时配置参数,SDK会自动完成初始化。
GroMore后台配置:
配置项填写内容说明
广告网络名称一盟广告用于标识广告源
初始化Adapter类名com.qiliang.mediation.adapter.QLInitAdapterSDK初始化类
AppIdYOUR_MEDIA_ID一盟平台的媒体ID
AppKeyYOUR_MEDIA_SECRET一盟平台的媒体密钥
使用此方式,无需在Application中手动初始化,GroMore会自动调用初始化Adapter完成SDK初始化。

方式二:在Application中手动初始化#

如果不使用方式一,可以在Application中手动初始化:
注意:必须在GroMore加载广告之前完成一盟SDK初始化。

9.4 在GroMore后台配置#

9.4.1 添加自定义广告网络#

1.
登录GroMore后台
2.
进入「广告网络」->「自定义广告网络」
3.
点击「新建自定义广告网络」
4.
填写以下信息:
广告网络名称:qiliang_ad
初始化Adapter类名:com.qiliang.mediation.adapter.QLInitAdapter
AppId:填写一盟平台的媒体ID
AppKey:填写一盟平台的媒体密钥

9.4.2 配置各广告类型的Adapter#

开屏广告:
Adapter类名:com.qiliang.mediation.splash.QLSplashAdapter
广告位ID:填写一盟平台的开屏广告位ID
信息流广告:
Adapter类名:com.qiliang.mediation.native_express.QLNativeExpressAdapter
广告位ID:填写一盟平台的信息流广告位ID
激励视频:
Adapter类名:com.qiliang.mediation.reward.QLRewardVideoAdapter
广告位ID:填写一盟平台的激励视频广告位ID
插屏广告:
Adapter类名:com.qiliang.mediation.interstitial.QLInterstitialAdapter
广告位ID:填写一盟平台的插屏广告位ID
Banner广告:
Adapter类名:com.qiliang.mediation.banner.QLBannerAdapter
广告位ID:填写一盟平台的Banner广告位ID

9.5 Adapter参数说明#

在GroMore后台配置Adapter时,可通过JSON格式传递额外参数:
{
    "slot_id": "YOUR_SLOT_ID",
    "media_id": "YOUR_MEDIA_ID"
}
参数名类型必填说明
slot_idString是一盟平台广告位ID
media_idString否媒体ID(如已在Application中初始化可不传)

9.6 Bidding竞价说明#

一盟广告Adapter支持GroMore的Bidding模式:
1.
Client Bidding:Adapter会在加载广告时返回出价信息
2.
竞价逻辑:由GroMore统一管理竞价流程
3.
价格单位:分(CNY)

9.7 版本对照表#

GroMore Adapter版本一盟SDK版本GroMore SDK版本
1.0.32.1.0+5.0.0+

9.8 常见问题#

Q: 出现 "QL SDK not initialized" 错误
A: 请确保在Application.onCreate()中调用了QLGroMoreInitializer.init()方法,且在GroMore初始化之前完成。
Q: 广告加载失败,返回NO_AD
A: 请检查:
1.
广告位ID是否正确
2.
媒体ID是否正确配置
3.
网络连接是否正常
4.
广告位在一盟平台是否已上线
Q: 如何调试Adapter
A:
1.
在初始化时开启Debug模式
2.
查看Logcat中TAG为"QLSDK_GroMore"的日志
3.
使用GroMore的测试模式进行调试

10. Taku自定义Adapter接入#

本章节介绍如何将一盟广告SDK作为 Taku / AnyThink 聚合平台的自定义 Adapter 接入。

10.1 概述#

Taku 适配器模块为 anythink_network_yimeng,命名空间为 com.yimeng.anythink。
支持的广告类型:
广告类型Adapter类名
开屏广告com.yimeng.anythink.splash.SplashAdapter
信息流模板广告com.yimeng.anythink.nativeexpress.NativeExpressAdapter
激励视频com.yimeng.anythink.reward.RewardVideoAdapter
插屏广告com.yimeng.anythink.interstitial.InterstitialAdapter
Banner广告com.yimeng.anythink.banner.BannerAdapter
初始化管理类com.yimeng.anythink.adapter.InitManager

10.2 接入准备#

10.2.1 添加依赖#

将 AAR 文件放入项目的 libs 目录,并在 build.gradle 中配置:
注意:最低 Android SDK 版本要求为 24 (Android 7.0),请确保 minSdkVersion >= 24。

10.2.2 混淆配置#

如果开启了代码混淆,请添加以下规则:
-keep class com.yimeng.anythink.** { *; }
-keep class com.qiliang.agg.** { *; }

10.3 后台配置#

在 Taku / AnyThink 后台创建自定义广告网络时,请使用以下配置。

10.3.1 初始化配置#

配置项填写内容说明
广告网络名称YiMeng / 一盟广告用于标识广告源
初始化管理类com.yimeng.anythink.adapter.InitManagerSDK 初始化入口
app_id一盟媒体ID必填
app_key一盟媒体密钥必填

10.3.2 各广告类型 Adapter 名称#

开屏:com.yimeng.anythink.splash.SplashAdapter
Banner:com.yimeng.anythink.banner.BannerAdapter
信息流模板:com.yimeng.anythink.nativeexpress.NativeExpressAdapter
插屏:com.yimeng.anythink.interstitial.InterstitialAdapter
激励视频:com.yimeng.anythink.reward.RewardVideoAdapter

10.4 自定义参数说明#

Taku / AnyThink 后台当前使用以下自定义参数 key:
{
    "app_id": "YOUR_MEDIA_ID",
    "app_key": "YOUR_MEDIA_SECRET",
    "slot_id": "YOUR_SLOT_ID"
}
参数名类型必填说明
app_idString是一盟平台媒体ID
app_keyString是一盟平台媒体密钥
slot_idString是一盟平台广告位ID
注意:Taku 适配器当前读取的广告位参数 key 为 slot_id,不是 unit_id。

10.5 调试建议#

1.
先确认后台是否已为对应 placement 绑定正确的 Adapter 类名。
2.
确认 app_id、app_key、slot_id 三个字段都已下发。
3.
如果日志提示 YiMeng slotId is empty.,优先检查自定义参数是否错误使用了 unit_id。
4.
如果日志返回 10000|没有获取到广告,说明链路已打到一盟侧,但当前广告位无填充或广告位类型不匹配。

11. 常见问题#

10.0 代码编写相关#

Q: 为什么代码示例中不使用 @Override 注解?
A: 由于 AAR 文件经过 R8 混淆处理,接口方法被标记为 SYNTHETIC(合成的),导致 Java 编译器不允许使用 @Override 注解。
错误示例:
正确做法:

10.1 初始化相关#

Q: SDK初始化失败怎么办?
A: 请检查以下几点:
1.
MediaId和MediaSecret是否正确
2.
网络权限是否已添加
3.
是否在主进程初始化
4.
查看错误码和错误信息进行排查
Q: 是否必须在Application中初始化?
A: 不是必须的,但建议在Application中初始化以保证SDK尽早准备就绪。也可以在首次请求广告前初始化。

10.2 广告加载相关#

Q: 广告加载失败的常见原因?
A:
广告位ID不正确
网络连接问题
广告素材尺寸不匹配
底价设置过高
用户定向不匹配
广告填充率不足
Q: 如何提高广告加载成功率?
A:
1.
使用QLAdLoadType.PRELOAD提前加载
2.
合理设置底价,避免过高
3.
提供准确的设备信息和用户画像
4.
确保网络连接稳定

10.3 广告展示相关#

Q: 广告加载成功但不显示?
A: 请检查:
1.
调用render()或showAd()方法
2.
容器是否可见且尺寸合适
3.
查看onRenderFail回调的错误信息
4.
确认isReady()返回true
Q: 如何处理广告关闭事件?
A: 在对应的监听器中实现onAdDismiss()或onAdClose()回调,在回调中清理广告视图和资源。

10.4 激励视频相关#

Q: 奖励验证失败怎么办?
A:
1.
检查服务端回调配置是否正确
2.
查看SERVER_CODE和SERVER_MSG
3.
确认UserID和MediaExtra格式正确
4.
MediaExtra仅支持单层JSON对象
Q: 如何保证奖励发放的安全性?
A:
1.
使用服务端奖励验证
2.
在后台配置回调URL
3.
验证回调签名
4.
根据verify参数判断是否发放

10.5 性能优化#

Q: 如何减少广告加载时间?
A:
1.
使用预加载模式
2.
在合适的时机提前请求
3.
使用缓存机制
4.
避免频繁创建和销毁
Q: 如何避免内存泄漏?
A:
1.
在Activity/Fragment销毁时调用destroy()
2.
及时移除广告视图
3.
避免持有Activity引用
4.
使用弱引用处理回调

附录#

A. 错误码说明#

错误码范围说明
1000-1999SDK内部错误
2000-2999网络错误
3000-3999广告素材错误
4000-4999参数错误
5000-5999广告位配置错误

B. 技术支持#

C. 版本更新日志#

D. 参考#

(GroMore)[https://www.csjplatform.com/union/media/union/download/detail?id=161&docId=27722&locale=zh-CN&osType=android]

文档版本:v1.2.0
更新日期:2026-06-29
适用SDK版本:v2.1.0+
修改于 2026-08-31 06:35:19
上一页
onemore 鸿蒙对接文档
下一页
一盟广告 iOS SDK接入文档
Built with