1. 项目概述与核心价值如果你正在用 Cocos Creator 开发可玩广告并且需要把同一个游戏包投放到 Facebook、Google、Unity Ads、TikTok 等不同的广告平台那你一定遇到过这个让人头疼的问题每个平台对可玩广告的打包格式、SDK 注入、启动逻辑甚至文件命名都有自己的一套“规矩”。手动为每个平台单独修改、构建、测试不仅效率低下还极易出错一个疏忽就可能导致广告无法正常展示直接影响投放效果和收益。“Cocos Playable Ads 多网络适配插件”就是为了解决这个痛点而生的。它本质上是一个 Cocos Creator 编辑器插件能够让你在 Cocos Creator 内通过一次配置一键生成适配多个广告渠道的可玩广告包。你不用再关心各个平台繁琐的技术细节插件会帮你处理好渠道标识注入、平台特定 SDK 脚本插入、HTML 结构适配、甚至图片压缩和代码混淆等优化工作。对于需要大规模投放可玩广告的团队或个人开发者来说这个插件能将跨渠道发布的效率提升数倍同时保证构建产出的标准化和可靠性。简单来说它的核心价值就是“一次开发多渠道发布”把开发者从重复、琐碎且容易出错的跨平台适配工作中解放出来让你能更专注于游戏玩法本身和广告创意的优化。2. 插件核心功能与适配原理拆解2.1 支持的渠道与兼容性这个插件目前覆盖了主流的可玩广告投放渠道。根据其官方文档对 Cocos Creator 2.x 和 3.x 版本都有良好的支持。主要支持渠道包括AppLovinFacebook(Meta)Google(Google Ads)IronSourceLiftoffMintegralMolocoPangle(穿山甲)RubeexTikTokUnity(Unity Ads)版本兼容性Cocos Creator 2.4.6 及以上所有上述渠道均支持。Cocos Creator 3.8.x所有上述渠道均支持。对于其他版本如 2.4.6 以下或 3.x 的其他小版本官方建议自行测试但社区反馈通常也表现良好。注意不同广告网络的可玩广告技术规范如 MRAID 版本、API 支持度、文件大小限制可能随时更新。插件会尽力跟进主流规范但在使用前特别是针对新兴渠道或特殊要求建议仍以各广告平台最新的官方文档为准进行最终验证。2.2 插件工作的核心原理插件的工作原理可以概括为“构建后处理”模式。它并没有深度侵入 Cocos Creator 的构建管线而是在 Cocos Creator 完成标准的 Web 平台web-mobile 或 web-desktop构建后对产出的构建文件夹进行“再加工”。其处理流程大致如下监听构建完成当你在 Cocos Creator 编辑器中选择“多渠道构建”并点击开始后插件会等待 Cocos 自身的构建流程结束。读取渠道配置插件会读取项目根目录下的配置文件.adapterrc确定需要为哪些渠道生成包以及每个渠道需要哪些特殊处理。渠道包复制与定制为配置中指定的每一个渠道复制一份原始的 Cocos 构建产出作为该渠道包的基础。内容注入与替换这是核心步骤。插件会遍历每个渠道包的代码文件主要是index.html和main.js等渠道标识替换查找代码中的特定占位符如{{__adv_channels_adapter__}}并将其替换为当前渠道的实际名称如Facebook。这为游戏逻辑中区分渠道提供了可能。SDK 脚本注入根据配置在 HTML 文件的head或body特定位置插入该渠道要求的 SDK 脚本标签例如Unity Ads 需要的mraid.js。自定义 HTML 注入同样根据配置注入任何渠道特定的 HTML 片段或内联脚本用于处理渠道独有的启动、关闭或交互逻辑。资源优化可选如果配置开启插件会调用 TinyPNG API 对图片进行压缩或使用 Pako 库对代码文本资源进行 Gzip 压缩以进一步减小包体满足各平台的严格大小限制。输出结构化目录最终所有处理好的渠道包会按照清晰的目录结构输出方便你直接上传到对应的广告平台。这种设计非常巧妙它利用了 Cocos 构建产物的稳定性通过后处理的方式实现差异化既保证了与 Cocos 官方构建的兼容性又提供了极高的灵活性。3. 插件安装与项目配置详解3.1 插件下载与安装插件的发布页在 GitHub Releases。你需要根据自己使用的 Cocos Creator 主版本2.x 或 3.x下载对应的插件包。访问发布页打开https://github.com/ppgee/cocos-pnp/releases。查找以playable-ads-adapter开名的、版本号最新的.zip文件。通常文件名会类似playable-ads-adapter-1.3.10.zip。选择版本确认该版本支持的 Cocos Creator 版本通常在 Release Notes 里说明。一般来说插件包是向前兼容的一个包可能同时支持 2.4.x 和 3.x但为了稳定建议使用与你的 Cocos 大版本匹配的发布包。解压与放置下载完成后解压这个 ZIP 文件。对于 Cocos Creator 2.x 项目将解压后的整个插件文件夹复制到你的项目根目录下的packages文件夹中。如果项目没有packages文件夹请手动创建一个。对于 Cocos Creator 3.x 项目将解压后的整个插件文件夹复制到你的项目根目录下的extensions文件夹中。同样如果没有extensions文件夹则手动创建。重启编辑器放置完成后务必完全关闭并重新启动 Cocos Creator然后打开你的项目。这是为了让编辑器正确扫描并加载新安装的插件。实操心得我遇到过好几次插件“不显示”的情况十有八九是因为没有重启编辑器。另外确保插件文件夹的名字没有多余的空格或特殊字符直接使用解压后的原名即可。安装成功后你会在 Cocos Creator 编辑器上方的工具栏中看到“多渠道构建”的按钮。3.2 核心配置文件.adapterrc解析项目根目录下的.adapterrc文件是整个插件的“大脑”所有多渠道适配的行为都由它控制。这个文件是一个 JSON 格式的配置文件。下面我们详细拆解每一个配置项的作用和写法。基础配置示例与说明{ buildPlatform: web-mobile, orientation: auto, exportChannels: [Facebook, Google, TikTok, Unity], skipBuild: false, enableSplash: true, isZip: true, tinify: false, tinifyApiKey: , injectOptions: { Facebook: { head: , body: , sdkScript: }, Unity: { head: , body: script/* 你的Unity MRAID 启动逻辑 *//script, sdkScript: script src\./mraid.js\/script } } }buildPlatform(可选): 指定 Cocos 的构建平台。必须是web-mobile或web-desktop。通常可玩广告使用web-mobile。如果留空插件会尝试自动判断或使用默认值。orientation(可选): 设备方向。可选portrait(竖屏)、landscape(横屏)、auto(自动)。需要与你在 Cocos 项目设置中配置的方向一致。exportChannels(可选): 一个字符串数组指定你想要导出的渠道。例如[Facebook, Google]。如果数组为空或整个字段不配置则默认导出所有支持的渠道。强烈建议显式配置只导出你需要的渠道以节省构建时间。skipBuild(可选): 布尔值默认为false。如果设置为true插件将跳过触发 Cocos Creator 构建的步骤直接基于项目目录下已有的最新构建产出如build/web-mobile进行多渠道处理。这在需要反复调试渠道适配逻辑而游戏内容本身未改变时非常有用。enableSplash(可选): 布尔值默认为true。是否启用插件自带的加载闪屏。有些广告平台要求可玩广告加载时不能有自制的 Loading 图这时可以将其设为false但你需要确保你的游戏有合适的加载体验。isZip(可选): 布尔值默认为true。是否使用 Pako 对生成的 HTML 和 JS 等文本文件进行 Gzip 压缩。这能有效减小包体但最终上传到广告平台时可能需要是未压缩的源文件请根据平台要求决定。开启后输出目录中会同时存在压缩版和未压缩版。tinify(可选): 布尔值默认为false。是否使用 TinyPNG 服务压缩项目中的 PNG/JPG 图片。这是进一步瘦包的利器。tinifyApiKey(可选): 字符串。当tinify: true时必须在此填入你在 TinyPNG 官网申请的 API Key。每个 Key 每月有 500 次免费压缩额度对于可玩广告通常够用。3.3 高级功能injectOptions深度配置injectOptions对象是实现各渠道差异化适配的关键。你可以为每一个在exportChannels中列出的渠道配置三种注入内容head: 字符串。这段 HTML 代码会被注入到生成页面的head标签末尾。通常用于放置一些渠道要求的meta标签或需要在页面早期加载的脚本。body: 字符串。这段 HTML 代码会被注入到body标签内部但在所有 Cocos 引擎脚本之前。这是最常用的位置用于放置渠道的广告控制逻辑、事件监听等。sdkScript: 字符串。这是一个特化的注入插件会智能地将这段脚本通常是script src.../script放入正确的位置。对于像 Unity Ads 这样严格要求mraid.js必须在特定位置先于游戏代码加载的渠道使用这个字段最稳妥。配置示例Unity Ads 适配Unity Ads 的可玩广告强烈依赖 MRAID (Mobile Rich Media Ad Interface Definitions) 协议。你的游戏需要等待 MRAID SDK 准备就绪后才能启动。injectOptions: { Unity: { body: script// 等待MRAID就绪的逻辑\nif(mraid.getState() loading) {\n mraid.addEventListener(ready, window.onSdkReady);\n} else {\n window.onSdkReady();\n}\n// 视图可见性变化监听\nfunction viewableChangeHandler(viewable) {\n if(viewable) {\n // 广告变为可见可以开始游戏或播放动画\n } else {\n // 广告不可见可能需要暂停游戏\n }\n}\n// SDK就绪回调\nwindow.onSdkReady function() {\n mraid.addEventListener(viewableChange, viewableChangeHandler);\n if(mraid.isViewable()) {\n // 如果已经可见直接启动游戏\n cc.game.run();\n }\n};/script, sdkScript: script src\./mraid.js\/script } }在这个配置中sdkScript确保了mraid.js被引入。body中的脚本则包含了标准的 MRAID 检测和事件监听逻辑并最终在环境准备好后通过调用cc.game.run()来启动 Cocos 游戏。你需要将你游戏中的启动调用可能是gameStart()之类的函数整合到这个逻辑里。配置示例动态渠道标识如果你想在游戏代码中知道当前运行在哪个平台可以使用占位符替换功能。在你的游戏全局代码例如main.js或一个全局脚本中定义一个变量// 注意这个变量必须被使用否则构建优化时可能会被删除 window.advChannel {{__adv_channels_adapter__}};在插件处理 Facebook 渠道包时会自动将{{__adv_channels_adapter__}}替换为字符串Facebook。这样你就可以在游戏中通过window.advChannel来判断渠道执行不同的逻辑比如不同的结束跳转链接、不同的数据上报点。4. 完整工作流与实操步骤4.1 第一步项目与插件基础准备假设我们有一个名为MyPlayableAd的 Cocos Creator 3.8.1 项目需要投放至 Facebook、Google 和 Unity Ads。环境确认确保你的 Cocos Creator 版本是受支持的如 3.8.x。在编辑器中打开你的项目。安装插件从 GitHub Releases 下载对应 3.x 的插件包解压后放入项目根目录的extensions文件夹。重启 Cocos Creator。创建配置文件在项目根目录与assets、extensions同级下新建一个名为.adapterrc的文本文件。注意文件名以点开头。编写基础配置用文本编辑器如 VSCode打开.adapterrc填入最基础的配置{ buildPlatform: web-mobile, orientation: portrait, exportChannels: [Facebook, Google, Unity], skipBuild: false, enableSplash: true, isZip: true }保存文件。4.2 第二步配置渠道特定的注入逻辑现在我们需要为每个渠道补充injectOptions。这通常需要查阅各广告平台最新的可玩广告技术文档。Facebook: 通常需要注入其特定的 SDK 和事件监听。示例Facebook: { head: meta property\fb:app_id\ content\你的APP_ID\ /, body: scriptwindow.fbPlayableAd.onCTAClick();/script, sdkScript: script src\https://connect.facebook.net/en_US/fbplayablead.js\/script }fb:app_id需要替换为你 Facebook 应用的实际 ID。fbPlayableAd.onCTAClick()是 Facebook 规定的点击调用行动号召按钮的方法。Google: 可能需要处理退出 API。Google: { body: a id\exit-api-anchor\ onclick\ExitApi.exit()\ style\display: none;\/ascriptfunction exitGoogleAd() { document.getElementById(exit-api-anchor).click(); }/script, sdkScript: }这里在 body 中注入了一个隐藏的锚点并定义了一个exitGoogleAd函数。当你的游戏需要结束并跳转时调用window.exitGoogleAd()即可。Unity: 使用前面章节提供的 MRAID 适配脚本。将这三部分合并到injectOptions中你的完整.adapterrc文件看起来应该是这样的{ buildPlatform: web-mobile, orientation: portrait, exportChannels: [Facebook, Google, Unity], skipBuild: false, enableSplash: true, isZip: true, tinify: true, tinifyApiKey: your_tinypng_api_key_here, injectOptions: { Facebook: { head: meta property\fb:app_id\ content\123456789\ /, body: scriptwindow.fbPlayableAd.onCTAClick();/script, sdkScript: script src\https://connect.facebook.net/en_US/fbplayablead.js\/script }, Google: { body: a id\exit-api-anchor\ onclick\ExitApi.exit()\ style\display: none;\/ascriptfunction exitGoogleAd() { document.getElementById(exit-api-anchor).click(); }/script, sdkScript: }, Unity: { body: scriptif(mraid.getState() loading) { mraid.addEventListener(ready, window.onSdkReady); } else { window.onSdkReady(); } function viewableChangeHandler(viewable) { if(viewable) { } else { } } window.onSdkReady function() { mraid.addEventListener(viewableChange, viewableChangeHandler); if(mraid.isViewable()) { cc.game.run(); } };/script, sdkScript: script src\./mraid.js\/script } } }切记将fb:app_id和tinifyApiKey替换为你自己的真实值。4.3 第三步在游戏代码中集成渠道逻辑为了让游戏能响应不同渠道的环境我们需要修改游戏代码。定义全局渠道变量在一个全局可访问的脚本中例如GameManager.ts或Main.ts添加// 声明一个全局变量用于接收插件替换后的渠道名 declare global { interface Window { advChannel: string; } } // 或者如果使用占位符方式 // const advChannel {{__adv_channels_adapter__}}; // 插件构建时会替换修改游戏启动逻辑通常 Cocos Creator 3.x 的游戏在main.ts或类似入口文件通过game.run()启动。我们需要将其改为受控启动。// main.ts 或你的游戏启动文件 import { game } from cc; // 自定义启动函数 function startGame() { // 你的游戏初始化代码... game.run(); } // 判断渠道并执行相应的启动准备 if (window.advChannel Unity) { // Unity渠道依赖MRAID启动由前面注入的body脚本中的onSdkReady控制 // 将startGame函数挂载到window供注入的脚本调用 window.startGame startGame; // 同时修改前面注入的Unity body脚本将 cc.game.run() 改为 window.startGame() } else { // Facebook、Google等渠道通常可以直接启动或等待其SDK的特定事件 // 例如Facebook可以监听fbPlayableAd.loaded事件 if (window.advChannel Facebook window.fbPlayableAd) { window.fbPlayableAd.onLoad(() { startGame(); }); } else { // 其他渠道或默认情况直接启动 startGame(); } }修改结束逻辑游戏结束时需要根据渠道调用不同的退出函数。// 游戏结束点击跳转按钮时 function onGameEnd() { const channel window.advChannel; switch(channel) { case Facebook: if (window.fbPlayableAd window.fbPlayableAd.onCTAClick) { window.fbPlayableAd.onCTAClick(); } break; case Google: if (typeof window.exitGoogleAd function) { window.exitGoogleAd(); // 调用我们在注入脚本中定义的函数 } break; case Unity: if (typeof mraid ! undefined mraid.open) { mraid.open(你的跳转链接); } break; default: // 默认跳转或上报错误 window.location.href 默认链接; } }4.4 第四步执行多渠道构建与产出配置构建参数在 Cocos Creator 编辑器中打开“项目设置”在“构建”页面确保“Web 平台”的相关设置如起始场景、分辨率策略、MD5 Cache 等符合你的要求。尤其注意“压缩纹理”、“图片压缩”等选项它们会与插件的 Tinify 功能共同影响最终包大小。执行构建点击编辑器主工具栏上的“多渠道构建”按钮。在弹出的面板中确认配置信息它主要读取.adapterrc。点击“开始构建”。此时Cocos Creator 会先进行一次标准的“web-mobile”构建。构建完成后插件开始工作你会在 Cocos Creator 的控制台看到类似“开始适配 Facebook 渠道...”的日志。获取产出构建完成后打开项目根目录下的build文件夹。你会发现除了常规的web-mobile文件夹外多出了一个playable-adapter文件夹或类似名称。进入该文件夹你会看到以渠道命名的子文件夹例如Facebook、Google、Unity。每个渠道文件夹内都包含了一个完整的、适配了该渠道的可玩广告包。如果配置了isZip: true你可能会看到xxx.zip文件和一个xxx_source文件夹前者是压缩版后者是未压缩的源码版。上传平台时请确认平台要求的是哪一种。本地测试强烈建议在将包上传到广告平台前进行本地测试。你可以使用一个简单的本地 HTTP 服务器如http-server来运行这些渠道包并在浏览器开发者工具中模拟移动设备检查控制台有无报错基本的游戏流程和结束跳转逻辑是否正常。5. 常见问题排查与进阶技巧5.1 构建过程报错与解决问题现象可能原因解决方案点击“多渠道构建”无反应或报“插件未找到”1. 插件未正确安装到packages(2.x) 或extensions(3.x) 目录。2. 编辑器未重启。3. 插件文件夹结构不正确。1. 检查插件文件夹路径。2. 完全关闭并重启 Cocos Creator。3. 确保解压后的插件文件夹直接放在上述目录内而不是嵌套了一层。构建时报 JSON 解析错误.adapterrc文件格式错误存在多余的逗号、引号不匹配等 JSON 语法问题。使用 JSON 验证工具如 VSCode 自带验证或在线 JSON 格式化工具检查并修正.adapterrc文件。控制台日志显示适配成功但输出目录没有渠道文件夹exportChannels配置为空或未配置且插件内部默认渠道列表可能与你预期不符。skipBuild为true但原构建目录不存在。1. 显式配置exportChannels。2. 当skipBuild: true时确保项目下已有一次成功的web-mobile构建产出。Tinify 图片压缩失败报 API Key 错误1.tinifyApiKey未配置或配置错误。2. 免费月度额度已用完。3. 网络问题。1. 检查 API Key 是否正确确保在 TinyPNG 开发者页面获取。2. 登录 TinyPNG 官网查看额度。3. 暂时关闭tinify选项或检查网络连接。生成的渠道包在平台上无法加载白屏1. 渠道特定的 SDK 脚本加载失败路径错误、网络问题。2. 注入的 JavaScript 代码存在语法错误导致整个页面脚本执行中断。3. 游戏启动逻辑与渠道 SDK 就绪事件未正确同步。1. 检查sdkScript的 src 地址是否正确、可访问。对于本地文件如mraid.js确保它被正确复制到了构建输出目录。2. 将注入的body脚本内容复制到浏览器控制台检查语法。3. 在浏览器开发者工具中调试确认mraid、fbPlayableAd等 SDK 对象是否已正确加载以及游戏启动函数是否在正确时机被调用。5.2 渠道包体积优化技巧可玩广告对包体大小通常要求 5MB 甚至更小极其敏感。除了插件提供的 Tinify 和 Pako 压缩你还需要在 Cocos 项目本身下功夫纹理优化使用压缩纹理格式在 Cocos Creator 的资源管理器中选择图片在属性检查器中设置合适的压缩格式如 ASTC、PVRTC、ETC2。这能大幅减少纹理内存和下载体积。合理设置 Max Size非背景的大图最大尺寸尽量不要超过 1024x1024。启用“压缩纹理”构建选项。音频优化将背景音乐和音效转换为码率更低的格式如.mp3或.ogg。裁剪音频长度避免不必要的静音部分。引擎裁剪如果项目简单在 Cocos Creator 构建面板中可以尝试取消勾选一些用不到的引擎模块如物理引擎、3D 粒子等。代码层面避免引入过大的第三方库。使用构建分析工具检查包体组成。5.3 调试与日志输出在开发阶段为了便于调试各渠道的逻辑你可以在注入的脚本或游戏代码中加入渠道特定的日志。// 在 .adapterrc 的 injectOptions 的 body 中 Facebook: { body: scriptconsole.log([FB Playable] SDK injected.); window._DEBUG_FB true;/script, ... } // 在游戏代码中 if (window.advChannel Facebook window._DEBUG_FB) { console.log(当前渠道: ${window.advChannel}, FB SDK状态:, window.fbPlayableAd); }构建后在浏览器控制台查看这些日志可以清晰了解代码执行流程。上线前请移除或关闭这些调试代码。5.4 关于 MRAID.js 文件Unity 等渠道依赖的mraid.js文件通常需要由广告平台提供或从该平台的示例包中获取。你不能随意使用一个来源不明的mraid.js。正确的做法是从目标广告平台如 Unity Ads 后台的官方文档或示例项目中获取其要求的mraid.js文件。将该文件放入你的 Cocos 项目的某个目录下例如assets/resources/mraid/。在 Cocos Creator 中将该文件的“导入为插件”属性设为 true以确保它会被原样导出到构建目录。在.adapterrc的sdkScript配置中使用相对路径引用它script src\./mraid.js\/script。插件在复制渠道包时会确保这个相对路径指向正确的文件。处理过多渠道的可玩广告发布后我最大的体会是标准化和自动化的重要性。在项目初期就引入这套插件工作流虽然需要一些学习成本来配置.adapterrc和调整游戏启动逻辑但一旦跑通后续任何内容更新都只需要点击一次“多渠道构建”所有平台的包就都准备好了极大地避免了人为失误也把团队从繁琐的重复劳动中解放了出来。尤其是在进行 A/B 测试或频繁更新广告创意时这种效率优势更加明显。最后一个小建议是为每个项目建立一个渠道配置的“知识库”记录下各平台最新的 SDK 要求、跳转方式以及常见的坑点这会让团队的新成员上手更快也让整个发布流程更加稳健。
与阻塞定价机制解析)
