foldcc/Commercialization.topon

Fork 0

Files

CORE-FOLDCC\Core e38e066a2d release: 1.4.7

2026-04-22 17:44:49 +08:00

16 KiB

Raw Blame History

IAA广告架构重构实施指南

1. 目标

本文档的目标不是讨论“架构是否优雅”，而是以 IAA 收益最大化 为第一原则，对当前广告接入架构进行诊断、排序和重构规划。

核心目标：

提高激励视频和插屏的首播成功率、Ready Rate、Show Rate、Reward Rate。
将当前旧版 load/show/listener 心智升级为新版 Taku/TopOn 的 生命周期 + 自动加载 + 场景统计 + 状态查询 + 策略化调度。
保留业务层统一入口 ADManager，但重做中下层能力和策略层。
把当前“联调环境”和“实际发布包依赖”统一起来，避免版本漂移导致的收益判断失真。

2. 当前架构快照

2.1 运行时主链路

flowchart LR
    A["业务层\nADManager.AsyncPlayAD"] --> B["商业化抽象层\nADPlayer / AsyncAdPlayer"]
    B --> C["平台实现层\nToponAdController / AwardVideoPlayer / InteractionPlayer"]
    C --> D["Unity桥\nATSDKAPI / Rewarded / Interstitial"]
    D --> E["原生桥\nSDKInitHelper / VideoHelper / VideoAutoAdHelper"]
    E --> F["Taku/TopOn 原生 SDK\n微信 / 抖音 / 小程序 / 下载链路"]

2.2 当前仓库角色

抽象层本地源码：Packages/CC-Framework.Commercialization
当前平台实现层：Assets/Topon_Adapter
当前官方 Unity 插件：Assets/AnyThinkPlugin
当前 Android 额外插件与资源：Assets/Plugins/Android

2.3 当前已知版本状态

本地抽象层版本：1.0.12
- 文件：Packages/CC-Framework.Commercialization/Assets/package.json
当前 Topon 包版本：1.4.7
- 文件：Assets/package.json
当前 Topon 包对抽象层的发布依赖是：1.0.12
- 文件同上
当前联调工程和发布依赖已对齐到同一抽象层版本，版本漂移问题已收敛。
Android 接入侧需注意：
- 当前中国区 Gromore/CSJ 组合要求 minSdkVersion >= 24

3. 术语速查

3.1 Placement（广告位）

一个 placement 就是一个固定广告机会点的唯一 ID。
例如：
- 复活激励
- 双倍奖励激励
- 关卡结尾插屏

3.2 Scenario（广告场景）

placement 是固定广告位，scenario 是这次广告触发的业务上下文。
例如：
- revive
- double_coin
- level_fail_exit
它主要用于：
- 漏斗分析
- 场景收益对比
- 定位具体场景的展示问题

3.3 load / ready / show

load：发起请求并缓存广告
ready：当前已有可展示广告缓存
show：真正展示广告

3.4 Auto Load（自动加载）

SDK 自动维护某个 placement 的缓存和补量
更适合高频高价值激励位

3.5 Waterfall（瀑布流）

按优先级依次请求广告源
优先级和广告源配置主要在后台控制

3.6 Bidding（竞价）

广告源实时回传价格
平台再选择最优广告展示

3.7 eCPM

每千次展示收益
是重要指标，但不能脱离：
- Ready Rate
- Show Rate
- Fill Rate
- Reward Completion 单独看

3.8 Fill Rate（填充率）

发起请求后，最终拿到可展示广告的比例

3.9 Show Rate（展示率）

已到达广告场景或已请求后，最终真正展示成功的比例

3.10 Impression（展示）

广告真正展示给用户一次
收益通常基于展示结算，而不是基于请求结算

3.11 Report API

广告平台收益与展示数据接口
用于自动价格、收益归因、Waterfall 对账和优化

3.12 Local Extra / Custom Map

local extra：请求级参数，通常带用户透传、业务信息
custom map：初始化级参数，通常带渠道、用户分组、实验标记

3.13 为什么“预加载影响 eCPM”是旧命题

旧时代常说“不要太早 load，会伤 eCPM”
现在更准确的说法是：
- 问题不在预加载本身
- 问题在于是否 策略化预热
真正影响收益的是：
- 预热时机不对
- placement 太多
- 长时间不展示
- 后台策略和客户端行为脱节

4. 官方推荐生命周期

4.1 推荐调用顺序

sequenceDiagram
    participant App as App启动
    participant Privacy as 隐私同意
    participant SDK as Taku SDK
    participant Policy as 客户端策略层
    participant Game as 广告业务逻辑

    App->>Privacy: 展示隐私协议
    Privacy-->>App: 用户同意
    App->>SDK: ATSDK.init(...)
    App->>SDK: ATSDK.start()（中国区）
    App->>Policy: 注册核心placement自动加载/预热
    Game->>Policy: 到达广告场景 entryScenario
    Policy->>SDK: ready/status 检查
    alt 已ready
        Policy->>SDK: show
    else 未ready但在容错窗口
        Policy->>SDK: 短等待 / 补偿重试
    else 超时
        Policy-->>Game: 播放失败
    end

4.2 推荐自动调用的动作

这些动作建议由底层 provider 自动做掉，而不是依赖业务层自己记忆：

中国区 ATSDK.start()
核心激励位注册 auto load
启动后预热高价值 placement
核心 placement 的诊断日志与状态快照
show start 后安排下一轮预热
首轮失败进入短重试窗口

4.3 业务层不应该感知的内容

以下内容应由策略层 / 平台层封装：

placement 是否自动加载
何时预热
是否可以等待更高价缓存
冷启动是否容许重试
微信/抖音/小程序/下载的具体差异

5.1 当前已接入的策略 Key（第二阶段）

目前已在 ToponControllerOptions 中接入的高收益策略 key：

topon.rewarded_auto_load
- 是否开启激励自动加载
- 当前建议默认：true
topon.rewarded_prewarm_on_init
- 初始化后是否自动预热激励位
- 当前建议默认：true
topon.rewarded_max_load_attempts
- 单次播放请求允许的最大加载尝试次数
- 当前建议默认：3
topon.rewarded_load_retry_delay_ms
- 激励首次失败后的短补偿等待时间
- 当前建议默认：1000
topon.interstitial_auto_load
- 是否开启插屏自动加载
- 当前建议默认：true
topon.interstitial_prewarm_on_init
- 初始化后是否自动预热插屏位
- 当前建议默认：true
topon.interstitial_max_load_attempts
- 单次插屏播放请求允许的最大加载尝试次数
- 当前建议默认：2
topon.interstitial_load_retry_delay_ms
- 插屏首轮失败后的短补偿等待时间
- 当前建议默认：500
topon.local_strategy_asset_path
- Android 本地策略资源路径
topon.auto_open_debugger_ui
- 是否在初始化后自动打开官方 DebugUI
- 当前建议默认：false

适用方式：

通过 ADConfig.CommonKeyValues
或通过 ToponControllerOptions
或额外传入 IDictionary

推荐默认示例：

topon.rewarded_auto_load=true
topon.rewarded_prewarm_on_init=true
topon.rewarded_max_load_attempts=3
topon.rewarded_load_retry_delay_ms=1000
topon.interstitial_auto_load=true
topon.interstitial_prewarm_on_init=true
topon.interstitial_max_load_attempts=2
topon.interstitial_load_retry_delay_ms=500
topon.auto_open_debugger_ui=false

调试说明：

topon.debug=true
- 当前只用于开启 SDK 调试日志
- 不再默认自动弹出官方 DebugUI
官方 DebugUI 建议在真机样例或专用调试入口中手动打开

5. 官方最新 SDK 能力，与当前项目的差距

结合官方文档和当前插件/反编译结果，当前 Taku/TopOn 体系已经具备以下关键能力，但当前项目没有充分利用：

3.1 `ATSDK.start()`

官方中国区 SDK 初始化文档要求 ATSDK.init(...) 后建议调用 ATSDK.start()。
反编译验证：ATSDK.start() 在当前 anythink_core 中真实存在，且是无参静态方法。
当前缺陷：
- ToponAdController 只调了 ATSDKAPI.initSDK(...)
- Unity 壳 ATSDKAPI.cs 没有暴露 start

3.2 自动加载能力

已有能力：
- ATRewardedAutoVideo
- ATInterstitialAutoAd
当前缺陷：
- 当前 AwardVideoPlayer / InteractionPlayer 仍是手工状态机模式
- 没有利用自动加载做高频 placement 的持续预热

3.3 状态查询能力

已有能力：
- hasAdReady
- checkAdStatus
- getValidAdCaches
当前缺陷：
- 未接入策略层
- 无法做“软等待”“缓存质量判断”“首轮失败补偿”

3.4 广告场景统计能力

官方推荐使用 entryAdScenario 做漏斗分析
当前缺陷：
- adScene 只在 show 阶段透传
- 没有将“用户到达广告机会点”单独建模

3.5 本地策略能力

官方原生 SDK 有 ATSDK.setLocalStrategyAssetPath(...)
当前缺陷：
- Unity 壳没暴露
- 客户端无法加载本地预置策略

3.6 流量分组 / 规则能力

当前已接的弱能力：
- channel / sub_channel
- custom_map
- placement custom data
当前缺陷：
- 只是透传，不是可运营的“收益策略层”

6. 现有问题，按收入影响从大到小排序

P0. 首播请求容错太差，直接损失收入

表现：

激励视频第一次点击经常失败
冷启动期首轮加载不稳定

根因：

AsyncAdPlayer 仍是“单次播放只给一次首轮 load 机会”
首次 load 比后续 load 多做了一层 VideoHelper / ATRewardVideoAd 初始化
冷启动期没有任何“延迟补偿 / 软等待 / 重试窗口”

影响：

直接损失首播展示
高价值激励点收益打折
拉低用户广告可接受度和视频完成率

P1. 高价值 placement 没有自动加载，Ready Rate 偏低

表现：

核心激励位依赖点击时加载
就绪完全由手工 load 时机决定

影响：

展示机会点到来时，经常没 ready
收入天花板偏低

P2. 没有完整接入场景统计，无法做精细化收益调优

影响：

无法准确判断问题在“场景设计”还是“缓存策略”
客户端和后台漏斗对不上

P3. 生命周期抽象过粗，不适配新版 SDK

表现：

init 被调用 != 广告系统真正 ready
当前实现无法表达 start、本地策略、自动加载启动等生命周期

P4. 插屏回调链本身存在缺陷

表现：

InteractionPlayer.ShowAD(...) 没接 onClose/onVideoComplete
onInterstitialAdFailedToShow 等回调是空实现

影响：

插屏统计、重试、展示完成事件不可靠

P5. 版本漂移导致实验结果不可信

表现：

本地抽象层、联调工程、发布依赖三个版本不统一

影响：

本地验证表现无法可信映射到业务项目

7. 对“预加载影响 eCPM”的判断

这是一个 旧时代常见结论，但今天已经不能直接这么说。

更准确的说法是：

无脑预加载本身不是收益最优策略
但“预加载会直接伤 eCPM”这个说法过于粗暴，已经过时

当前更合理的理解：

预加载是 IAA 的基础能力，不做高价值位预热，收入上限一定低。
问题不在“要不要预加载”，而在“何时预加载、预加载多少、多久不展示视为无效”。
真正会伤收益的不是“有预加载”，而是：
- 预热过早
- 长时间不展示
- placement 太多导致缓存浪费
- 高价值场景没有拿到新鲜缓存
- 客户端策略和后台 Waterfall 配置脱节

最优结论：

高价值高频位：必须预热，甚至自动加载
中频位：场景前置预热
低频位：Just-in-time load + 短等待容错
插屏：策略化预热，不建议全局常驻缓存所有位

8. 最优指南：面向 IAA 的广告策略

6.1 激励视频

推荐策略：

核心激励位默认使用自动加载
启动后预热
用户进入关键广告场景时调用 entryAdScenario
播放前先读 ready/status
首次失败给短重试窗口，不要直接判死
onRewardedVideoAdPlayStart 后立即安排下一轮预热

6.2 插屏

推荐策略：

重要插屏位可使用自动加载
低频插屏采用场景前置预热
插屏失败要完整上报 show fail 和 close 结果
插屏不应该沿用激励的奖励回调模型

6.3 后台协同

推荐策略：

开启报表 API
配置自动价格
做流量分组
用 A/B 测试验证：
- 自动加载 vs 手工加载
- 启动预热 vs 场景预热
- 软等待 0/300/800ms

8.4 常见产品策略方式

策略 A：核心激励常驻预热

适用：
- 复活激励
- 双倍奖励激励
特点：
- 就绪率高
- 收入稳定

策略 B：场景前置预热

适用：
- 结算页激励
- 阶段性插屏
特点：
- 更省请求
- 更接近真实展示时机

策略 C：点击兜底加载 + 软等待

适用：
- 低频长尾位
特点：
- 节省资源
- 不适合核心高价值激励位

策略 D：自动加载 + 场景感知展示

适用：
- 高频核心激励
特点：
- 是当前推荐的主流 IAA 策略
- 平衡 ready rate 和展示体验

策略 E：更高价广告软等待

适用：
- 激励价值极高的场景
特点：
- 可能提高单次展示收益
风险：
- 等待过久伤转化
- 必须通过 A/B 测试验证

9. 推荐的新架构

flowchart LR
    A["业务层\nADManager.AsyncPlayAD"] --> B["策略层\nPlacementPolicy / RevenuePolicy"]
    B --> C["Provider Runtime\nRewardedRuntime / InterstitialRuntime"]
    C --> D["Platform Adapter\nTopOn/Taku"]
    D --> E["Unity SDK Bridge"]
    E --> F["Native SDK"]

7.1 抽象层职责

保留 ADManager 作为统一入口
去掉“只懂 0/1/2 状态”的单薄模型
引入 placement 级策略

7.2 平台层职责

管理 SDK 生命周期
管理自动加载/手工加载
管理状态查询和场景统计
处理微信/抖音/小程序/下载相关链路

7.3 策略层职责

placement 是否自动加载
预热时机
soft wait 时长
load fail 重试策略
show 冷却和频控

10. 实施计划

阶段 1：P0 止血

目标：解决首播失败和关键回调缺陷

实施项：

将工程切换到本地 CC-Framework.Commercialization
扩展 Unity 层，补 ATSDK.start()
ToponAdController 中接入 start 生命周期
激励首播增加冷启动补偿和短重试窗口
插屏回调链修正

阶段 2：P1 收益增强

目标：提高 Ready Rate 和 Show Rate

实施项：

核心激励位切自动加载
插屏支持自动加载或策略化预热
接 entryAdScenario
接状态查询、缓存查询

阶段 3：P2 架构升级

目标：建立长期可运营体系

实施项：

新增策略层
placement 级配置
本地策略 / 后端策略下发
数据埋点和 BI 打通

11. 第一阶段具体改动清单

9.1 必改

Packages/manifest.json
- 切本地包依赖
Packages/CC-Framework.Commercialization/Assets/Runtime/ADAggregator/*
- 升级 AsyncAdPlayer
Assets/Topon_Adapter/Runtime/Scripts/ToponAdController.cs
- 补 start
Assets/Topon_Adapter/Runtime/Scripts/AwardVideoPlayer.cs
- 首播容错、场景统计
Assets/Topon_Adapter/Runtime/Scripts/InteractionPlayer.cs
- 回调完整化

9.2 推荐

增加 ToponSdkLifecycle 或 ToponStrategyConfig
增加 RewardedPlacementPolicy
为激励和插屏补统一诊断日志

12. 产品 / 运营 / 后端建议

10.1 产品侧

明确每个激励位的触发场景和价值等级
区分“高价值激励位”和“长尾激励位”
插屏不要用“一刀切”频率

10.2 运营侧

配合场景统计做 placement 漏斗
按渠道分组优化 Waterfall
做自动价格和 A/B 实验

10.3 后端侧

下发 placement 策略
拉通报表 API
统一客户端和平台收益口径
对激励奖励做服务端幂等和风控

13. 一句话结论

当前最优方案不是继续修补旧版手工状态机，而是：

保留 ADManager 统一入口，重做中下层为“策略层 + 平台能力层”，把新版 Taku/TopOn 的 start / 自动加载 / 场景统计 / 状态查询 / 本地策略 真正接进来。

16 KiB Raw Blame History Unescape Escape

IAA广告架构重构实施指南

1. 目标

2. 当前架构快照

2.1 运行时主链路

2.2 当前仓库角色

2.3 当前已知版本状态

3. 术语速查

3.1 Placement（广告位）

3.2 Scenario（广告场景）

3.3 load / ready / show

3.4 Auto Load（自动加载）

3.5 Waterfall（瀑布流）

3.6 Bidding（竞价）

3.7 eCPM

3.8 Fill Rate（填充率）

3.9 Show Rate（展示率）

3.10 Impression（展示）

3.11 Report API

3.12 Local Extra / Custom Map

3.13 为什么“预加载影响 eCPM”是旧命题

4. 官方推荐生命周期

4.1 推荐调用顺序

4.2 推荐自动调用的动作

4.3 业务层不应该感知的内容

5.1 当前已接入的策略 Key（第二阶段）

5. 官方最新 SDK 能力，与当前项目的差距

3.1 ATSDK.start()

3.2 自动加载能力

3.3 状态查询能力

3.4 广告场景统计能力

3.5 本地策略能力

3.6 流量分组 / 规则能力

6. 现有问题，按收入影响从大到小排序

P0. 首播请求容错太差，直接损失收入

P1. 高价值 placement 没有自动加载，Ready Rate 偏低

P2. 没有完整接入场景统计，无法做精细化收益调优

P3. 生命周期抽象过粗，不适配新版 SDK

P4. 插屏回调链本身存在缺陷

P5. 版本漂移导致实验结果不可信

7. 对“预加载影响 eCPM”的判断

8. 最优指南：面向 IAA 的广告策略

6.1 激励视频

6.2 插屏

6.3 后台协同

8.4 常见产品策略方式

策略 A：核心激励常驻预热

策略 B：场景前置预热

策略 C：点击兜底加载 + 软等待

策略 D：自动加载 + 场景感知展示

策略 E：更高价广告软等待

9. 推荐的新架构

7.1 抽象层职责

7.2 平台层职责

7.3 策略层职责

10. 实施计划

阶段 1：P0 止血

阶段 2：P1 收益增强

阶段 3：P2 架构升级

11. 第一阶段具体改动清单

9.1 必改

9.2 推荐

12. 产品 / 运营 / 后端建议

10.1 产品侧

10.2 运营侧

10.3 后端侧

13. 一句话结论

16 KiB

Raw Blame History

3.1 `ATSDK.start()`