🇺🇸 For English users, please refer to README_EN.md for the English version
Bingo 是一款专为广告开发者打造的跨平台桌面应用程序,它能帮助您快速构建、测试和发布跨平台的 Playable 可玩广告。无论您是面向 Facebook、Unity、AppLovin 还是其他主流广告平台,Bingo 都能为您提供一站式解决方案。
✅ 多平台一键覆盖 - 内置 20+ 个主流广告平台 SDK,单次构建同时输出所有渠道素材,无需为每个平台重复开发
- AppLovin、BIGO、Chartboost、Facebook、Google、InMobi
- ironSource、Kuaishou、Kwai、Liftoff、Mintegral、Moloco
- MyTarget、OceanEngine、Pangle、Snapchat、Tencent、TikTok
- Unity、Unity Playworks(Luna)、Vungle
- 以及通用 MRAID 构建:一份产物即可投放所有遵循 MRAID 规范的长尾平台(如 Aarki、Adikteev、BigaBid、YouAppi、Kayzen 等)
✅ 极致包体压缩 - 内置 WebP 图片压缩引擎,并采用 Base122 编码内嵌资源(相比 Base64 膨胀率从约 33% 降至约 14%),帮助广告素材轻松达标各平台文件大小限制
✅ 零门槛上手 - 无需搭建复杂构建环境,安装即用;接入 SDK 后,4 步完成从 Cocos Creator 到跨平台广告素材的完整流程
✅ 构建即交付(VIP 专属 CLI) - 内置命令行工具,支持 bingo.config.json 配置文件与 Cocos Creator 构建钩子,构建完成后自动产出各渠道交付文件,无需打开应用,无缝接入 CI/CD 流程
✅ 简洁专业界面 - 支持中英文切换和亮色/暗色主题,平台素材规范与测试工具一屏查看,降低日常维护成本
简洁直观的主界面,支持亮色/暗色主题和中英文界面切换,一键完成广告构建
- 添加产品:支持快速导入新广告项目,轻松管理多个项目
- 删除产品:一键移除不再需要的项目,保持工作区整洁
- 产品设置:自定义产品名称、别名和平台 URL
- 平台要求:展示各大广告平台的素材规范,包括文件大小限制和格式要求
- 测试工具:提供各平台的测试工具链接,方便快速验证广告素材
- 应用预览:支持在测试应用中预览广告效果
✅ 支持 Windows 和 macOS 操作系统(支持 Apple Silicon 及 Intel 芯片)
✅ 支持 Cocos Creator 版本:
- 2.4.11 及以上版本
- 3.8.0 及以上版本
✅ 全面支持 2D 和 3D 游戏开发
✅ 完全兼容 Cocos Creator 所有功能模块
获取 GitHub 体验版 - 下载最新的体验版本,抢先体验新功能
立即获取 Bingo 应用 - 前往 Cocos 商店购买和下载
💡 版本更新说明:由于 Cocos 商店审核周期较长,商店版本可能会有一定滞后。如果您发现商店版本不是最新版本,可以直接购买后凭支付记录截图,通过邮箱(458264325@qq.com)或微信联系我们获取与体验版相同的最新版本。
在使用 Bingo 构建广告前,需要先在 Cocos Creator 项目中接入 PlayableSDK.d.ts。这一步需要在游戏开发阶段完成,接入 SDK 后广告才具备跳转商店、响应平台音频/暂停控制等能力。
当用户点击下载按钮(CTA)或结束卡片时调用此方法,触发应用商店跳转。
当游戏结束时(无论胜利或失败)必须调用此方法。
⚠️ 重要:某些广告平台(如 Mintegral、Vungle)强制要求调用此方法,否则可能导致广告行为异常或统计数据不准确。
获取当前运行的广告渠道,可用于实现渠道差异化逻辑:
if (PlayableSDK.channel === 'Facebook') {
// Facebook 特定逻辑
} else if (PlayableSDK.channel === 'TikTok') {
// TikTok 特定逻辑
}注册静音/取消静音回调函数,用于响应平台的音频控制请求。
注册暂停/恢复回调函数。以下场景会触发这些回调:
| 回调 | 触发场景 |
|---|---|
onPause |
用户点击下载按钮跳转商店、广告进入后台、广告失去焦点 |
onResume |
用户从商店返回、广告回到前台、广告重新获得焦点 |
最佳实践:
- 在
onPause中暂停游戏动画、音效和计时器 - 在
onResume中恢复游戏状态,或考虑直接显示结束卡片
针对 AppLovin Playable Analytics,可上报加载、展示、挑战进度与转化等互动事件。
- 加载、展示、CTA、结束卡片等生命周期事件已由 SDK 自动上报(
LOADING/LOADED/DISPLAYED/CTA_CLICKED/ENDCARD_SHOWN),无需游戏方处理。 - 游戏内部的挑战类事件需手动上报,请使用可选链调用(该方法仅 AppLovin 渠道实现,其他渠道为
undefined,可选链可保证安全、不影响其他渠道):
PlayableSDK.trackEvent?.("CHALLENGE_STARTED");
PlayableSDK.trackEvent?.("CHALLENGE_PASS_25"); // 25 / 50 / 75
PlayableSDK.trackEvent?.("CHALLENGE_SOLVED");
⚠️ 注意:仅支持 AppLovin 预定义事件名(自定义事件无效);CHALLENGE_FAILED仅表示用户主动失败,不可用于崩溃、异常、加载失败等技术错误;CHALLENGE_*系列需先触发CHALLENGE_STARTED。
PlayableSDK.onMute(() => {
AudioManager.muteAll();
});
PlayableSDK.onUnmute(() => {
AudioManager.unmuteAll();
});
PlayableSDK.onPause(() => {
GameManager.pause();
});
PlayableSDK.onResume(() => {
GameManager.resume();
});完成 SDK 接入后,只需 4 步即可完成可玩广告的构建:
- 打开您的 Cocos Creator 项目
- 选择菜单「项目」→「构建发布」
- 目标平台选择「Web Mobile」
⚠️ 重要:确保不勾选「MD5 Cache」选项(详见打包配置注意事项)- 点击「构建」按钮,等待构建完成
- 打开 Bingo 应用
- 点击「选择」按钮,选择上一步生成的
web-mobile目录 - 点击「选择」按钮,指定输出目录(构建后的广告文件将保存在此处)
- 点击产品旁的「设置」按钮打开产品管理界面
- 添加或选择您的产品
- 配置产品的 Apple URL 和 Google Play URL(用于广告跳转和平台配置)
- 在渠道列表中勾选目标广告平台(可多选)
- 根据需要选择图片压缩模式:
- 无压缩:保持原始画质
- 无损压缩:转换为 WebP 格式,画质无损失
- 有损压缩:可调节质量参数,获得更小的包体
- 点击「构建」按钮
- 构建完成后,在输出目录中查看生成的广告文件
💡 提示:部分渠道(如 Facebook、Google、TikTok、Unity Playworks)会输出 ZIP 包,其他渠道输出单个 HTML 文件。
VIP 专属功能:Bingo CLI 命令行工具仅 VIP 版本可用,体验版调用任何 CLI 子命令都会提示升级并以退出码 1 结束。
Bingo 内置 CLI 命令行接口,可在 Cocos Creator 完成 web-mobile 构建之后,直接产出各广告平台(Facebook、TikTok、Google 等)的可玩广告交付文件,无需打开桌面应用,天然适合接入 CI/CD 与 Cocos Creator 构建钩子,实现「一键构建即交付」。
# 查看版本
bingo --cli version
# 列出全部支持的渠道
bingo --cli channels
# 构建可玩广告(参数也可通过 bingo.config.json 预配置)
bingo --cli build --web-mobile ./build/web-mobile --output ./playable-ads --product MyGame --channels Facebook,TikTok核心特性:
- headless 构建:不创建任何窗口,构建进度与产物绝对路径输出到 stdout(界面输出为英文),退出码明确(
0成功 /1失败),便于脚本与 CI 集成 - 配置文件:支持在工程根目录放置
bingo.config.json固化构建参数,参数优先级:命令行 > 配置文件 > 默认值 - 构建钩子接入:支持 Cocos Creator 3.x 构建扩展
onAfterBuild钩子与 2.x 脚本化构建,工程构建完成后自动产出交付文件,零人工干预 - 应用内指引:桌面应用「开发者选项」中新增「命令行工具 (CLI)」入口,可一键复制含本机安装路径的 alias 命令与常用命令示例,并可打开完整文档
📖 完整的调用方式(macOS / Windows)、参数与配置字段说明、Cocos Creator 2.x / 3.x 接入示例,请参阅 CLI 使用文档
Bingo 内置了强大的图片压缩引擎,可以有效减小广告包体积,帮助您满足各平台的文件大小限制。
| 模式 | 技术方案 | 压缩效果 | 画质影响 | 推荐场景 |
|---|---|---|---|---|
| 无压缩 | 保持原始格式 | 无 | 无损失 | 包体已满足要求,追求原始画质 |
| 无损压缩 | PNG/JPG → WebP | 约 20-40% | 无损失 | 平衡画质与体积 |
| 有损压缩 | WebP + 质量控制 | 约 50-80% | 轻微损失 | 需要极致压缩以满足平台限制 |
使用有损压缩时,您可以通过滑块调节质量参数(1-100):
- 100%:最高画质,压缩率较低
- 50%(推荐):平衡画质与体积
- 1%:最小体积,画质损失较大
Bingo 会自动对比压缩前后的文件大小:
- 如果压缩后体积更小,使用压缩版本
- 如果压缩后体积反而变大,自动保留原图
这确保了压缩操作始终是有益的,不会因为压缩导致包体变大。此外,Bingo 采用 Base122 编码内嵌游戏资源,相比 Base64 数据膨胀率从约 33% 降至约 14%,进一步压缩最终文件体积。
勾选 MD5 Cache 会导致可玩广告在某些平台上无法正常运行,因为:
- MD5 缓存会改变资源文件的命名规则
- 部分广告平台对文件名有严格要求
- 可能导致资源加载失败或路径错误
正确做法: 在构建设置中确保 "MD5 Cache" 选项保持未勾选状态。
document.write() 的兼容性问题
部分用户在 AppLovin 等平台的测试工具中测试可玩广告时,可能会遇到广告无法正常显示的问题。这通常是由于现代浏览器(Chrome 55+)对 document.write() 方法有更严格的限制,控制台可能会显示 Violation 警告。
解决方案:
- 使用 Chrome 无痕模式(Ctrl/Cmd + Shift + N)打开平台测试工具,通常可以正常显示
- 尝试使用其他浏览器进行测试(如 Safari),因为不同浏览器对
document.write()的限制程度不同 - 如果在平台测试工具中无法显示,请尝试在本地浏览器中直接打开 HTML 文件进行测试
在 Chrome 普通模式下本地预览可玩广告时,若控制台出现类似以下报错:
TypeError: Cannot read properties of null (reading 'getAssembler')
at inject.js:1
调用栈底部的 inject.js 是浏览器扩展注入的脚本,并非可玩文件自身的 bug。某些扩展(如性能监控、广告分析工具等)会向页面注入节点,导致 Cocos 引擎报错。该错误不影响游戏实际运行,真实用户在 Facebook/Instagram 等平台的 WebView 中不存在浏览器扩展,不会遇到此问题。
解决方法: 使用 Chrome 无痕模式(Ctrl/Cmd + Shift + N)预览,无痕模式默认禁用所有扩展,可获得与真实投放环境一致的测试结果。
查看 Bingo 生成的可玩广告示例 - 这些是通过 Bingo 工具生成的跨平台广告素材
如有任何问题或需求反馈,欢迎通过以下方式联系我:
-
email: 458264325@qq.com
-
微信
由于 Cocos 商店审核周期较长,商店版本可能滞后于体验版。如需最新版本,可参照获取 Bingo 联系我们。
- 修复 Google 渠道「第四方调用无效(Invalid fourth-party call)」拒审:移除
ExitApi.exit()失败后回退window.open直跳商店的逻辑,退出商店严格只走 Google 官方ExitApi.exit(),符合 Google 包内禁止未授权外部调用的政策 - 新增 Google 上传前审计工具:
tools/google-audit基于 CDP 本地模拟ExitApi正常 / 不可用两种场景,自动校验跳转与网络请求行为,退出码可直接接入提交门禁与 CI - 优化 Google 产物结构:改用与 Facebook 一致的 ZIP 包输出(
index.html+ 相对路径加载zip.js),不再注入<base href>,避免 CSP 冲突导致的「Unapproved third-party call」拒审(Cocos Creator 2.x / 3.x 均已适配) - 消除 Google h5validator 校验警告:产物自动注入内联 1×1 透明 GIF 懒加载占位符(
loading="lazy",data URI 不产生网络请求),消除「Asset preloading」建议项警告,且不影响游戏运行 - 全渠道跳转合规治理:移除所有渠道
download()中的浏览器兜底跳转(window.open/window.location/ 动态<a>),CTA 严格通过各平台宿主 API 触发(MRAID 系渠道统一使用mraid.open()),符合 Meta、Google、TikTok、Pangle 等平台「素材中不得包含 JavaScript 跳转」的审核要求,显著降低拒审风险 - ironSource 渠道迁移至 MRAID 3.0:遵循 ironSource 最新官方规范,从已废弃的 DAPI 迁移至 MRAID 3.0(head 注入
mraid.js,必选监听stateChange/viewableChange/audioVolumeChange,首次 viewable 后才启动游戏,CTA 使用mraid.open(HTTPS URL));应用内素材规范文案同步更新 - 优化 ZIP 产物可复现性:固定 ZIP 条目时间戳(1980-01-01)与 UNIX 平台属性,相同输入多次构建产物字节级一致、MD5 保持稳定,便于版本比对与 CI 缓存
- 新增 CLI 命令行工具(VIP 专属):支持
build/channels/version/help子命令,以 headless 模式(不创建窗口)构建可玩广告;英文进度与产物路径输出到 stdout,退出码明确(0成功 /1失败),方便接入脚本与 CI/CD - 新增
bingo.config.json配置文件:支持在工程中固化构建参数(web-mobile 路径、输出目录、产品信息、渠道、压缩设置等),参数优先级:命令行 > 配置文件 > 默认值;也支持BINGO_USER_DATA_DIR环境变量覆盖用户数据目录,适配 CI / 受限环境 - 新增应用内 CLI 使用指南:「开发者选项」新增「命令行工具 (CLI)」入口,VIP 用户可一键复制含本机安装路径的 alias 命令与常用命令示例,并可打开完整文档;体验版用户展示功能简介与升级引导
- 新增 CLI 使用文档:涵盖 macOS / Windows 调用方式、参数与配置说明、Cocos Creator 2.x / 3.x 构建钩子接入示例
- 重构构建管线:抽取无 Electron 依赖的核心构建管线,CLI 与桌面版共用同一构建流程,桌面版构建行为与产物完全一致
- 新增 AppLovin Playable Analytics 事件埋点:自动上报加载与转化事件(
LOADING/LOADED/DISPLAYED/CTA_CLICKED/ENDCARD_SHOWN),并通过PlayableSDK.trackEvent支持游戏上报挑战类事件(CHALLENGE_STARTED/CHALLENGE_PASS_25/50/75/CHALLENGE_SOLVED等)。所有埋点均带安全检查,仅在 AppLovin 渠道生效,对其他渠道零影响 - 优化 Unity Playworks 编码策略:对以未压缩 HTML 大小为审核标准的渠道(如 Unity Playworks)改用 Base122 编码,将内嵌资源膨胀率从约 33%(Base64)进一步降至约 14%,有效减小
source.html体积 - 修复 style.css 内联兼容性:构建时内联样式的匹配逻辑改为正则,同时兼容
<link ... />与<link ...>两种标签格式,修复部分 Cocos 版本生成的 HTML 样式未能正确内联、导致移动端屏幕适配失效的问题 - UI 优化:全面改进主界面布局,新增构建按钮前置验证(必填项未填时禁用并提示),引入 CSS 主题变量统一配色,优化渠道/压缩模式的键盘可访问性(方向键导航、ARIA 属性),以及构建进度弹窗性能优化
- 新增 macOS Intel 构建:CI 新增 macOS Intel(x64)构建任务,支持非 Apple Silicon 用户
- 新增「通用 MRAID」渠道:一份产物即可投放所有遵循 MRAID 规范的长尾平台(如 Aarki、Adikteev、BigaBid、YouAppi、Kayzen 等),无需为每个平台单独构建
- 新增「Unity Playworks(Luna)」渠道:自动导出
source.html、luna.json、playground.json组成的 Playworks ZIP 包,支持startGame启动协议、CTA 和 GameEnded API - 新增渠道:InMobi、快手(Kuaishou)、Kwai、MyTarget、巨量引擎(OceanEngine)、Pangle、Snapchat、Vungle / Liftoff
- 优化:统一 AppLovin、Chartboost、InMobi 等 MRAID 渠道的生命周期表现(后台暂停/恢复、平台静音、横竖屏自适应),与 Unity 渠道行为一致
- 优化:产品配置中的 Apple 链接统一命名为 Apple URL,并用于 Unity Playworks 的
iosLink生成 - 修复:解决使用 Spine 动画时在 Unity / AppLovin 测试 App 上卡在开场加载(splash loading)或黑屏的问题
- 修复:InMobi 跳转商店逻辑;更新腾讯优量汇 SDK 地址
- 下线:AdColony(已并入 Digital Turbine 生态,不再单独提供)
- 新增 Unity 渠道 MRAID 支持,增强 SDK 健壮性
- 优化
mraid.open跳转与应用商店 URL 选择逻辑 - 完善 SDK 接入指南与产品介绍文档
- 早期版本,奠定多渠道一键构建、图片压缩与 Base122 内嵌等核心能力



