Skip to content

About

Bingo is a desktop application designed specifically for ad developers. It helps you quickly build, test, and publish cross-platform playable ads. Whether you're targeting Facebook, Unity, AppLovin, or other major ad platforms, Bingo offers a one-stop solution for all your needs.

Topics

Resources

Stars

94 stars

Watchers

1 watching

Forks

Repository files navigation

🇺🇸 For English users, please refer to README_EN.md for the English version

Bingo 可玩广告构建工具

让广告开发更简单高效

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 所有功能模块

获取 Bingo

体验版本

获取 GitHub 体验版 - 下载最新的体验版本,抢先体验新功能

正式版本

立即获取 Bingo 应用 - 前往 Cocos 商店购买和下载

💡 版本更新说明:由于 Cocos 商店审核周期较长,商店版本可能会有一定滞后。如果您发现商店版本不是最新版本,可以直接购买后凭支付记录截图,通过邮箱(458264325@qq.com)或微信联系我们获取与体验版相同的最新版本。

前置准备:SDK 接入

在使用 Bingo 构建广告前,需要先在 Cocos Creator 项目中接入 PlayableSDK.d.ts。这一步需要在游戏开发阶段完成,接入 SDK 后广告才具备跳转商店、响应平台音频/暂停控制等能力。

核心接口

1. download() - 跳转应用商店

当用户点击下载按钮(CTA)或结束卡片时调用此方法,触发应用商店跳转。

2. game_end() - 游戏结束通知

当游戏结束时(无论胜利或失败)必须调用此方法。

⚠️ 重要:某些广告平台(如 Mintegral、Vungle)强制要求调用此方法,否则可能导致广告行为异常或统计数据不准确。

3. channel - 获取当前渠道(只读)

获取当前运行的广告渠道,可用于实现渠道差异化逻辑:

if (PlayableSDK.channel === 'Facebook') {
    // Facebook 特定逻辑
} else if (PlayableSDK.channel === 'TikTok') {
    // TikTok 特定逻辑
}

生命周期回调接口

4. onMute(callback) / onUnmute(callback) - 音频控制

注册静音/取消静音回调函数,用于响应平台的音频控制请求。

5. onPause(callback) / onResume(callback) - 暂停/恢复

注册暂停/恢复回调函数。以下场景会触发这些回调:

回调 触发场景
onPause 用户点击下载按钮跳转商店、广告进入后台、广告失去焦点
onResume 用户从商店返回、广告回到前台、广告重新获得焦点

最佳实践:

  • 在 onPause 中暂停游戏动画、音效和计时器
  • 在 onResume 中恢复游戏状态,或考虑直接显示结束卡片

数据埋点接口(AppLovin 专用)

6. trackEvent(eventName) - 上报 Playable Analytics 事件

针对 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 步即可完成可玩广告的构建:

第 1 步:在 Cocos Creator 中构建项目

  1. 打开您的 Cocos Creator 项目
  2. 选择菜单「项目」→「构建发布」
  3. 目标平台选择「Web Mobile」
  4. ⚠️ 重要:确保不勾选「MD5 Cache」选项(详见打包配置注意事项)
  5. 点击「构建」按钮,等待构建完成

第 2 步:配置项目路径

  1. 打开 Bingo 应用
  2. 点击「选择」按钮,选择上一步生成的 web-mobile 目录
  3. 点击「选择」按钮,指定输出目录(构建后的广告文件将保存在此处)

第 3 步:配置产品信息

  1. 点击产品旁的「设置」按钮打开产品管理界面
  2. 添加或选择您的产品
  3. 配置产品的 Apple URL 和 Google Play URL(用于广告跳转和平台配置)

第 4 步:选择渠道并构建

  1. 在渠道列表中勾选目标广告平台(可多选)
  2. 根据需要选择图片压缩模式:
    • 无压缩:保持原始画质
    • 无损压缩:转换为 WebP 格式,画质无损失
    • 有损压缩:可调节质量参数,获得更小的包体
  3. 点击「构建」按钮
  4. 构建完成后,在输出目录中查看生成的广告文件

💡 提示:部分渠道(如 Facebook、Google、TikTok、Unity Playworks)会输出 ZIP 包,其他渠道输出单个 HTML 文件。

命令行工具 (CLI)

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%,进一步压缩最终文件体积。

重要配置说明

打包配置注意事项

⚠️ 重要提示:在使用 Cocos Creator 打包项目时,请务必不要勾选 "MD5 Cache" 选项

MD5 Cache配置

勾选 MD5 Cache 会导致可玩广告在某些平台上无法正常运行,因为:

  • MD5 缓存会改变资源文件的命名规则
  • 部分广告平台对文件名有严格要求
  • 可能导致资源加载失败或路径错误

正确做法: 在构建设置中确保 "MD5 Cache" 选项保持未勾选状态。

平台测试注意事项

⚠️ 关于 document.write() 的兼容性问题

部分用户在 AppLovin 等平台的测试工具中测试可玩广告时,可能会遇到广告无法正常显示的问题。这通常是由于现代浏览器(Chrome 55+)对 document.write() 方法有更严格的限制,控制台可能会显示 Violation 警告。

解决方案:

  • 使用 Chrome 无痕模式(Ctrl/Cmd + Shift + N)打开平台测试工具,通常可以正常显示
  • 尝试使用其他浏览器进行测试(如 Safari),因为不同浏览器对 document.write() 的限制程度不同
  • 如果在平台测试工具中无法显示,请尝试在本地浏览器中直接打开 HTML 文件进行测试

⚠️ 关于 Chrome 扩展注入导致的干扰报错

在 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 工具生成的跨平台广告素材

联系我们

如有任何问题或需求反馈,欢迎通过以下方式联系我:

更新日志

由于 Cocos 商店审核周期较长,商店版本可能滞后于体验版。如需最新版本,可参照获取 Bingo 联系我们。

2.0.7

  • 修复 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 缓存

2.0.6

  • 新增 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 与桌面版共用同一构建流程,桌面版构建行为与产物完全一致

2.0.5

  • 新增 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 用户

2.0.4

  • 新增「通用 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 生态,不再单独提供)

2.0.3

  • 新增 Unity 渠道 MRAID 支持,增强 SDK 健壮性
  • 优化 mraid.open 跳转与应用商店 URL 选择逻辑
  • 完善 SDK 接入指南与产品介绍文档

2.0.2

  • 早期版本,奠定多渠道一键构建、图片压缩与 Base122 内嵌等核心能力

About

Bingo is a desktop application designed specifically for ad developers. It helps you quickly build, test, and publish cross-platform playable ads. Whether you're targeting Facebook, Unity, AppLovin, or other major ad platforms, Bingo offers a one-stop solution for all your needs.

Topics

Resources

Stars

94 stars

Watchers

1 watching

Forks

Releases

Used by

Contributors

Languages