Tutorial: SDK 升级指引

SDK 升级指引

如下罗列的 SDK 版本存在接口变更或 Breaking Change,升级时需要注意。

v4.14.0 版本

  1. 修改 Client.on('client-banned') 事件的回调参数,返回被动退房原因,可以根据原因做出相应的提示。原有的 ErrorCode.CLIENT_BANNED 在该版本废弃。
// v4.14.0 及其之后的版本
client.on('client-banned', event => {
  console.log(`reason: ${event.reason}, message: ${event.message}`);
  // 根据对应的 reason 提示用户
});
// v4.14.0 之前的版本
client.on('client-banned', error => {
  console.error('client-banned observed: ' + error);
  // 提示退房
});

v4.12.6 版本

  1. live 模式下,具备相同 userId 的观众,重复进入同一个房间,TRTC 后台无法保证互踢。为避免潜在的状态冲突导致业务异常,该版本 client.join 新增了如下拦截逻辑:

live 模式下调用 client.join 接口进房时,若 SDK 检测到当前页面已经有相同 userId 的 client 在房间内了,此时 client.join 会调用失败。

业务代码应避免相同的 userId 重复进入同一个房间。

const clientA = TRTC.createClient({ sdkAppId: 1400000000, userId: 'test1', mode: 'live', userSig: 'fake' });
const clientB = TRTC.createClient({ sdkAppId: 1400000000, userId: 'test1', mode: 'live', userSig: 'fake' });
await clientA.join({ roomId: 12345 })
try {
  await clientB.join({ roomId: 12345 }) // 相同 userId 进相同房间,无法进房,sdk 会抛出 RtcError。
} catch(error) {
  console.error(error);
}
await clientB.join({ roomId: 22222 }) // 可正常进房。

v4.12.1 版本

  1. TRTC.createStream 废弃 streamConfig.mirror 参数。设置视频镜像播放请参考 stream.play(elementId, { mirror: true })

v4.12.0 版本

  1. client.setRemoteVideoStreamType 由同步接口改为异步接口,返回 Promise 对象,可根据 Promise 的结果来判断切换大小流是否成功。具体使用说明参见 开启大小流传输

  2. 企业内网代理方案中 Nginx 代理的 websocket 域名,由 qcloud.rtc.qq.com 变更为 signaling.rtc.qq.com

  • 对于 4.12.0 及以上版本,Nginx 配置的 websocket 代理域名为:signaling.rtc.qq.com
  • 对于 4.12.0 以下版本,Nginx 配置的 websocket 代理域名为:qcloud.rtc.qq.com

v4.11.9 版本

  1. 该版本默认开启 enableAutoPlayDialog 配置,当出现自动播放失败时,SDK 会在页面中弹窗引导用户点击页面,以解决自动播放失败问题。详情参考:自动播放受限处理建议

    若在您的业务中,已实现了相关弹窗逻辑,以解决自动播放失败的问题。那么在升级至该版本时,可在 TRTC.createClient 中将 enableAutoPlayDialog 设置为 false 来关闭 SDK 的弹窗。

  2. 为规避可能出现的无声问题,TRTC.getMicrophones 不再返回 deviceId 为 'default' & 'communications' 的麦克风。详情参考:Chrome 已知问题 case 8 & 9

v4.11.7 版本

  1. 为规避参数类型错误可能出现的潜在异常,该版本 SDK 增加了关键接口的参数类型强校验。若您之前的业务代码传入的参数类型,与 SDK 文档描述不符,升级到该版本后,调用接口可能会出现报错。请根据报错信息及 SDK 接口文档调整参数类型。

v4.9.0 版本

TRTC.checkSystemRequirements 返回详细检测结果发生变更,具体请参见 接口文档

  • v4.9.0 及其以上版本的 SDK: checkResult.detail 移除了 isH264Supported,新增了 isH264EncodeSupported,isVp8EncodeSupported,isH264DecodeSupported 以及 isVp8DecodeSupported。

v4.8.2 版本

  1. 删除已废弃接口:Client.setDefaultMuteRemoteStream,请使用 TRTC.createClient 的 autoSubscribe 参数替代.

  2. Client.join 接口增加了 roomId 参数的强校验。升级时需注意。

  • roomId 使用 number 类型时,取值要求为 [1, 4294967294] 的整数;
  • roomId 使用 string 类型时,限制长度为64字节,且仅支持以下范围的字符集:
    • 大小写英文字母(a-zA-Z);
    • 数字(0-9);
    • 空格、"!"、"#"、"$"、"%"、"&"、"("、")"、"+"、"-"、":"、";"、"<"、"="、"."、">"、"?"、"@"、"["、"]"、"^"、"_"、" {"、"}"、"|"、"~"、",";

注意:

  • roomId 默认使用 number 类型,如需使用 string 类型的 roomId,请在执行 TRTC.createClient 时设置 useStringRoomId 为 true。

示例代码:

// roomId 使用 number 类型
let client = TRTC.createClient({
  mode,
  sdkAppId,
  userId,
  userSig
});
await client.join({ roomId: 1024 });  // 传入的 roomId 必须为 [1, 4294967294] 的整数
// roomId 使用 string 类型
let client = TRTC.createClient({
  mode,
  sdkAppId,
  userId,
  userSig,
  useStringRoomId: true  // roomId 使用 string 类型时,必须设置 useStringRoomId 为 true
});
await client.join({ roomId: 'hello' });  // 传入的 roomId 必须为 string 类型,且字符与长度符合要求

v4.7.0 版本

TRTC.checkSystemRequirements 接口在该版本有 Breaking Change。升级时需要注意。

  • v4.7.0 以下版本的该接口: Promise 返回 boolean, 表示 SDK 是否支持当前浏览器。
  • v4.7.0 及其以上版本的该接口: Promise 返回 object, 支持返回详细的检测结果,详见 TRTC.checkSystemRequirements

用法差异如下:

// v4.7.0 以下版本的 SDK
TRTC.checkSystemRequirements().then((result) => {
  if(!result) {
     console('Your browser is not compatible with TRTC');
     // SDK 不支持当前浏览器,建议用户使用最新版本的 Chrome 浏览器。
  }
});
// v4.7.0 及其以上版本的 SDK
TRTC.checkSystemRequirements().then((checkResult) => {
  if(!checkResult.result) {
     console.log('checkResult', checkResult.result, 'checkDetail', checkResult.detail);
      // SDK 不支持当前浏览器,根据用户设备类型建议用户使用 SDK 支持的浏览器
  }
});