概述
为方便 Web 应用开发者调试和接入腾讯云游戏多媒体引擎产品 H5 SDK,这里向您介绍用最短路径跑通「进房 → 开麦 → 开扬声器 → 退房」这条主链路,全程只需4步。
环境要求
项目 | 要求 |
浏览器 | Chrome / Edge / Safari / Firefox 最近两个大版本。 |
页面协议 | HTTPS 或 http://localhost(浏览器仅在安全上下文下允许采集麦克风)。 |
账号 | 已在控制台创建应用,拿到 SDKAppID 与 SECRETKEY。 |
浏览器运行时只依赖
GMEWebSDK.js 这一个静态文件,部署到任意静态服务器或 CDN 即可。接入流程总览
引入 GMEWebSDK.js↓WebGMEAPI.getInstance() 获取单例↓setTMGDelegate() 注册事件回调(必须在进房前)↓init(sdkAppId, userId) 初始化↓enterRoom(...) 进房(结果通过事件回调返回)↓enableMic(true) / enableSpeaker(true)↓exitRoom() 退房
关键约束
setTMGDelegate() 必须在 enterRoom() 之前调用,否则收不到进房结果。enterRoom() 不返回 Promise,进房成功/失败通过事件 ITMG_MAIN_EVENT_TYPE_ENTER_ROOM 回调。所有音频操作(开麦、开扬声器、伴奏等)都必须在进房成功之后调用。
接入步骤
步骤一:引入 SDK
<script src="./GMEWebSDK.js"></script>
引入顺序:
必须在业务脚本之前引入 SDK,否则会出现
WebGMEAPI is not defined。步骤二:初始化并注册回调
// 1. 获取单例(全局唯一,重复调用返回同一实例)const gmeAPI = WebGMEAPI.getInstance();// 2. 设置日志等级(可选,建议联调阶段用 DEBUG)// 0:TRACE 1:DEBUG 2:INFO 3:WARN 4:ERROR 5:NONEgmeAPI.setLogLevel(1);// 3. 注册事件回调(必须在 enterRoom 之前)function onGmeEvent(eventType, data) {switch (eventType) {case WebGMEAPI.event.ITMG_MAIN_EVENT_TYPE_ENTER_ROOM:console.log(data.errorCode === 0 ? '进房成功' : '进房失败:' + data.errorMsg);break;case WebGMEAPI.event.ITMG_MAIN_EVENT_TYPE_EXIT_ROOM:console.log('已退房');break;case WebGMEAPI.event.ITMG_MAIN_EVENT_TYPE_ROOM_DISCONNECT:console.warn('房间断开:', data.message);break;case WebGMEAPI.event.ITMG_MAIN_EVENT_TYPE_USER_UPDATE:console.log(data.type === 1 ? '用户进房:' : '用户退房:', data.userId);break;default:break;}}gmeAPI.setTMGDelegate(onGmeEvent);// 4. 初始化(必须早于 enterRoom)const SDK_APP_ID = 160000000;const userId = 'user_10001';gmeAPI.init(SDK_APP_ID, userId);
进房结果事件数据
字段 | 说明 |
errorCode | 0表示进房成功,非0表示失败。 |
errorMsg | 失败原因描述。 |
步骤三:获取 UserSig
UserSig 是进房鉴权签名,由 SDKAppID、UserID、SECRETKEY 计算得出,必须由业务后台签发。正确做法:后台使用
SECRETKEY 计算 UserSig,前端在进房前向自己的业务接口请求:// 向业务后台请求 UserSig,后台用 SDKAppID + SECRETKEY + userId 计算后返回async function fetchUserSig(userId) {const res = await fetch(`https://your-server.com/api/getUserSig?userId=${userId}`);const { userSig } = await res.json();return userSig;}
联调阶段:可临时使用控制台生成的 UserSig 硬编码在页面中,用于快速验证链路。切勿在生产环境这样操作,前端代码中的
SECRETKEY 可被轻易逆向,密钥泄露会导致流量被盗用。步骤四:进房与音频控制
下面是一个最小可运行的完整页面,替换
SDK_APP_ID 与 UserSig 获取方式后即可跑通。<!DOCTYPE html><html lang="zh-CN"><head><meta charset="UTF-8"><title>GME Web Quick Start</title></head><body><button id="enter">进入房间</button><button id="mic">开启麦克风</button><button id="speaker">开启扬声器</button><button id="exit">退出房间</button><!-- 1. 引入 SDK --><script src="./GMEWebSDK.js"></script><script>const SDK_APP_ID = 0; // 替换为您的 SDKAppIDconst userId = 'user_10001'; // 房间内唯一,不可重复const roomId = '202101'; // 字符串房间号,两端一致即进入同一房间const roomType = 1;const gmeAPI = WebGMEAPI.getInstance();let inRoom = false;// 2. 注册事件回调gmeAPI.setLogLevel(1);gmeAPI.setTMGDelegate((eventType, data) => {if (eventType === WebGMEAPI.event.ITMG_MAIN_EVENT_TYPE_ENTER_ROOM) {inRoom = data.errorCode === 0;console.log(inRoom ? '进房成功' : '进房失败:' + data.errorMsg);}if (eventType === WebGMEAPI.event.ITMG_MAIN_EVENT_TYPE_EXIT_ROOM ||eventType === WebGMEAPI.event.ITMG_MAIN_EVENT_TYPE_ROOM_DISCONNECT) {inRoom = false;}});// 3. 初始化gmeAPI.init(SDK_APP_ID, userId);// 4. 进房:userSig 由业务后台签发,privateMapKey 无权限控制时可传空字符串document.getElementById('enter').onclick = async () => {const userSig = await fetchUserSig(userId);gmeAPI.enterRoom(roomId, roomType, userSig, '');};// 5. 开麦 / 开扬声器:必须等进房成功回调之后document.getElementById('mic').onclick = async () => {if (inRoom) await gmeAPI.enableMic(true);};document.getElementById('speaker').onclick = async () => {if (inRoom) await gmeAPI.enableSpeaker(true);};// 6. 退房document.getElementById('exit').onclick = () => {gmeAPI.exitRoom();};async function fetchUserSig(uid) {const res = await fetch(`https://your-server.com/api/getUserSig?userId=${uid}`);const { userSig } = await res.json();return userSig;}</script></body></html>
enterRoom 参数说明参数 | 类型 | 必填 | 说明 |
roomID | string | 是 | 房间号。 |
roomType | number | 是 | 房间类型,传1。 |
userSig | string | 是 | 后台签发的进房签名。 |
privateMapKey | string | 是 | 权限加密串,无权限控制时传 ''。 |
scene | string | 否 | 'rtc' 实时通话(默认)/ 'live' 互动直播。 |
role | string | 否 | 'anchor' 主播 / 'audience' 观众。不传时 rtc 默认为 anchor,live 默认为 audience。 |
上线前检查清单
页面通过 HTTPS 部署(麦克风采集需要安全上下文)。
UserSig 由业务后台签发,前端代码中不含 SECRETKEY。UserSig 有效期设置合理(建议数小时),过期后重新获取。全房间
userId 唯一,避免互相踢出。已处理
ITMG_MAIN_EVENT_TYPE_ENTER_ROOM 的失败分支(errorCode !== 0)。已处理
ITMG_MAIN_EVENT_TYPE_ROOM_DISCONNECT(被踢出、网络断开)并引导重连。页面切后台/最小化时调用
pause(),回到前台调用 resume()。首次进房由用户点击触发(规避浏览器自动播放限制)。
关键注意事项
进房后立即静音远端:SDK 进房成功后会执行
muteRemoteAudio('*', true),因此必须调用 enableSpeaker(true) 才能听到远端和伴奏声音。进房后自动推流但默认静音:SDK 进房成功后会以静音方式开启本地音频,开麦请调用
enableMic(true),不要重复调用底层推流接口。扬声器与伴奏联动:扬声器关闭时,所有伴奏的实际播放音量会被置为 0;重新
enableSpeaker(true) 后自动恢复为设定音量。暂停态限制:调用
pause() 后,enableMic()、enableSpeaker()、startPlayMusic() 等接口会被直接拦截并返回,需先 resume()。角色默认值:未显式指定角色时,
live 场景默认为 audience,rtc 场景默认为 anchor。userId 唯一性:同一房间内
userId 不可重复,否则会互相踢出。核心能力速查
除
init() 外,以下接口均需在进房成功后调用。能力 | 接口 | 说明 |
初始化 | init(sdkAppId, userId) | 必须早于 enterRoom()。 |
进房 | enterRoom(roomId, roomType, userSig, privateMapKey, scene, role) | 结果走事件回调。 |
退房 | exitRoom() | 自动停止伴奏、清理状态。 |
查询是否在房 | isRoomEntered() | 返回 boolean。 |
开关麦克风 | enableMic(enable, micId?) | micId 为空表示默认设备。 |
开关扬声器 | enableSpeaker(enable) | 关闭时伴奏音量同步为0。 |
采集音量 | setMicVolume(volume) | 默认100,> 100为放大。 |
静音某个远端 | muteRemoteAudio(userId, mute) | 不受扬声器开关影响。 |
远端播放音量 | setRemoteAudioVolume(userId, volume) | 支持 '*' 表示所有人。 |
设备列表 | getMicrophones() / getSpeakers() | 返回 Promise。 |
切换设备 | selectMic(micId) / selectSpeaker(speakerId) | 需对应设备已开启。 |
播放伴奏 | startPlayMusic(soundId, url, loop, volume) | volume 取值 0~1。 |
伴奏控制 | pausePlayMusic() / resumePlayMusic() / stopPlayMusic() | 按 soundId 操作。 |
设置伴奏进度 | seekMusicToPosInTime(soundId, time) | 单位:秒。 |
整体暂停/恢复 | pause() / resume() | 页面切后台、最小化时使用。 |
角色切换 | switchRole(role, privateMapKey?) | 仅 LIVE 场景有意义。 |
自定义消息 | sendCustomMessage(cmdId, data) | data 为 ArrayBuffer。 |
完整的参数、类型、返回值等参照 SDK 中的
gme.d.ts 和 type.d.ts 文件。常见问题排查
现象 | 排查方向 |
听不到远端声音 | 是否调用 enableSpeaker(true);是否对目标用户执行过 muteRemoteAudio(userId, true);远端是否开麦。 |
对方听不到我 | 是否调用 enableMic(true);浏览器是否已授权麦克风;是否处于 pause() 状态。 |
进房失败 | 检查 SDKAppID 与 UserSig 是否匹配;UserSig 是否过期;控制台查看 errorMsg。 |
伴奏没有声音 | 是否已进房;扬声器是否开启;音乐 URL 是否可访问且支持 CORS;音量是否为0。 |
提示不支持自动播放 | 浏览器策略限制,需用户产生一次交互(点击)后再播放音频。 |
WebGMEAPI 未定义 | GMEWebSDK.js 是否在业务脚本之前引入;资源路径是否正确。 |
设备列表为空 / 无法采集 | 页面必须通过 https 或 http://localhost 访问,且已授予麦克风权限。 |