Commercialization.tapadn/Assets/SDK_MAINTENANCE.md

TapADN SDK 封装维护说明

本文记录 Commercialization.tapadn 对官方 Dirichlet/TapADN 聚合 SDK 的封装、改动和升级注意事项。维护或升级 SDK 时先读本文，再改文件。

当前 SDK 版本

官方链接：

• 资源下载页：https://ssp.dirichlet.cn/docs/resource-download/
• 聚合 Unity 接入文档：https://ssp.dirichlet.cn/docs/dirichlet-mediation-sdk/dirichlet-mediation-sdk-guide-unity/
• 聚合 Android 接入文档：https://ssp.dirichlet.cn/docs/dirichlet-mediation-sdk/dirichlet-mediation-sdk-guide-android/

范围	当前版本	来源	说明
Unity 聚合 SDK	4.2.5.0	官方 dirichlet_mediation_unity_4.2.5.0.unitypackage	官方资源页当前仍只提供 Unity 4.2.5.0。
Android 聚合 native AAR	4.2.7.3	官方 dirichlet_ad_mediation_4.2.7.3.zip	已单独升级 Android native 侧。
Android Pangle	7.6.1.2	官方 Android 聚合接入文档	通过 Gradle 后处理注入 Maven 依赖。
Android GDT	4.690.1560	官方 Android 聚合接入文档	通过 Gradle 后处理注入 Maven 依赖。
iOS 聚合 SDK Pod	4.2.0.1	官方 iOS 聚合版本	默认值在 DirichletMediationIOSPostProcessor，可用环境变量覆盖。

模块结构

路径	归属	维护说明
Assets/DirichletMediation	官方 Unity SDK 基础层	不再视为纯官方源码，部分文件已有本地改动。
Assets/Plugins/Android/DirichletMediation	官方 Android Unity bridge + native AAR	Java bridge 当前与官方 Unity 包一致；AAR 已升级到 Android native 4.2.7.3。
Assets/Plugins/Android/libs	Android 本地依赖	保留 iadsdk-release-2.3.102.110.aar；Pangle/GDT 不再放本地 AAR，改由 Maven 注入。
Assets/Tapadn_Adapter	本模块封装层	对接 CC-Framework.Commercialization，不要让业务层直接调用官方 SDK。
Assets/Samples~	可选调试样例	不是官方 sample，是本模块验证 ADManager 流程的样例。

官方源码改动清单

以下文件来自官方 Unity SDK，但本仓库已经修改过。升级官方 Unity SDK 时不能直接覆盖，必须三方合并：

文件	本地改动目的
Assets/DirichletMediation/Runtime/DirichletAdTypes.cs	补齐 Unity 侧 ad handle、auto-ad fallback、事件会话保活、IsValid / Destroy 包装等桥接行为。
Assets/DirichletMediation/Runtime/DirichletMediationSdk.cs	增强 Android/iOS/noop bridge、Unity 线程派发、iOS load/init callback receiver 和平台兼容逻辑。
Assets/DirichletMediation/Editor/DirichletGradlePostProcessor.cs	改为适配 Unity 导出的 Gradle 工程，注入仓库、support/glide/okhttp、Pangle/GDT Maven 依赖，避免本地 AAR 重复类。
Assets/DirichletMediation/Editor/DirichletMediationIOSPostProcessor.cs	自动生成 Podfile，处理 UnityFramework target、framework/header search paths、SKAdNetwork、ATT、GDT 动态 framework 嵌入和 CocoaPods 异常兜底。

以下官方文件当前与官方 Unity 4.2.5.0 包一致，升级时可优先直接替换后验证：

文件	说明
Assets/DirichletMediation/Editor/DirichletMediationDependencies.xml	EDM4U 依赖声明。
Assets/Plugins/Android/DirichletMediation/src/main/java/com/dirichlet/unity/DirichletUnityBridge.java	Android Java bridge。
Assets/Plugins/Android/AndroidManifest.xml	官方基础 Manifest。
Assets/Plugins/Android/proguard-user.txt	当前为空文件。

封装层做了什么

Tapadn_Adapter 的目标是让业务项目只面对 ADManager / ADConfig / AD_Type：

1. TapadnAdController 从 ADConfig 和 CommonKeyValues 解析媒体 ID、MediaKey、广告位、渠道、debug、权限、预加载和展示超时配置。
2. TapadnCommercialization 提供创建 controller、初始化 ADManager、创建默认 ADConfig、批量写入激励场景广告位映射的便捷入口。
3. TapadnAdRequestFactory 统一构建 DirichletAdRequest，保证 SpaceId 是正整数，并注入 UserId、奖励名、奖励数量、展示尺寸。
4. TapadnAwardVideoPlayer 对接激励视频。手动 load/show 模式下，按 SpaceId 隔离缓存；展示关闭、展示失败、IsValid == false、或默认 600 秒未消费都会销毁缓存。
5. TapadnInteractionPlayer 对接插屏；TapadnSplashPlayer 对接开屏。两者保持单默认广告位语义。
6. TapadnSmartLoadOrchestrator 维护场景学习数据和智能预加载归因。当前是保守策略：默认不开启；开启后先观察用户点击广告的概率，达到阈值才自动预加载。

场景广告位规则

激励视频支持游戏场景映射不同 SpaceId：

配置 key	示例
tapadn.rewarded_scene_slot.<scene_id>	tapadn.rewarded_scene_slot.level_clear = 200101
tapadn.rewarded_scene_slots	level_clear=200101,daily_bonus=200102
tapadn.rewarded_scene_slots_json	{ "Mappings": [ { "Scene": "level_clear", "SlotId": "200101" } ] }

回退规则：

1. 未传场景、场景为空、场景未配置、配置 SpaceId 非法时，使用 BaseAwardAdKeyValue.value。
2. 如果两个场景配置到同一个 SpaceId，它们共享同一个广告位缓存。
3. 如果 A 场景 SpaceId 已加载但没展示，用户去 B 场景展示 B SpaceId，A 缓存不会被 B 消费；A 会等回到 A 时复用，或超时/失效后销毁。

Android 升级步骤

1. 查官方资源页和聚合 Android 发布记录，确认最新 Android 聚合版本、Pangle 版本、GDT 版本。
2. 下载 dirichlet_ad_mediation_<version>.zip，校验官方 MD5。
3. 替换 Assets/Plugins/Android/DirichletMediation/libs/DirichletAD_*_<version>.aar。
4. 检查官方 Android 接入文档中的 Maven 依赖，更新 DirichletGradlePostProcessor 里的 PangleSdkVersion、GdtSdkVersion。
5. 不要同时保留 Pangle/GDT 本地 AAR 和 Maven 依赖，否则容易出现 duplicate classes。当前策略是 Pangle/GDT 走 Maven。
6. 搜索旧版本号，更新 GLOBAL_DESIGN.md、README.md、CHANGELOG.md 和 Assets/package.json。
7. 至少执行 dotnet build Commercialization.tapadn.sln --no-restore 和 git diff --check。
8. Android 真机构建仍需在消费项目里跑项目自带构建流程验证 Manifest merge、Gradle dependency resolution 和广告展示回调。

Unity SDK 升级步骤

1. 下载官方新的 dirichlet_mediation_unity_<version>.unitypackage 并校验 MD5。
2. 解包到临时目录，对比 Assets/DirichletMediation 和 Assets/Plugins/Android。
3. 对“官方源码改动清单”里的 4 个文件做三方合并，不允许直接覆盖。
4. 官方 sample 不进入默认包；如需要保留调试能力，继续放到 Samples~。
5. 检查 Android Java bridge API 是否和当前 C# bridge 匹配，重点是 load/show/destroy/isValid/auto-ad callback。
6. 检查 iOS Pod 名称和版本是否变化，同步 DirichletMediationIOSPostProcessor 的默认版本和 search path 规则。
7. 重新验证 Android/iOS editor compile；真机展示验证至少覆盖初始化、激励 load/show/close/reward、插屏、开屏、无填充失败。

发布步骤

包根是 Assets/package.json，消费者应使用：

"com.commercialization.tapadn": "http://private.lightyears.ltd:18650/foldcc/Commercialization.tapadn.git?path=/Assets#<version>"

发布命令：

git subtree split --prefix=Assets --branch upm
git tag <version>
git push origin master upm <version>

注意：当前版本 tag 打在完整仓库 master 上，因此消费者必须带 ?path=/Assets。