帮你快速理解、总结文档立即下载
文档中心>游戏多媒体引擎

Web&H5

最近更新时间:2026-09-30 15:57:18
我的收藏

概述

为方便 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

下载 SDK,解压并打开,把 GMEWebSDK.js 放到项目的静态资源目录,用 <script> 标签引入,引入后即可使用全局变量 WebGMEAPI:
<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:NONE
gmeAPI.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; // 替换为您的 SDKAppID
const 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 访问,且已授予麦克风权限。