Add TapADN smart preload attribution

2026-06-05 21:44:35 +08:00
parent c21bdec3fe
commit fd98a7f541
48 changed files with 9441 additions and 18 deletions
--- a/README.md
+++ b/README.md
@@ -83,10 +83,56 @@ ADManager.Instance.Init(callback, userId, adConfig, new TapadnAdController());
 * `tapadn.splash_max_load_attempts`
 * `tapadn.splash_load_retry_delay_ms`
 * `tapadn.splash_show_timeout_ms`
+* `tapadn.smart_preload_enabled`（开启智能预加载策略）
+* `tapadn.smart_preload_config_json`（智能预加载静态配置 JSON）
+* `tapadn.smart_preload_config_asset_path`（预加载策略资源表路径，默认 `TapadnSmartLoadPolicy_Default`）
+* `tapadn.smart_preload_remote_json`（远端覆盖配置 JSON，按场景覆盖静态配置）
 * `tapadn.express_width`
 * `tapadn.express_height`

-默认激励、插屏、开屏都使用 TapADN Android auto-ad 接口。若遇到渠道缓存策略差异，可将对应 `*_auto_load` 设为 `false`，切换为手动 load/show。
+默认激励、插屏、开屏都使用手动 load/show；如无特殊策略验证需求，不建议开启 auto-ad。若要做 auto-ad AB 测试，再将对应 `*_auto_load` 设为 `true`。
+
+### 智能预加载（实验）
+
+默认会按“场景进入次数 + 场景播放请求次数”维护一个小样本统计：
+
+* 进入场景时记录 `EnterCount`
+* `AsyncPlayAD` 执行前调用的 `OnPlayRequestStarted` 记录 `PlayRequestCount`
+* 按置信加权算法推算场景播放概率，达到阈值后触发 `ADManager.LoadAD` 预加载
+* 预加载归因按“全局广告类型缓存”记录：触发场景记录 `preload_request/success/fail`，实际播放场景记录 `show/immediate/smart_cache_hit`
+* 当 A 场景触发的全局缓存在 B 场景展示时，A 会记录 `smart_preload_consumed_other_scene`，B 会记录 `smart_cache_cross_scene_hit`
+
+配置 JSON 示例（可通过 `CommonKeyValues` 下发）：
+
+```json
+{
+  "GlobalDefault": {
+    "AdType": -1,
+    "Scene": "__default__",
+    "BaseProbability": 0.08,
+    "PreloadThreshold": 0.75,
+    "CooldownSeconds": 120,
+    "MinSamplesForConfidence": 8,
+    "DecayHalfLifeHours": 72
+  },
+  "ScenePolicies": [
+    {
+      "AdType": 0,
+      "Scene": "reward_debug",
+      "BaseProbability": 0.6,
+      "PreloadThreshold": 0.5,
+      "CooldownSeconds": 60,
+      "MinSamplesForConfidence": 4,
+      "DecayHalfLifeHours": 48
+    }
+  ]
+}
+```
+
+说明：
+* `AdType` 使用 `AD_Type` 枚举值：`0=AwardVideo`, `1=Splash`, `2=Interaction`
+* `Scene` 用于和 `ADManager.EnterAdScenario` 的场景名对齐；场景未命中时回退到对应广告位的默认场景配置。
+* `ExportSnapshotCsv()` 会额外导出 `immediate_hit`、`smart_cache_hit`、`smart_preload_consumed`、`smart_preload_expired` 等列，用于区分“哪个场景触发预加载”和“哪个场景最终消费缓存”。

 ## Android 构建

@@ -100,3 +146,34 @@ ADManager.Instance.Init(callback, userId, adConfig, new TapadnAdController());
 * `android.useAndroidX=true` 与 `android.enableJetifier=true`。

 包内不默认暴露可视化编辑面板；调试样例通过 `Samples~` 作为可选导入内容。
+
+## 智能预加载敏感度验收（默认次留 35%）
+
+本模块包含一套本地仿真脚本，用于模拟 IAA 场景下不同 `PreloadThreshold` 与 `CooldownSeconds` 的收益差异，输出完整 CSV 与变化曲线。
+
+默认次留基线设置为 `35%`（你可以改保留率列表），默认模型参数位于 `Assets/Tapadn_Adapter/Runtime/Resources/TapadnSmartLoadPolicy_Default.json`。
+
+```bash
+python Tools/SmartLoadSensitivity/smartload_sensitivity_simulation.py --users 5000 --out-dir Tools/SmartLoadSensitivity/output
+```
+
+输出文件（可复现）：
+
+* `Tools/SmartLoadSensitivity/output/smartload_sensitivity_summary.csv`
+* `Tools/SmartLoadSensitivity/output/smartload_retention_rank.csv`
+* `Tools/SmartLoadSensitivity/output/TapADN_智能预加载_敏感度验收报告.md`
+* `Tools/SmartLoadSensitivity/output/*.png`（热力图和曲线）
+
+重点图示（`TapADN_智能预加载_敏感度验收报告.md` 中已自动嵌入）：
+
+* `heatmap_immediate_r_0.35.png`（次留 35% 下的即时命中率）
+* `heatmap_wait_ms_r_0.35.png`（次留 35% 下的平均等待时延）
+* `heatmap_waste_ratio_r_0.35.png`（次留 35% 下的 waste 率）
+* `line_immediate_vs_retention.png`（留存与即时命中率关系）
+* `line_wait_vs_retention.png`（留存与等待时延关系）
+
+你也可以直接查看部分曲线对比：
+
+![Immediate vs retention](Tools/SmartLoadSensitivity/output/line_immediate_vs_retention.png)
+![Wait vs retention](Tools/SmartLoadSensitivity/output/line_wait_vs_retention.png)
+![Heatmap immediate 35%](Tools/SmartLoadSensitivity/output/heatmap_immediate_r_0.35.png)