用途
本 Skill 用于 three.js + Capacitor 移动项目通过 AppLovin 官方 MAX Cordova 原生插件接入聚合广告，覆盖 Banner、插页与激励视频三类广告位。聚合层固定使用 AppLovin MAX，接入实现固定使用 AppLovin 官方维护的 cordova-plugin-applovin-max，由 Capacitor 的 Cordova 兼容层加载。项目只在 TypeScript 侧建立业务门面和官方插件 API 适配，不自建 Android/iOS 广告插件，也不直接集成 MAX 原生 SDK。
主要能力
- 指导 iOS/Android 插件的集成路径与版本、许可证、平台支持、Capacitor 兼容方式的核对。
- 管理 Banner、插页与激励视频广告位的独立状态：每个广告位独立维护加载失败计数、retry deadline 和至多一个重试 timer，但使用相同分类、退避、暂停和恢复规则。
- 插页与激励视频只在后台静默预加载，不在初始化阶段主动创建广告对象或视图；预加载成功以当前广告实例对象的就绪属性为准。
- Banner 不预加载，只在业务请求展示时创建并加载；支持 Banner 且广告位启用、页面允许展示时，在页面首帧前先预留广告区域并完成 UI 布局。
- 统一处理视频广告位不可用提示：用户触发展示但当前不可用，或官方插件接受展示后回调 displayFailed 时，通过统一 UI 层弹出一次“视频广告暂不可用，请稍后再试”Toast。
- 隐私流程固定使用 MAX 自带的 Terms and Privacy Policy Flow 与其集成的 Google UMP；iOS ATT 交由该流程按官方配置处理。
使用方式
开始任何设计、实施或审查前，必须先读取唯一细则合同 AppLovin MAX 接入合同，并以其中的状态、时序、失败和合规规则为准。交付流程包括：读取当前 Work Item、项目 TDD/依赖能力档、Capacitor 平台状态及官方插件安装状态；提交最小模块提议（Web/小游戏 no-op、AppLovin 官方 Cordova 插件、共享 TypeScript 业务门面与插件 API 适配器、测试替身）；冻结插件适配契约（initialize、preload(slotId)、tryShow(context)、setBannerVisibility(slotId, visible)、isReady(slotId) 均为非阻塞调用并返回结构化结果）。全局控制接入以 $threejs-game-workflow-control 为唯一全局状态、风险门、任务范围和证据控制面。
共享门面至少提供以下语义：
initialize(config): Promise<InitResult>
retryInitialize(): Promise<InitResult>
preload(slotId): Promise<PreloadResult>
isReady(slotId): ReadyResult
tryShow(context): Promise<ShowResult>
setBannerVisibility(slotId, visible): Promise<BannerVisibilityResult>
结果至少包含稳定的 ok、code、platform、phase、gates 和必要的 retryScheduled 字段；插页因激励视频后的 30 秒保护期被跳过时返回 rewarded-interstitial-delay 和 interstitialDelayRemainingMs。
适用场景
- three.js + TypeScript/Vite + Capacitor 的 iOS/Android 移动项目接入 AppLovin MAX 聚合广告。
- 需要在游戏自然中断点展示插页或激励视频，且不得阻塞场景切换、输入、主循环或结算流程。
- 需要在页面首帧前预留 Banner 区域并按需创建广告视图。
- 需要在 MAX 自带隐私流程与 Google UMP/TCF、iOS ATT 下完成初始化与广告请求隐私门控制。
限制
- ThreeJS Web、浏览器预览和小游戏不直接调用 MAX，也不加载原生广告 SDK；广告能力在这些运行目标上必须是明确的 unsupported/no-op，调用后立即返回并继续游戏。
- 不兼容时必须阻断并报告，不回退到社区插件、自建 Capacitor 原生插件或业务代码直连 MAX SDK。
- 本 Skill 不替项目自动配置 MAX 控制台、广告网络账号、商店元数据或发布渠道。
- 涉及外部写入、付费、真实设备、商店提交、发布或不可逆操作的 A4-A6 动作，必须按对象取得控制面明确批准；本 Skill 不代为批准、执行或推送这些动作，也不自动发起真机运行验收。
- SDK key 与 ad unit ID 按环境从受控构建配置注入官方插件适配层，不手写进业务源码、示例、日志或提交记录；广告网络账号凭证与 Ad Review key 不得进入 Web 代码或公开产物。
- 本仓库本次只交付 Skill 指导文件，不新增运行时代码、脚本、SDK 依赖或外部配置。
- 固定聚合渠道为 AppLovin、Google AdMob、Mintegral、Pangle、Unity Ads、DT Exchange（Fyber）和 Verve（PubNative/HyBid）；插件、MAX SDK 与 adapter 的版本组合以官方插件和官方渠道文档当前声明的兼容范围为准，不在 Skill 或业务代码中写死版本号。