预加载与缓存

文档版本 v1.0.0

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

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

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

接口

objc

// 首页展示出来之后：为下一次开屏备货（缓存已满或已有预加载在飞时 SDK 自动跳过 / 合并）
[AdMixSplashAd preloadUnitId:@"splash_main"];

// 激励视频入口页打开时：用户点按钮时大概率已经就绪
[AdMix preloadUnitId:@"reward_main" completion:^(NSString *unitId, NSString *adnType, NSError *error) {
    // error 非 nil：未开缓存、缓存已满、无填充
}];

[AdMix cachedCountForUnitId:@"splash_main"];   // 当前可用条数（过期的已剔除）
[AdMix clearCache];                            // 用户撤回隐私授权时调用

+[AdMixSplashAd preloadUnitId:]、+[AdMixRewardAd preloadUnitId:]、+[AdMixBannerAd preloadUnitId:] 与 +[AdMix preloadUnitId:completion:] 等价，只是不需要结果回调。

用户同意隐私政策（调用 start）之前调用一律失败，一个请求都不会发。

各广告位的行为

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

进程被杀后缓存清空

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

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

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

热启动开屏（App 从后台回到前台时补放开屏）—— 缓存收益最大的场景
下一次激励视频

建议接入热启动开屏：App 在后台停留超过一定时长（通常 30 秒以上）回到前台时展示开屏。 iOS 上 App 退到后台后进程通常还活着一段时间，热启动开屏是开屏缓存最主要的命中来源。

过期与补位

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

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

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

Swift 写法

swift

AdMixSplashAd.preload(unitId: "splash_main")

AdMix.preload(unitId: "reward_main") { unitId, adnType, error in
    // error 非 nil：未开缓存、缓存已满、无填充
}

let count = AdMix.cachedCount(unitId: "splash_main")
AdMix.clearCache()

已知限制

缓存只在进程内存里，进程被杀后清空，新进程的第一条开屏一定是实时请求。

预加载与缓存 ​

接口 ​

各广告位的行为 ​

进程被杀后缓存清空 ​

过期与补位 ​

Swift 写法 ​