Adapter 集成

KeyPuff 的客户端分发由两部分组成：

• 核心 SDK：与 KeyPuff 服务端通信、拉取聚合策略、调度多渠道比价，不含任何渠道 SDK；
• 渠道 adapter：对接各广告平台（ADN）SDK 的桥接层，核心 SDK 通过它加载、展示渠道广告。

App 只需集成核心 SDK 与实际参与分发的渠道 adapter。每个应用需要集成的依赖行（含版本号）由控制台「SDK 中心」按应用生成，核心规则：

1. 依赖行取该平台最新已发布版本的 core 与渠道 adapter；
2. 已排除该应用登记的自接渠道（见下文重要规则）；
3. 近 30 天平台新增的渠道会在 SDK 中心标记为「新增」，集成后流量才会进入该渠道。

渠道清单

KeyPuff 现行支持的广告渠道：

渠道	说明
倍业 Mercury	平台自有聚合底层渠道
优量汇 GDT	腾讯广告
穿山甲 CSJ	字节跳动
百度	百度百青藤
快手	磁力聚星
阿里 Tanx	阿里妈妈
OPPO	OPPO 广告
TapTap	好游快爆 / TapTap
Sigmob	Sigmob 广告
华为	华为广告（Petals）
小米	小米广告
vivo	vivo 聚效
荣耀	荣耀广告

各渠道 adapter 在 iOS / Android / 鸿蒙三端的可用性不同，以控制台「SDK 中心」按您的应用与平台列出的为准。此外平台支持接入自定义渠道（渠道 ID 从 90001 起）。

重要规则：同一渠道不能双入口

同一广告渠道（ADN）不能既由开发者自接、又经 KeyPuff 接入。

• 登记应用时，请如实填写 App 已自接的广告 SDK 渠道；
• 平台不会为该应用配置这些渠道，SDK 中心也不会列出对应的 adapter；
• 若后续您移除了某个自接渠道，请联系客户经理更新应用登记，平台即可为该应用配置该渠道；
• 双入口会导致同一渠道内竞价冲突、报表归属混乱，属于违约行为，可能影响结算。

集成步骤

1. 在控制台「SDK 中心」选择应用，复制核心 SDK + 全部所需渠道 adapter 的依赖行；
2. 粘贴到工程依赖配置（iOS CocoaPods / Android Gradle / 鸿蒙 ohpm），执行安装；
3. 各渠道 SDK 自身的隐私合规配置（如 OAID 开关）同样适用，见 SDK 合规接入指引；
4. 发版后可在控制台报表确认各渠道流量是否正常进入。

各端初始化与广告格式代码见：iOS / Android / 鸿蒙。

自定义渠道

自定义渠道的 adapter 由接入方自行开发并打包进 App：服务端按应用下发各广告格式的 adapter 类名，SDK 反射加载。接入前请联系客户经理登记类名。

• Android 类名必须以 com.advance.supplier. 开头（例如 com.advance.supplier.yourcompany.YourSplashAdapter）。SDK 会给不带该前缀的类名补前缀，导致找不到类、无法出广告。iOS 无此限制。

• 初始化类必须返回非空的 SDK 版本号：Android 实现 getSDKVersion()，iOS 实现类方法 +sdkVersion（未实现即不上报），鸿蒙覆写静态方法 getSDKVersion()（基类默认返回空串）。SDK 以 custom_<渠道ID>_v 随广告请求上报该值，服务端据此判断 App 是否集成了该渠道；值为空时该渠道的广告源会被跳过。

• Android 首次安装后的第一次启动需要先拉取配置。 SDK 在 initSDK 时登记各渠道的初始化类，而自定义渠道配置要在初始化之后才异步拉取；首次安装时本次启动内自定义渠道全部失败（错误码 999），下次启动才恢复。请在初始化前处理：

  1. 在子线程同步请求 <SDK 服务地址>/custom_adn?appid=<appid>（地址与 SDK 的策略请求同域，appid 与 initSDK 传入的一致）；
  2. 把响应中的 custom_adn_list 逐项转成 com.advance.model.AdvanceCustomADNModel，写入 AdvanceConfig.getInstance().customADNList；
  3. 再调用 AdvanceSDK.initSDK(...)。请求失败时直接初始化即可（SDK 会使用上次缓存的配置）。

  字段对应：

  响应字段	AdvanceCustomADNModel 字段
  id	sdkID
  name	sdkName
  custom_config_adapter	initClzName
  custom_splash_adapter	splashClzName
  custom_banner_adapter	bannerClzName
  custom_interstitial_adapter	interstitialClzName
  custom_rewardvideo_adapter	rewardClzName
  custom_nativeexpress_adapter	nativeExpressClzName
  custom_renderfeed_adapter	nativeCustomClzName