预加载与缓存

文档版本 v1.0.0

本页对应 SDK 1.0.0，与离线包 docs/ 目录里的同一份文档内容一致。其他版本见文档中心。

广告位在后台开了缓存（cache_size > 0）时，SDK 会把「提前调度好、还没被展示」的广告放进 内存缓存池，load() 优先从池子里取。

接入方代码不需要为缓存写任何分支：命中就同步回调 onAdLoaded，没命中照常请求。

接口

// 主页 onResume：为下一次开屏备货（缓存已满或已有预加载在飞时 SDK 自动跳过 / 合并）
AdMix.preload(this, "splash_main");

// 激励视频入口页打开时：用户点按钮时大概率已经就绪
AdMix.preload(this, "reward_main", new AdPreloader.PreloadListener() {
    @Override public void onSuccess(String unitId, String adnType) { }
    @Override public void onFail(String unitId, AdError error) { }   // 未开缓存、缓存已满、无填充
});

AdMix.getCachedCount("splash_main");   // 当前可用条数（过期的已剔除）
AdMix.clearCache();                    // 用户撤回隐私授权时调用

两条约束：

• 用户同意隐私政策（调用 start()）之前调用一律失败，一个请求都不会发
• 用来预加载的 Activity 会被广告对象引用到它被取走或过期， 不要用马上就 finish 的页面预加载（如开屏页自己）；主页这类长期存活的页面最合适。 开屏广告 View 在 show() 时才挂进开屏页的容器，预加载与展示用不同的 Activity 没有问题（真机已验证）

各广告位的行为

广告位	命中缓存	未命中	自动补位
开屏	同步回调，0 等待	发起请求并等待，最多 total_timeout_ms（从 load 调用起算，含广告平台初始化）。超时放行后请求继续跑完，拿到的广告进缓存池留给下一次开屏，不会像纯实时请求那样超时即丢弃	按配置
激励视频	同步回调	有预加载在飞就等它（不重复请求），否则实时请求	按配置，一般不开
激励视频 + 服务端验证参数	不取缓存、不等预加载，一律实时请求（缓存里的广告请求时没带这次的用户 ID）	—	—
Banner	只有首次 load 取缓存	实时请求	不补。每次定时刷新都是实时调度

进程被杀后缓存清空

冷启动第一条开屏一定是实时请求

广告平台的广告对象不能持久化，缓存池只在进程内存里。所以真正的冷启动（新进程） 第一条开屏必然是实时请求 —— 它的价值在于超时后的结果会进池子。

缓存命中发生在进程还活着的时候：

• 热启动开屏（App 从后台回到前台时补放开屏）—— 缓存收益最大的场景
• 返回桌面后再从图标进入
• 下一次激励视频

建议接入热启动开屏：App 在后台停留超过一定时长（通常 30 秒以上）回到前台时打开开屏页。

过期与补位

这两件事由 SDK 自动处理，了解即可。

• 素材有效期默认 30 分钟（优量汇官方开源聚合适配器对穿山甲 / 快手 / 百度统一取 30 分钟）； 广告平台自己给出更早的过期时刻时以平台为准。过期的广告到点即销毁，绝不会被展示
• 开了 auto_refill 的广告位，缓存被取走或过期后补一条：两次补位至少间隔 refill_min_interval_sec（默认 30 秒），失败按间隔翻倍退避（封顶 10 分钟）， 连续失败 3 次暂停，等下一次取走 / 过期 / 主动 preload 再恢复； 只在 App 前台发起，开屏刚被开屏页取走时会等开屏页退出再补
• 缓存中的广告不再和实时请求比价：它本身就是一轮完整调度的胜出者。 池子里有多条时取价格最高的一条，同价取先入池的；容量满时丢弃新来的那条 （旧的更早过期，先用掉才不浪费）
• show() 对过期素材返回 false。过期广告的对象本身还在、有效性判断也可能仍返回 true， 展示出来却是一块空白，这种「填充成功却没有曝光」的损失在报表上极难归因，所以 SDK 主动拦住

缓存相关的配置项见《策略配置格式》，埋点上如何区分缓存来源见《数据与事件》。

已知限制

缓存只在进程内存里，进程被杀后清空。唯一能改善「新进程第一条开屏」的手段是优量汇的 SplashAD.preLoad()（跨进程素材预缓存），尚未接入。

开屏超时后迟到入池的广告会引用已 finish() 的开屏页，直到被取走或过期（不超过 30 分钟）， 属于有界泄漏。