YYKAAdkit · Cocos Creator 小游戏 IAA 广告接入套件

在 Cocos Creator 里配一次广告、写一行代码，微信 / 抖音小游戏的 IAA 广告接入就完成了——不用再逐平台抄 API、管回调、算冷却。

一个面板管配置（AppID / 广告位 / 策略 / 合规），一份配置落盘，一套 API 给业务：
AdKit.showRewarded('revive')。平台差异、预加载、重试、频控、隐私前置、构建期补文件全部在插件里做完。

✨ 功能特性

1. 面板集中配置，一份配置文件

插件面板共 8 个页签：概览 / 平台 / 广告位 / 策略 / 埋点 / 合规 / 调试 / 关于。

• 概览：配置文件是否已生成、启用平台数、广告位总数、各平台接入状态（是否启用 / AppID 是否已配置 / 广告位缺失数量），并提供搜索与注入的快捷入口。
• 所有配置集中保存为一份 <工程>/assets/yyka-adkit/adkit.config.json，不再散落在代码与平台后台。
• 概览页与各页签共用同一份内存状态，切换页签不丢改动。

2. 平台能力矩阵（单一事实来源）

• 平台清单集中在 source/core/platform-matrix.ts 一处维护：平台标识、运行时命名空间、落地阶段、支持的广告类型、能力限制备注。
• 首版（v1）落地：微信小游戏 wechatgame、抖音小游戏 bytedance-mini-game，覆盖 激励视频 rewarded 与 插屏 interstitial。
• 快手 / QQ / 百度 / 支付宝 / 快游戏联盟已登记为预留平台，面板只读展示，运行时与面板上层均以矩阵为准。
• 新增平台 = 加一个适配器文件 + 在矩阵注册 + 进探测顺序，门面 / 策略引擎 / 面板零改动。

3. 逻辑广告位（业务只认一个 ID）

• 业务代码里只记逻辑广告位，例如 revive、level_pass_double，不写平台广告位 ID。
• 每个逻辑广告位按平台分别填 adUnitId：留空表示该平台不投放，一套配置可同时服务多个平台。
• 广告位可配置类型、描述，以及每个广告位独立的策略（见下一条）。

4. 策略引擎（把每次重写的广告逻辑收进配置）

按广告位可调，全部在运行时统一执行：

全局还有一条 插屏启动门控 interstitialGateSeconds（默认 30s）：启动后该秒数内禁止弹插屏，避免盖住首屏；0 = 不门控。

5. 合规开关（隐私前置不卡死）

6. 统一错误语义 + 错误码速查表

• 微信 / 抖音的原始错误码体系互不通用，适配器统一归一化为 8 种语义：no_fill / network / adunit_invalid / banned / unsupported / capped / cooldown / unknown。
• 无数字错误码时按错误文案兜底推断（no ad / network / 参数 / 封禁 / 版本 等关键词）。
• 面板「调试」页内置错误码速查表，与文档一致：微信 / 抖音通用码 1000~1008、插屏类 2001~2005、抖音特有码 10301 / 20000~21000 / 120002，每条都给出含义与建议处理。

7. 标准事件模型（本地埋点，可订阅可导出）

• 8 类事件：ad_request、ad_load_success、ad_load_fail、ad_show、ad_click、ad_close、ad_reward_success、ad_reward_fail，统一补齐 time / platform / placementId / type，并带 adUnitId / tag / costMs / retryIndex / isPreloaded / isEnded / errorCode / semantic 等字段。
• 业务可 AdKit.on('ad_reward_success', handler) 订阅统计，也可 AdKit.getLocalEvents() 取本地事件快照（环形缓存 200 条）、clearLocalEvents() 清空。
• 业务回调抛异常只打 warn，不影响广告流程。
• 服务端批量上报（endpoint / batchSize）为预留配置，首版仅本地记录、不联网。

8. 一键注入运行时（幂等 + 可升级 + 可回滚）

点一下「注入运行时」，插件把运行时库写入用户工程：

<工程>/assets/yyka-adkit/
├─ runtime/                  # AdKit 门面 / 策略引擎 / 隐私门 / 事件总线 / 适配器
├─ core/platform-matrix.ts   # 平台能力矩阵（运行时依赖）
└─ adkit.config.json         # 面板保存的配置

• 内容未变化的文件不重复落盘，避免 Cocos 反复重新导入资源。
• 入口文件头部带 @adkit-version 版本标记，重复注入（升级）前会自动备份旧内容，并清理插件接管范围内的过期文件。
• 注入目录保持相对层级完整，运行时内部相对 import 才成立；注入的是源码文本，工程照常由 Cocos 编译。

9. 构建集成（不劫持未接入的工程）

• onBeforeBuild：目标平台不在 v1 范围 → 跳过；未接入（无配置 / 平台未启用）→ 只告警跳过；已接入但配置有 error 级问题 → 中止构建并给出问题清单。
• onAfterBuild：① 把配置写到产物目录的 adkit.config.json；② 补写平台配置文件；③ 比对注入运行时的版本标记，落后时提示升级。
• 平台文件补写（补全而非覆盖）：微信 project.config.json 补 appid、抖音 project.config.json 补 appid；只动插件负责的字段，其余字段与手改内容原样保留；文件解析失败一律跳过不覆盖；未填 AppID 时不创建空文件。构建日志逐条打印 新建 / 合并写入 / 已一致 / 跳过（原因）。
• 产物目录三源定位：result.dest → result.paths.output → options.buildPath（含 project:// 还原）+ 平台目录兜底，并用产物特征文件（game.js / game.json / application.js / index.html 等）校验，避免写错目录。

10. 预览即可联调（不需要真机）

• 未探测到 wx / tt 命名空间时（编辑器预览 / 浏览器预览）自动回落 MockAdapter，AdKit.preview === true。
• Mock 下可完整走通「加载 → 展示 → 关闭 → 激励发放 / 未看完」全流程，MockAdapter.behavior 可控制是否看完、加载 / 展示是否失败、各阶段耗时。
• 广告位与类型仍以配置为准，所以预览期的结果与真机语义一致。

11. 运行时零引擎依赖

• 注入的运行时是纯 TypeScript，不 import 'cc'，只做广告 API 与策略编排——所以它不绑定渲染层、不增加包体耦合，业务侧只在读配置时用到 cc。
• 类型定义、配置 schema、事件模型都有独立导出（runtime/types.ts / runtime/config.ts），IDE 补全直接可用。
• 配置归一化对非法输入收敛而不抛错：缺失补默认、类型不符转数字、负数归零、未知平台与未知字段裁剪。

📋 使用说明

安装与启用

1. 把扩展目录 yyka-adkit 放到：
   • 项目级：<你的项目>/extensions/
   • 全局级（Windows）：%USERPROFILE%\.CocosCreator\extensions\
   • 全局级（macOS）：~/.CocosCreator/extensions/
2. 重启 Cocos Creator，或使用编辑器菜单 开发者 → 重新加载扩展。

打开面板

顶部菜单：YYKA插件 → YYKA广告套件，点击即打开面板。

六步上手

1. 平台页：勾选要接入的平台（首版为微信 / 抖音），分别填写小游戏 AppID。页面下方只读展示平台能力矩阵（含预留平台）。
2. 广告位页：新增逻辑广告位 → 填 id（如 revive）、type（rewarded / interstitial）、desc → 在对应平台栏填 adUnitId（留空 = 该平台不投放）。
3. 策略页：按广告位调 预加载 / 重试次数与间隔 / 冷却 / 每日上限 / 兜底广告位 / 加载失败表现；再设全局的插屏启动门控。
4. 合规页：按需开关 隐私授权前置 / 频控 / 未成年保护登记项。
5. 点右上角「保存」：配置落盘到 <工程>/assets/yyka-adkit/adkit.config.json。
6. 调试页 →「注入运行时」：写入 assets/yyka-adkit/runtime/** 与 assets/yyka-adkit/core/platform-matrix.ts；需要时点「校验配置」检查 error / warn 项。

业务运行前把 adkit.config.json 再复制一份到 assets/resources/，运行时用 resources.load 读取（原因见 FAQ Q3）。

业务代码接入（完整示例）

// assets/scripts/AdBootstrap.ts
import { JsonAsset, resources } from 'cc';
import { AdKit } from '../yyka-adkit/runtime/AdKit';

export async function bootstrapAdKit(): Promise<void> {
    // 1. 读数面板导出的配置
    const config: any = await new Promise((resolve) => {
        resources.load('adkit.config', JsonAsset, (err, asset) => resolve(err ? {} : asset.json));
    });

    // 2. 初始化：注入配置、选定适配器、按策略预加载
    AdKit.setLogLevel('debug');
    await AdKit.init(config);

    // 3. 展示激励视频（不抛异常，全部结构化返回）
    const result = await AdKit.showRewarded('revive', { tag: 'level_fail' });
    if (result.completed) {
        // 发放奖励
    } else if (result.reason === 'cooldown' || result.reason === 'capped') {
        // 频控命中，提示「稍后再试」
    }

    // 4. 插屏（受启动门控 + 频控约束）
    const it = await AdKit.showInterstitial('level_start');
    if (!it.shown && it.reason === 'gated') {
        // 启动初期被门控，稍后重试
    }

    // 5. 本地埋点
    console.log(AdKit.getLocalEvents());
}

运行时 API 速查

showBanner / hideBanner 为首版预留：showBanner 调用即抛「首版预留能力」异常，hideBanner 仅打日志无副作用。

构建

在「构建发布」中构建微信 / 抖音小游戏即可。插件通过 contributions.builder 已挂上构建钩子，无需额外配置；构建日志里能看到配置写入与平台文件补写的逐条结果。

升级与卸载

• 升级运行时：插件版本更新后，在「调试」页再点一次「注入运行时」，旧内容会自动备份。
• 卸载：删除 <工程>/assets/yyka-adkit/ 整个目录 + 业务代码里的 AdKit 调用即可，工程回到接入前状态（构建时不再生成配置、不再补写平台文件）。除升级备份外，插件不写工程内其他位置。

⚙️ 引擎与环境要求

🖥️ 平台支持情况

接入前置条件（平台侧硬要求）

广告位还需在各自平台后台创建并通过审核；未开通变现 / 审核中 / 暂无填充时都不会有可展示的广告。

📜 更新日志

v1.0.0（首次发布）

• 插件面板（8 页签）：概览 / 平台 / 广告位 / 策略 / 埋点 / 合规 / 调试 / 关于，配置落盘为单一 adkit.config.json。
• 平台能力矩阵作为单一事实来源：v1 落地微信、抖音小游戏，5 个平台预留登记。
• 逻辑广告位 + 按平台填 adUnitId（留空即该平台不投放），支持按广告位独立策略。
• 运行时策略引擎：预加载、指数退避重试、冷却、每日上限、兜底广告位、插屏启动门控、加载失败表现（silent / toast / callback）。
• 合规三开关：隐私授权前置（10s 超时 / 异常一律放行）、频控总开关、未成年保护登记项。
• 统一错误语义（8 种）+ 错误文案兜底推断 + 面板内置错误码速查表（微信 / 抖音原始码映射）。
• 标准事件模型（8 类事件）+ 本地事件缓存 200 条 + on / off 订阅与快照导出。
• 一键注入运行时：内容不变不落盘、升级前自动备份、清理过期文件、入口带 @adkit-version 版本标记。
• 构建集成：onBeforeBuild 配置校验（未接入仅告警、已接入有 error 才中止）+ 写入产物配置；onAfterBuild 补写平台 project.config.json 的 appid 并与注入版本做一致性比对。
• 产物目录三源定位（result.dest → result.paths.output → options.buildPath）+ 产物特征文件校验。
• 平台配置文件补全而非覆盖：解析失败跳过、未填 AppID 不建空文件、空值不覆盖既有值。
• MockAdapter 预览联调：编辑器 / 浏览器预览下完整走通展示与关闭流程。
• 注入运行时零 cc 依赖；配置归一化对非法输入收敛而不抛错。
• 自动化单测：配置归一化与校验、策略引擎（冷却 / 上限 / 门控 / 重试退避 / 兜底 / 事件序列）、隐私门、注入器（幂等 / 备份 / 过期清理 / 版本比对）、平台文件补写（保留用户字段 / 解析失败跳过）。

❓ 常见问题 FAQ

Q1. 编辑器预览时并没有真实广告，正常吗？
正常。未探测到 wx / tt 命名空间时会自动使用 MockAdapter（AdKit.preview === true），展示 / 关闭 / 激励发放都是模拟的，用于在不出真机的情况下把流程和业务逻辑调通。真机的广告结果、填充率与错误码以平台为准。

Q2. 微信和抖音的广告错误码不一样，我要自己判断吗？
不用。适配器把两端原始码统一归一化成 8 种语义（no_fill / network / adunit_invalid / banned / unsupported / capped / cooldown / unknown），你在 result.semantic 或事件的 semantic 字段直接判断即可；原始码仍在 errorCode 里保留，便于对照面板「错误码速查」表排查。

Q3. 为什么配置不能直接 import adkitConfig from './adkit.config.json'？
因为 Cocos 会把 assets/ 下的 JSON 导入为 JsonAsset 资源，而不是 ES 模块，直接 import 在运行时不可用。正确做法是把 adkit.config.json 复制一份到 assets/resources/，再用：

const config: any = await new Promise((resolve) => {
    resources.load('adkit.config', JsonAsset, (err, asset) => resolve(err ? {} : asset.json));
});
await AdKit.init(config);

如果你有自己的配置加载方式（远端下发 / 内联常量），把任意普通对象传给 AdKit.init(config) 也可以。

Q4. init 之后还要不要手动 preload？
preload 为 true 的广告位在 init 时已自动预加载，展示完还会自动补拉下一条，所以通常不需要。手动 AdKit.preload(id) 用于暖机或从后台切回等时机主动预热；已有实例或已有在途请求时它会静默跳过，不会重复加载。

Q5. 冷却 / 每日上限不生效？
先看「合规」页的 频控总开关 frequencyControl：关闭后 cooldownSeconds 与 dailyCap 会全部跳过。开关为开启时，冷却时间戳与每日计数写入平台 storage（预览下回落 localStorage，再无则内存），每日计数按「广告位 + 自然日」自动重置。

Q6. showRewarded 会抛异常打到业务层吗？
不会。不支持 / 冷却中 / 达上限 / 广告位不存在等全部以结构化结果返回（reason: 'unsupported' | 'cooldown' | 'capped' | 'error'），业务侧不需要 try/catch。只有明确标注为「首版预留」的 showBanner 会抛预留提示。

Q7. 插屏为什么一开始弹不出来？
这是启动门控：启动后 strategy.interstitialGateSeconds（默认 30s）内不允许弹插屏，返回 { shown: false, reason: 'gated' }，避免广告盖住首屏。把该值设为 0 即可关闭门控。另外抖音插屏依赖宿主版本，AdKit.isSupported('interstitial') 返回 false 时插件会直接返回 unsupported，不浪费时间重试。

Q8. 真机上广告拉不起来，怎么排查？
按这个顺序：① 平台是否启用且 AppID 已填；② 该广告位在当前平台是否填了 adUnitId（留空 = 不投放）；③ AdKit.setLogLevel('debug') 打开日志，看 ad_load_fail 的 errorCode / semantic 对照面板错误码速查表；④ 是 adunit_invalid → 去面板「广告位」页核对 ID 与平台后台是否一致；⑤ 是 no_fill → 平台暂无填充，配置 fallbackPlacementId 兜底提升成功率；⑥ 是 banned → 去平台后台看广告位是否审核中 / 被驳回 / 已关闭。

Q9. 构建时提示「配置校验未通过」导致构建中止？
这是 onBeforeBuild 的 error 级校验：未启用任何平台、启用平台 AppID 为空、广告位 ID 为空或重复等。按提示在面板修正后重新构建即可。反过来，没有接入的工程不会被影响——没有配置文件或平台未启用时插件只告警跳过，构建流程与接入前完全一致。

Q10. 构建时插件会不会覆盖我手改的平台配置文件？
不会。插件采用补全而非覆盖：读取 → 合并 → 写回，只动它负责的字段（appid），你手写的其他字段照原样保留；文件解析失败时直接跳过写入；未填 AppID 时连文件都不创建。构建日志会明确打印每个文件的处理结果（新建 / 合并写入 / 已一致 / 跳过）。

Q11. 构建日志说「未能定位产物目录」怎么办？
说明构建参数里的输出目录与插件的识别规则不一致。插件会按 result.dest → result.paths.output → options.buildPath（含 project:// 还原）→ 平台目录依次尝试，并用 game.js / game.json / application.js / index.html 等特征文件校验。请确认「构建发布」的输出目录已生成且包含这些特征文件；若仍是自定义目录结构，把产物目录信息反馈给作者补充识别规则。

Q12. 升级插件后，我工程里的运行时怎么更新？
在「调试」页再点一次「注入运行时」。插件会在覆盖前先把旧内容备份一份，并清理插件接管范围内的过期文件；内容没变化的文件不会重写，避免 Cocos 反复重新导入。构建时 onAfterBuild 还会读入口文件头部的 @adkit-version 标记，落后会提示你升级。

Q13. 运行时会不会增加包体 / 引入引擎耦合？
注入的运行时是纯 TypeScript，不 import cc，体量是几个小文件，只做广告 API 与策略编排；业务侧只有读配置时才用到 cc。类型与配置 schema 都有独立导出，IDE 补全可用。

Q14. 我的游戏要同时接微信和抖音两套广告吗？会在一个包里同时跑两个平台吗？
不会同时跑。一次构建只服务一个平台：运行时按 wx / tt 命名空间自动选适配器，同一个包里永远只有一个平台在工作，另一平台的广告位 ID 在那个包里不会被使用。

但工程层面建议两个都配：小游戏双端发行（微信 + 抖音）是常态，一份配置同时承载两套广告位 ID，逻辑广告位（如 revive）只需定义一次，不必维护两份 JSON 或两份代码。只发一个渠道也完全合法，只勾那一个即可。

需要留意的是：要构建哪个平台的包，就在「平台」页勾选哪个平台——只有勾选的平台，构建时才会写入产物 adkit.config.json 并补写 project.config.json 的 appid；未勾选平台的构建会跳过这些动作（只打一条告警，不会中止构建）。

Q15. 支持快手 / QQ / 百度 / 支付宝 / 快游戏联盟吗？Banner 呢？
首版不支持，仅预留扩展点（平台能力矩阵中已登记，showBanner 会明确抛「首版预留能力」提示）。新增平台是三步：新增一个适配器文件实现 IPlatformAdAdapter → 在 platform-matrix.ts 注册 → 加入 AdKit 探测顺序，门面、策略引擎、面板都不用改。

Q16. 埋点会上报到我的服务器吗？插件联网吗？
不会。埋点默认仅本地记录（环形缓存 200 条，AdKit.getLocalEvents() 读取），「埋点」页的 endpoint / batchSize 是阶段 F 的服务端上报预留配置，首版不生效。整个插件不联网、不上传任何数据。

Q17. 插件含授权 / 激活 / 分级逻辑吗？
不含。插件是纯本地能力（配置 + 运行时 + 构建集成），不引入任何授权、激活或版本分级机制，安装后即可使用。

Q18. 卸载插件会不会在我工程里留一堆垃圾？
不会。插件只写 <工程>/assets/yyka-adkit/ 目录（升级时另留一份运行时备份，可一并删除），删除 assets/yyka-adkit/ 目录并移除业务代码里的 AdKit 调用即卸载完成，工程回到接入前状态。

Q19. 我填了广告位，为什么真机没有广告？
广告位 ID 正确并不保证一定有广告，常见三类原因：① 平台侧变现未开通——微信需先开通流量主（累计 UV > 500 且无违规），抖音需在控制台「设置 → 商业化变现」申请（结算账户须为主体账户），未开通时广告接口不会返回广告；② 广告位还在后台审核中——微信错误码 1005（审核中）/ 1006（被驳回）/ 1007（被封禁）；③ 暂无填充或命中平台频控——微信 1004、抖音 1004 表示无合适广告（无填充），或命中了插屏的启动 / 间隔限制。排查方法：AdKit.setLogLevel('debug') 打开日志看 ad_load_fail 的 errorCode / semantic——no_fill → 暂无填充，可配 fallbackPlacementId 兜底；banned → 去后台看广告位状态；命中频控则稍后再试。

Q20. 抖音插屏为什么经常弹不出来？
抖音插屏的限制比微信多：仅抖音宿主支持（头条等宿主不支持），且平台侧强制启动后前 30s 内不可展示、两次插屏间隔 ≥ 60s、与激励视频之间也需 ≥ 60s。插件默认的启动门控 30s 恰好覆盖第一条，但插屏冷却默认 5s 低于抖音要求的 60s——启用抖音时面板「校验配置」会对插屏 cooldownSeconds < 60 与启动门控 < 30s 给出 warn（仅告警，不阻断保存 / 构建），建议把抖音插屏的 cooldownSeconds 设为 ≥ 60。另外，AdKit.isSupported('interstitial') 为 false 时会直接返回 unsupported。

Q21. 连点激励视频按钮会不会弹两次？
不会。插件同一时刻只允许一条广告展示流程在途（广告是模态资源）：展示中再次调用 showRewarded 会返回 { completed: false, reason: 'cooldown' }，再次调用 showInterstitial 会返回 { shown: false, reason: 'cooldown' }。连点按钮或多入口并发调用既不会弹出两条广告，也不会重复发起 load 请求。

⚠️ 购买须知

本产品为付费虚拟插件商品，一经购买成功概不退款，请支付前谨慎确认购买内容。

购买后获得对应版本授权，仅限授权范围内使用；
插件仅支持标注的 Cocos Creator 版本，请确认引擎版本符合要求再下单；
不包含定制开发服务，如有定制需求可单独咨询；
严禁二次分发、转售、反编译本插件。

📞 联系我们

如遇问题、有定制需求或希望增加广告平台 / 广告类型，欢迎联系作者：

官网：https://www.yyka.cn
邮箱：yykacn@qq.com
公众号：智能运营咖

关键词（商店后台标签）

Cocos Creator 插件、Cocos Creator 3.8、小游戏广告、IAA、广告接入、激励视频、插屏广告、微信小游戏、抖音小游戏、广告位管理、广告策略、预加载、重试退避、频控、每日上限、隐私授权、合规、埋点、事件模型、错误码归一化、构建集成、一键注入、TypeScript、adUnitId、AppID

感谢用户的内容

感谢每一位购买与反馈的朋友。

这个插件的起点很实在：微信和抖音的广告 API 不一样，每接一个平台就把预加载、重试、冷却、每日上限、隐私前置重写一遍，抄来抄去还容易漏配置、漏补平台文件。所以我们把它收进了面板——平台、广告位、策略、合规各占一页，配完存成一份 JSON；业务侧只剩一句 AdKit.showRewarded('revive')。

上线后收到的反馈（尤其是「预览怎么没广告」「为什么不能直接 import 配置」「插屏怎么一开始不弹」「构建会不会覆盖我的文件」这类较真的问题）都被逐条查到底、写进文档和自动化单测里。想接哪个新平台、想加哪种广告类型，随时找我们——你的接入场景，就是下一版的路线图。