Add TapADN auto loading strategy report

TapADN自动加载策略分析报告.md

@@ -0,0 +1,121 @@
+# TapADN 自动加载策略分析报告
+
+## 结论先行
+
+当前 `Commercialization.tapadn` 的 auto 接入调用了 TapADN / Dirichlet 官方 Unity SDK 提供的 Android auto-ad API，接口使用方向是正确的：激励视频走 `ShowRewardVideoAutoAd`，插屏走 `ShowInterstitialAutoAd`，开屏走 `ShowSplashAutoAd`，激励视频额外按 SDK 注释使用 `PreLoad(request, 3)`。
+
+但不能把 TapADN 的 auto 与 TopOn 的全自动加载视为同一种能力。TopOn 的 auto 是一套更完整的广告位请求维护方案，包含广告位注册、真实 ready 查询、场景进入统计、缓存状态统计和自动续载；TapADN 当前 Unity wrapper 暴露的是“加载 + 展示合并”的 auto show API，没有看到类似 `entryAutoAdScenarioWithPlacementID` 的场景入口，也没有看到 auto ready 查询 API。
+
+因此，生产默认策略建议调整为“激励视频可优先 auto，但插屏和开屏建议默认手动或由项目配置显式开启 auto”。如果为了兼容当前模块和快速调试继续保留 auto 默认值，也应该在正式项目配置里显式写清楚每个广告类型的选择，避免项目层误以为 `IsReadly()` 表示真实填充可展示。
+
+## 问题定义
+
+这次校对的核心不是“auto API 能不能调用”，而是要判断它是否适合作为 IAA 游戏商业化模块的默认策略：
+
+* IAA 游戏的收益优化通常不是按广告类型粗放处理，而是按广告场景处理，例如复活、翻倍奖励、关卡结束、失败结算、返回大厅、冷启动开屏。
+* 顶部聚合平台的自动加载能力通常还承担缓存命中、场景到达率、展示率和频控策略的统计基础。
+* 若 SDK auto 只能在 show 时兜底加载，业务侧把它当作“已准备好”会引入延迟、失败回调、误展示时机和广告场景数据缺失。
+
+## 当前 TapADN 实现状态
+
+当前模块默认配置位于 `Assets/Tapadn_Adapter/Runtime/Scripts/TapadnControllerOptions.cs`：
+
+* `RewardedAutoLoad = true`
+* `InterstitialAutoLoad = true`
+* `SplashAutoLoad = true`
+* `RewardedPrewarmOnInit`、`InterstitialPrewarmOnInit`、`SplashPrewarmOnInit` 默认为 `false`
+
+三个播放器的 auto 分支行为如下：
+
+* 激励视频：`LoadAD()` 中调用 `PreLoad(request, 3)`；`ShowAD()` 中调用 `ShowRewardVideoAutoAd(...)`。
+* 插屏：`LoadAD()` 只把本地状态置为可播放；`ShowAD()` 调用 `ShowInterstitialAutoAd(...)`。
+* 开屏：`LoadAD()` 只把本地状态置为可播放；`ShowAD()` 调用 `ShowSplashAutoAd(...)`。
+
+这个实现和 TapADN 当前 SDK wrapper 的能力匹配，但有一个重要语义差异：auto 模式下 `IsReadly()` 实际上只能证明广告位 id 合法，不能证明广告已经填充并可立即展示。激励视频由于有 `PreLoad(type=3)`，缓存命中概率会更好；插屏和开屏在当前 wrapper 中没有对应 preload 能力，show-time 加载的风险更明显。
+
+## TopOn 全自动加载机制对照
+
+`Commercialization.topon` 的设计更接近平台完整自动加载模型：
+
+* 初始化或使用前通过 `addAutoLoadAdPlacementID` 注册广告位。
+* 展示前通过 `autoLoadRewardedVideoReadyForPlacementID` / `autoLoadInterstitialAdReadyForPlacementID` 查询真实 ready 状态。
+* 进入业务广告场景时调用 `entryAutoAdScenarioWithPlacementID(placementId, scenario)`。
+* 手动模式也有 `entryScenarioWithPlacementID(placementId, scenario)`，保证场景到达统计不只绑定 auto 模式。
+
+TopOn 官方文档也明确把全自动加载定义为“一站式请求维护方案”，会根据用户使用状态和广告消耗进度判断下一条广告的预加载和缓存时机，并建议进入可展示广告的业务场景后调用 `entryAdScenario(placementId, scenarioId)` 统计缓存状态。也就是说，用户之前的判断是对的：TopOn 的 auto 不只是少写一次 load，它确实和“广告场景切分 + 缓存状态统计 + 展示决策”绑定在一起。
+
+## TapADN 官方 auto 机制对照
+
+TapADN / Dirichlet Unity 文档对 auto 的描述主要是“加载和展示合并为一次调用，内部自动管理广告缓存；若有可用缓存则立即展示，否则自动加载后展示”。官方文档中：
+
+* 激励视频 `ShowRewardVideoAutoAd` 标注为推荐、Android only。
+* 插屏 `ShowInterstitialAutoAd` 标注为推荐、Android only。
+* 开屏 `ShowSplashAutoAd` 标注为推荐、Android only。
+* 最佳实践仍然写到“在关键节点提前加载广告，展示后及时销毁并重新请求”，以及“结合业务实现频次限制”。
+
+本地 SDK 注释进一步约束了能力边界：
+
+* `PreLoad` 当前只有 type=3，即激励视频，会被 native SDK 处理。
+* iOS auto-ad / preload 在当前 wrapper 中返回不支持或 noop。
+* Android bridge 中为 auto ad 保留了 singleton `DirichletAdNative`，用于保持 native 侧自动广告缓存。
+
+当前接入严格遵循了这些 TapADN API，但没有也不能补出 TopOn 那种场景入口，因为当前 SDK wrapper 没有暴露同类接口。`ADManager.EnterAdScenario(...)` 对 TapADN 玩家侧目前没有平台上报效果，只能作为项目自身策略或日志的入口继续扩展。
+
+## IAA 游戏策略判断
+
+从全球和中国 IAA 游戏的通用经验看，默认策略应该围绕“广告位是否必须确定可展示”和“展示时机是否允许等待”来定：
+
+* 激励视频是用户主动选择，通常用于复活、翻倍、补体力、开宝箱。这里最怕的是用户点击后广告不可用或等待过久，所以按钮是否可点最好来自真实 ready 状态。TapADN auto 可降低接入复杂度，但若 reward 场景价值高，手动 preload + ready gating 更稳。
+* 插屏是非自愿打断，适合关卡间、结算后、自然暂停点。这里最怕误打断、过频和 show-time 卡顿，因此应该由业务频控、冷却和场景判断主导。没有真实 ready 查询时，默认手动更可控。
+* 开屏在中国安卓渠道更常见，但冷启动时长、首屏流失和合规压力都更敏感。若 auto show 触发后再加载，失败或超时都直接影响进主场景体验；生产上更适合手动加载、严格超时和无广告快速进入。
+* 顶级 IAA 调优更关注 placement / scenario 维度，而不是“这个类型是不是 auto”。同一个激励视频，复活、翻倍金币、免费抽奖的 eCPM、转化率和留存影响都可能不同，需要可分桶、可频控、可 A/B。
+
+所以，模块层应该把 auto 当作“TapADN Android 的一种展示通道”，而不是全局商业化策略本身。
+
+## 推荐默认配置
+
+建议在生产项目里按如下方式显式配置：
+
+```text
+tapadn.rewarded_auto_load=true
+tapadn.rewarded_prewarm_on_init=true 或在进入高概率广告场景前主动 LoadAD
+
+tapadn.interstitial_auto_load=false
+tapadn.interstitial_prewarm_on_init=false
+
+tapadn.splash_auto_load=false
+tapadn.splash_prewarm_on_init=false
+```
+
+如果项目追求快速接入、广告位较少、可以接受展示时等待，则可以短期保持当前三类 auto 默认开启。但正式灰度前至少应完成以下验证：
+
+* auto 模式下点击激励按钮到 `OnAdShow` 的延迟分布。
+* auto 模式下 show fail、load fail、close、reward verify 是否都被 `ADManager` 收口。
+* 插屏在自然断点触发时是否会出现明显等待、黑屏或重复请求。
+* 开屏失败或无填充时是否能按产品要求进入主场景。
+* 每个业务广告场景是否有自己的埋点、频控和远程配置。
+
+## 当前实现评价
+
+当前 TapADN auto 接入本身是合规且完整的 API 级接入，但默认策略偏激进。它适合样例工程、快速调试和 Android 单平台验证；对于正式 IAA 游戏商业化，建议把默认认知改成：
+
+* TapADN auto 负责“SDK 内部 load + show + 缓存复用”。
+* 项目商业化策略仍然负责“场景进入、ready gating、频控、冷却、奖励发放、A/B 分桶和兜底路径”。
+* TopOn 的 auto 与 TapADN 的 auto 不等价，不能直接迁移 TopOn 的策略假设。
+
+如果后续希望补齐 TopOn 风格的体验，可以在 `CC-Framework.Commercialization` 或 TapADN adapter 上层加一个本地策略层：
+
+* `scenario -> ad type -> slot id/config` 映射。
+* 每场景冷却、每日次数、会话次数、首局保护、新用户保护。
+* 自有 `EnterAdScenario` 埋点，不依赖 SDK 是否支持场景 API。
+* 对 TapADN auto 模式记录 show 请求、show 成功、show 失败、奖励验证和关闭，用数据判断是否继续 auto。
+
+## 参考资料
+
+* [Dirichlet 聚合 SDK Unity 接入文档](https://ssp.dirichlet.cn/docs/dirichlet-mediation-sdk/dirichlet-mediation-sdk-guide-unity/)
+* [TopOn Fully automatic loading](https://help.toponad.net/docs/Fully-automatic-loading)
+* [TopOn 全自动加载激励视频](https://help.toponad.net/cn/docs/Xactf8)
+* [Google AdMob interstitial implementation guidance](https://support.google.com/admob/answer/6066980?hl=en)
+* [Google AdMob recommended interstitial implementations](https://support.google.com/admob/answer/6201350?hl=en)
+* [Google AdMob frequency capping](https://support.google.com/admob/answer/6244508?hl=en)
+* [Unity LevelPlay placement best practices](https://docs.unity.com/grow/levelplay/platform/best-practices/placement)