主题
Skip to content
YouTube 小游戏接入
YouTube 小游戏属于 H5 渠道，使用 Cocos Creator 的 Web 手机端构建产物接入。本页说明渠道限制、SDK 生命周期、音频与暂停控制、构建模板以及测试流程。
渠道特性
接入前需重点确认包体、加载性能和音频行为：
- 初始软件包必须小于 30 MiB。统计范围为网页开始加载至游戏调用
gameReady的时刻。 - 总软件包大小必须小于 250 MiB。
- 单个文件必须小于 30 MiB。
- 加载时间需要小于 5 秒。
- 游戏必须通过
isAudioEnabled和onAudioEnabledChange遵从 YouTube 的音频设置和静音按钮。 - 游戏必须遵从设备音量控制。
- 游戏不得意外播放声音。
- YouTube 处于静音状态时，游戏不得输出音频，且游戏内音频控件不得绕过该状态。
- YouTube 未静音时，游戏内音频控件可以进一步调整音频输出。
接入流程
游戏首帧上报
当游戏已经渲染加载画面或启动画面，能够明确告知用户正在加载时，调用 firstFrameReady。该接口必须先于 gameReady 调用，否则系统不会向用户显示游戏。
如果 YouTube 测试页面长时间黑屏，可将调用位置前移到首个可见画面完成之后。
javascript
GameHelper.CCGlobal.api.game.firstFrameReady();可互动状态上报
当主菜单或游戏场景已经准备好接受用户操作时调用 gameReady。加载画面仍不可互动时不要调用。
javascript
GameHelper.CCGlobal.api.game.gameReady();音频开关控制
YouTube 要求游戏使用渠道状态控制音频。启动时先读取 isAudioEnabled，运行期间再通过 onAudioEnabledChange 监听静音状态变化。
获取音频启用状态：
javascript
if (GameHelper.YTAdapter.isAudioEnabled()) {
// 启用游戏音频
} else {
// 关闭游戏音频
}监听音频设置变化：
javascript
GameHelper.YTAdapter.onAudioEnabledChange((isAudioEnabled) => {
if (isAudioEnabled) {
// 启用游戏音频
} else {
// 关闭游戏音频
}
});暂停和继续
游戏必须通过渠道回调处理暂停和恢复：
- 触发
onPause后，游戏必须暂停所有执行，包括游戏循环、音乐和互动；仅在触发onResume后恢复。 - 触发
onPause时，游戏应保存用户进度。
javascript
GameHelper.YTAdapter.onPause(() => {
pauseGame();
});
GameHelper.YTAdapter.onResume(() => {
resumeGame();
});广告相关
该渠道支持插屏广告和激励视频广告，调用项目内通用的插屏、视频展示接口即可。该渠道不支持 Banner 广告，调用 showBanner 不会生效。
构建流程
在构建发布配置中选择 Web 手机端
编辑构建模板
- 首次构建 Web 包时不要勾选 MD5 Cache。
- 打开构建包根目录中的
index.html，在任何游戏代码之前引入 YouTube Playables SDK：
html
<script src="https://www.youtube.com/game_api/v1"></script>建议将上述脚本放在 <head> 中，并确保它位于游戏脚本之前：
- 将修改后的
index.html放入构建模板目录：
text
工程根目录\build-templates\web-mobile- 可选：添加启动页。如果调用
firstFrameReady时画面仍为黑屏，审核可能无法通过。可以在index.html中加入启动图，并在首个场景完成加载后移除。
html
<body>
<img
id="LaunchPageImage"
src="page.jpg"
alt=""
style="position: absolute; left: 0; top: 0; width: 100%; height: 100%; z-index: 10000;"
/>
<script>
function removeLaunchPageAfterGameFrame() {
const timer = setInterval(function () {
if (!window.cc || !cc.director) return;
clearInterval(timer);
const removeLaunchPage = function () {
requestAnimationFrame(function () {
const launchPage = document.getElementById("LaunchPageImage");
if (launchPage) launchPage.remove();
});
};
cc.director.once(
cc.Director.EVENT_AFTER_SCENE_LAUNCH,
removeLaunchPage,
);
}, 16);
}
removeLaunchPageAfterGameFrame();
</script>
</body>测试流程
项目构建完成后，在 Cocos Creator 中点击“运行”。
复制浏览器中打开的游戏地址。
将地址粘贴到测试套件的
Game URL中开始测试。
注意
测试期间必须保持 Cocos 本地预览服务运行，否则测试页面无法加载游戏。
