概览

文档版本 v1.0.0

本页对应 SDK 1.0.0，与离线包 docs/ 目录里的同一份文档内容一致。其他版本见文档中心。

AdMix 是一套 Android 广告聚合 SDK：端上一个 SDK 聚合多家广告平台，投放策略在平台后台配置后 下发到端上生效。接入方只提供两个凭证，其余全部由平台下发。

当前支持 穿山甲（GroMore 通道） 与 优量汇 两家广告平台，三种广告位：开屏 / 激励视频 / Banner。 仅 Android。

平台能力

能力	说明
竞价 + 瀑布混合调度	并行请求竞价位取最高价，再按预估价降序遍历瀑布层；竞价价高过当前层就不再往下请求，并向参与方回传竞胜 / 竞败结果
三种广告位共用一套引擎	调度引擎对广告类型无感知，开屏 / 激励视频 / Banner 走同一套流程
策略下发，改动不发版	各广告平台的应用 ID 与广告位 ID、底价、超时、瀑布顺序、缓存参数全部由配置服务下发，SDK 侧没有本地写入口
按需集成	只接一家就只引那一个适配器，另一家连同它的广告 SDK 都不进包；服务端按端上实际能力裁剪下发内容
预加载与缓存池	命中缓存时加载回调 0 等待，支持自动补位、过期主动销毁
广告事件与埋点	SDK 自动采集广告维度事件出报表，另提供可选的事件回调接进接入方自己的数据平台
激励视频服务端发奖验证	广告平台回调经平台验签后，用应用的 AppSecret 签名转发到接入方的接收地址
合规两段式初始化	init() 只读本地配置、不联网不采集；start() 才初始化各广告平台的 SDK，必须在用户同意隐私政策之后
混淆开箱可用	R8 规则随 aar 自动生效，接入方无需编写任何 -keep

环境要求

项	要求
平台	仅 Android
minSdk	25（Android 7.1.1）
compileSdk	34
JDK	17
AGP	8.x
语言	纯 Java API，Kotlin 工程直接调用，无需适配层

最低支持 Android 7.1.1

配置服务 https://api.maemi.cn 使用 Let's Encrypt 证书，证书链最终锚定在 ISRG Root X1， 而 Android 7.0（API 24）及以下的系统证书库里没有这个根证书，HTTPS 握手直接失败， 拉不到配置也就出不了广告。

宿主 App 的 minSdk 低于 25 时 Gradle 合并清单会报错，需要把宿主的 minSdk 提到 25。

调度流程

1. 并行请求全部竞价位，等待 bidding_timeout_ms
2. 取其中实时价格最高的一个
3. 按预估价从高到低遍历瀑布层：
   • 竞价价 ≥ 当前层预估价 → 直接采用竞价结果，剩余层不再请求
   • 否则请求该层，成功则与竞价结果比价取高者，失败则继续往下探
4. 向参与竞价的广告平台回传竞胜 / 竞败结果

所有回调都在主线程，接入方不需要自己切线程。价格单位统一为分（1500 = 15 元 eCPM）。

调度参数（超时、预估价、瀑布顺序）由平台运营在后台配置，取值口径见《策略配置格式》。

名词解释

三种「位」的区分

这三个是不同层级的东西，混用会直接导致无填充或对账错位。

层级	术语	谁使用	形态
平台侧的广告展示位	广告位 / 广告位标识	接入方写进代码	unit_id，如 reward_main，格式 ^[a-z0-9_]{3,32}$
广告平台侧的广告位	平台广告位 ID	平台运营在后台录入，由配置服务下发	穿山甲 10 开头 9 位、优量汇 16 位
GroMore 瀑布流内部的一行	穿山甲后台叫「代码位 ID」	平台不使用	如 989026797

不要把 GroMore 的「代码位 ID」当成平台广告位 ID

穿山甲后台有两层 ID：「应用管理」页的广告位 ID（10 开头）是平台登记并下发的那个； 点进去之后「瀑布流管理」里每一行的代码位 ID 是 GroMore 内部的，平台不使用。

填错的表现是 602 未知异常，错误信息毫无指向性。

广告位标识建后不可改，也没有任何接口能改它。 它同时在接入方的代码里和报表的维度键上， 改一次意味着那一版 App 直接没广告且必须重新发版，历史数据还会在报表里裂成两行。 需要换就新建一个广告位。

三类凭证

凭证	从哪来	能进 APK
AppID	管理后台创建应用时生成	能。它只是身份标识，不是密钥
App 密钥	管理后台「应用管理 → 接入」，每个应用各自一套	需要进。SDK 用它给请求签名，密钥本身不随请求发送
AppSecret	管理后台生成，只显示一次	绝对不能。只用于接入方服务器与平台之间的验签

详见《配置与凭证》。

竞价位与瀑布层

术语	含义
竞价位	请求时由广告平台实时给出价格的广告源，参与竞价并接收竞胜 / 竞败回传
瀑布层	价格来自后台配置的预估价，按价格降序被请求

穿山甲侧走 GroMore 通道，竞价在 GroMore 内部完成，配置里按瀑布层对待。

穿山甲侧走的是 GroMore 聚合通道

这一点影响配置怎么填、报表怎么看，接入前需先了解。

穿山甲已将「基础变现」并入 GroMore 并停止受理基础变现的开通申请，账号里创建的广告位 「是否用于 GroMore」一律是「是」，这类广告位只在聚合场景下返回广告。因此穿山甲适配器 以 GroMore 模式接入（useMediation(true)），由此带来三点：

项	说明
配置里填什么	平台广告位 ID 填 GroMore 广告位 ID（后台「应用管理」页，10 开头），不是瀑布流里的代码位 ID
广告从哪来	广告平台标识是 csj，但真正出广告的是 GroMore 瀑布流里的某一家（穿山甲 / 快手 / 百度 / Sigmob）。当前策略是瀑布流里只配穿山甲一家
谁在竞价	竞价由 GroMore 内部完成，SDK 不再向穿山甲回传竞胜 / 竞败。配置里 bidding 对 csj 不起作用，填 false

穿山甲后台必须配两步，缺一不可

先在「应用管理」建广告位，再在「瀑布流管理」里给这个广告位添加代码位。 只建广告位不配瀑布流会直接无填充，且错误信息只说「全部代码位请求失败」，看不出是漏配。

详见《策略配置格式》「穿山甲后台配置」。

埋点要记真实广告来源时，用 getAdnSourceName()：

rewardAd.getAdnType();        // "csj" —— 走哪条聚合通道
rewardAd.getAdnSourceName();  // "pangle" / "ks" / "baidu" / "sigmob" —— 真正出广告的那一家

该值在广告展示后最完整（部分广告位在加载回调阶段还取不到），埋点建议在 onAdShow 时读。 SDK 自己的埋点已经在采集它（AdEvent.adnSource，见《数据与事件》），接入方接事件回调即可， 不需要在每个 onAdShow 里补一遍。

对外 API 的范围

只使用文档列出的类和方法：AdMix、AdMixConfig、AdError、AdnType、 com.admix.api 下的广告类与监听器、AdPreloader.PreloadListener、 AdEvent / AdEventListener / AdEventType。

其余类（com.admix.adapter、cache、config、mediation、util 等包及各适配器的实现类） 是 SDK 内部实现，标注了 @RestrictTo，在宿主代码里直接调用时 Android Studio 会标红、 lint 报 RestrictedApi 错误。这些内部类随版本随时变化，不保证兼容。

两条固定约定：

• 不返回真实 eCPM，也不返回平台广告位 ID。onAdLoaded(adnType) 只给广告平台名称， AdEvent 里没有价格字段，release aar 的日志里这两项打 ***
• 配置字段只增不删。SDK 逐个键取值、忽略不认识的键，所以平台加字段对老版本 SDK 是安全的； 需要新版 SDK 才支持的能力由服务端按「最低 SDK 版本」裁剪后再下发，不需要在 App 里做判断。 对外 API 的破坏性改动会升主版本号并写进《更新日志》

文档导航

文档	什么时候看
《快速开始》	第一次接入，先跑通第一个广告
《引入依赖》	依赖坐标、版本锁定、清单合并冲突、按需集成单家、离线包
《初始化》	两步初始化、可选项、按需初始化、Kotlin 写法、日志排查
《开屏广告》《激励视频广告》《Banner 广告》	逐个广告位的完整接法与各自特有的注意事项
《预加载与缓存》	想降低加载耗时、提高开屏填充率
《服务端对接》	激励奖励有现金价值，需要服务端发奖验证
《配置与凭证》	凭证怎么管、配置什么时候生效、拉不到配置怎么查
《策略配置格式》	配价格、超时、瀑布顺序（平台运营看这份）
《数据与事件》	埋点口径、把广告事件接进自己的数据平台
《合规与隐私》	写隐私政策、做 SDK 自查
《金融类 App 合规清单》	上架应用商店前
《错误码参考》	拿到一个错误码，查它是什么、怎么办
《常见问题》	按现象查：没广告、白屏、包体积、报表对不上
《更新日志》	升级前确认有没有影响接入方行为的改动