GMA SDK 广告预加载审计实战skills 仓库中的跨平台 Preload API 校验规则详解【免费下载链接】skillsAgent Skills for Google products and technologies项目地址: https://gitcode.com/GitHub_Trending/skills29/skills本文围绕 skills 仓库中google-mobile-ads-validate技能的一项核心审计规则——广告预加载Ad Preloading校验展开。你将完整掌握 Google Mobile AdsGMASDK 在 Android、iOS、Unity 三个平台上预加载 API 的对照关系理解 6 类必须判 Fail、1 类 Warning 及 N/A 的判定标准并结合仓库内的 Next-Gen SDK 迁移映射表学会如何在应用发布前对预加载实现做合规审查。一、这项校验在 GMA 集成审计中的定位在 skills 仓库中google-mobile-ads-validate 是一个面向 AI Agent 的集成校验技能用于对已接入 GMA SDK 的 iOS、Android 或 Unity 工程做上线前审计。它支持两种工作模式完整审计Full Audit当用户提出泛化的校验/完整审计请求时评估全部检查项单项检查Specific Checks当用户只要求校验某个领域例如只查广告预加载时仅评估对应的检查项而不运行整个清单。完整审计清单包含 5 个检查项广告预加载校验是其中之一其余 4 项各有独立的参考文档检查项参考文档项目中不存在测试 Application ID 且格式正确application-id.md项目中不存在测试广告单元且格式正确ad-units.md已实现全部 Google SKAdNetwork IDgoogle-skadnetwork-ids.md中介Mediation适配器版本兼容性mediation-adapter-compatibility.md广告预加载校验ad-preloading.md每个检查项的状态按统一的评分规则取值见 SKILL.md 的 Scoring Rules 一节Pass不满足任何 Warning、Fail 或 N/A 条件Warning / Fail / N/A满足对应状态描述的条件校验结论最终以 Markdown 报告输出表格列为Check | Status | Findings | Next Steps且只包含实际执行过的检查项。二、跨平台预加载 API 对照表定位代码的第一步ad-preloading.md 给出的操作步骤是在目标工程中搜索当前平台对应的 GMA SDK 预加载调用。三套平台的 API 命名风格差异很大审计时必须先按本表锁定搜索关键词APIAndroidiOSUnityStart PreloadstartPreloadpreloadPreloadStop PreloaddestroyAllstopPreloadingAndRemoveAllAdsDestroyAllPoll AdpollAdad(withPreloadID:)DequeueAdAd PreloadedonAdPreloadedadAvailable(forPreloadID:)OnAdPreloadedAd ExhaustedonAdsExhaustedadsExhausted(forPreloadID:)OnAdsExhaustedAd Available CheckisAdAvailableisAdAvailable(withPreloadID:)IsAdAvailable从这张表可以读出三套平台的命名约定差异这也是搜索时的注意点Android方法名全部小驼峰回调以on开头onAdPreloaded、onAdsExhausted停止预加载直接叫destroyAlliOS以 Swift 风格 API 呈现回调是...Available(forPreloadID:)、...Exhausted(forPreloadID:)这类带PreloadID参数的方法preload ID 是贯穿 iOS 预加载流程的显式参数Unity首字母大写的 C# 风格Preload、DequeueAd、OnAdPreloaded取广告的叫DequeueAd而非Poll。审计时建议按平台逐一搜索这些关键词确认工程中实际使用了哪些预加载能力再对照下文的 Pass/Fail 条件逐项判定。三、Pass/Fail 判定标准六类 Fail 模式逐条拆解原文档给出的判定标准是本次校验的核心必须完整保留。以下按原文逐条继承并补充每条模式的实际含义与规避方式。3.1 Fail 条件任一不当预加载模式被检出即判 Fail1在同一个方法作用域内poll出广告却没有展示Polls an ad without showing it within the same method scopepollAdAndroid/ad(withPreloadID:)iOS/DequeueAdUnity是从预加载队列中取出一个广告的操作取出后即消耗掉队列中的一个实例。如果在同一方法作用域内调用了 poll 却没有任何展示路径例如忘记调用show()或仅在日志中打印该广告就被白白丢弃预加载的意义荡然无存。正确的写法是 poll 与 show 处于同一逻辑流程中且 show 一定会被执行。2在广告已预加载或广告已耗尽回调中启动预加载Starts preloading in the ad preloaded or ad exhausted callbackonAdPreloaded/adAvailable(forPreloadID:)/OnAdPreloaded与onAdsExhausted/adsExhausted(forPreloadID:)/OnAdsExhausted这两组回调的职责是通知状态变化而不是重新发起预加载。在回调内部嵌套startPreload/preload/Preload会形成难以追踪的重入链路容易造成状态错乱。启动预加载应当放在明确的生命周期位置如页面初始化而不是被动回调里。3在广告已预加载或广告已耗尽回调中停止预加载Stops preloading in the ad preloaded or ad exhausted callback与上一条同理destroyAll/stopPreloadingAndRemoveAllAds/DestroyAll表示终止整个预加载器并清空队列属于生命周期级操作。把它放进预加载回调中会导致预加载完成 → 立即销毁预加载器这种自相矛盾的循环正确做法是把停止操作与页面/功能的销毁流程绑定。4对同一个 preload ID 多次启动预加载且中途未先停止预加载器Starts preloading for the same preload ID multiple times without stopping the preloader first预加载器实例与 preload ID 绑定。若要在同一 ID 上再次startPreload必须先调用停止 API 释放旧实例否则会出现重复预加载、队列状态不可预期等问题。审计时应检查所有对同一 ID 的启动点确认存在先停后启的调用顺序。5使用空字符串或 null 作为 preload IDUses an empty string or null as the preload IDpreload ID 是区分不同预加载队列/实例的键。传入或null会使多个逻辑队列混用同一键或触发 SDK 内部状态异常。代码审查时应关注 preload ID 的赋值来源避免把可能为空的变量直接传入预加载 API。6在 Unity 中于Update循环内检查广告可用性Checks ad availability inside an Update loop on Unity这条只针对 Unity 平台。IsAdAvailable/isAdAvailable/isAdAvailable(withPreloadID:)属于可能涉及跨线程查询的 API若放在每帧执行的Update()中高频轮询会造成不必要的性能开销。可用性的检查应挂在事件回调如OnAdPreloaded或用户触发点上进行。3.2 Warning 条件对同一广告格式预加载了多个广告单元 IDPreloads multiple ad unit IDs for the same ad format例如同一 banner 格式下为两个广告单元分别建立预加载队列。这未必是错误有时是多源冗余策略但会成倍消耗预加载配额与流量因此只判 Warning 并提示确认必要性。3.3 N/A 条件工程根本没有使用预加载 API按上表搜索不到任何命中→ 判定 N/A而不是 Pass。四、结合 Next-Gen SDK 迁移映射预加载 API 的底层变化佐证skills 仓库中还有一份与预加载直接相关的映射文档——google-mobile-ads-android-migrate-to-next-gen 技能它描述了从旧版 GMA SDKcom.google.android.gms:play-services-ads迁移到 GMA Next-Gen SDKcom.google.android.libraries.ads.mobile.sdk:ads-mobile-sdk的规则。其中与预加载相关的变化可以作为审计时判断代码属于哪代 SDK、应使用哪套 API的依据预加载要素旧 SDKGMA Next-Gen SDK预加载配置preload.PreloadConfiguration通过PreloadConfiguration.Builder(String adUnitId).build()构建common.PreloadConfiguration改为PreloadConfiguration(AdRequest request)广告单元 ID 声明在AdRequest中预加载回调preload.PreloadCallbackV2抽象类common.PreloadCallback改为接口 interface插页广告预加载器interstitial.InterstitialPreloaderinterstitial.InterstitialAdPreloader预加载完成回调onAdPreloaded(preloadId: String, responseInfo: ResponseInfo?)onAdPreloaded(preloadId: String, responseInfo: ResponseInfo)responseInfo不再可空从该映射文档的结构看见 SKILL.md 的 Ad preloading 一节除映射表中明确列出的差异外Next-Gen SDK 的预加载方法保留与旧 SDK 相同的 API 签名与参数。这意味着第二节的跨平台 API 表startPreload、onAdPreloaded、onAdsExhausted等关键词对两代 SDK 都同样适用审计搜索时不会因为 SDK 版本不同而漏检但配置构建方式Builder(adUnitId)还是PreloadConfiguration(AdRequest)与回调可空性ResponseInfo?还是ResponseInfo是区分新旧代码的信号可用于在 Findings 中描述工程所处的 SDK 代际。此外该迁移文档强调的 UI 线程规则同样适用于预加载回调GMA Next-Gen SDK 的回调在后台线程触发回调内的所有 UI 操作必须包裹在runOnUiThread {}或Dispatchers.Main.launch {}中——审计onAdPreloaded回调体时可以把这一点作为附加检查项因为它直接决定预加载后的展示逻辑是否会崩溃。五、审计执行方式与报告输出以 ad-preloading.md 为执行蓝本一次完整的预加载校验流程是确定平台识别工程是 Android、iOS 还是 Unity或跨平台如 Unity 工程同时含原生插件选定第二节的关键词表搜索定位对 6 组 APIStart/Stop Preload、Poll Ad、Ad Preloaded、Ad Exhausted、Ad Available Check逐一搜索记录所有命中点若零命中直接判 N/AThe project doesnt use the ad preloading APIs若存在命中读取每个命中点的上下文对照 3.1 节的 6 条 Fail 模式与 3.2 节的 Warning 条件判定状态生成报告按 SKILL.md 的 Final Output 模板只输出实际检查过的行格式为CheckStatusFindingsNext StepsAd preloading validation checksPass / Warning / Fail / N/A命中的具体文件、模式与说明修复建议如在onAdPreloaded回调中移除startPreload调用改为在页面初始化时启动六、适用前提与边界说明本文全部判定标准来源于仓库内 ad-preloading.md 与 SKILL.md适用于任何接入了 GMA SDK含 Next-Gen SDK预加载方法签名在两代间基本一致且使用预加载 API 的工程各平台 API 关键词表覆盖 Android、iOS、Unity 三端其他平台如 Flutter 包装层不在该表显式覆盖范围内审计时只能从源码结构推断其最终落到了哪一端的原生 API 上并据此谨慎套用对应行的规则迁移映射部分依据的是仓库中迁移技能的映射表SKILL.md仅覆盖 Android 侧旧 SDK 到 Next-Gen SDK 的差异本仓库是只读的 Agent Skills 集合以上查看、运行均指将上述技能文档作为审计规范使用不涉及修改仓库内容。【免费下载链接】skillsAgent Skills for Google products and technologies项目地址: https://gitcode.com/GitHub_Trending/skills29/skills创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考