Tutorial: SDK Upgrade Guide

SDK Upgrade Guide

The SDK versions below introduced API changes, in some cases breaking changes.


  1. Modify the callback parameter of Client.on('client-banned') event to return the reason for the passive kickout, which can be prompted accordingly. The original ErrorCode.CLIENT_BANNED is deprecated in this version.
// v4.14.0 and later
client.on('client-banned', event => {
  console.log(`reason: ${event.reason}, message: ${event.message}`);
  // prompt the user according to the corresponding reason
// Versions prior to v4.14.0
client.on('client-banned', error => {
  console.error('client-banned observed: ' + error);
  // Prompt for checkout


  1. In live mode, if audiences with the same userId repeatedly enter the same room, TRTC backend can't guarantee to kick each other. In order to avoid potential state conflicts that may lead to business exceptions, the following validate logic has been added to client.join in this version:

When calling the client.join api to join a room in live mode, client.join will fail if the SDK detects that a client with the same userId is already in the room on the current page.

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 }) // unable to join same room with same userId, RtcError will be thrown.
} catch(error) {
await clientB.join({ roomId: 22222 }) // able to join room.


  1. The mirror parameter of TRTC.createStream is deprecated, use stream.play instead.


  1. client.setRemoteVideoStreamType changes from synchronous interface to asynchronous interface, and returns Promise object, which can be used to determine whether switch big/small stream is successful. For details, please refer to Enabling Dual-Channel Mode


  1. This version enables enableAutoPlayDialog configuration by default, when there is autoplay failure, SDK will show an UI dialog to guide users to click the page for solving the autoplay failure issue. Reference: Suggested Solutions for Autoplay Restrictions.

    If the UI dialog has been implemented in your business to solve the autoplay failure problem. Then when upgrading to this version, you can set enableAutoPlayDialog to false in TRTC.createClient to disable the UI dialog in the SDK.

  2. To avoid possible audio playback silent issue, TRTC.getMicrophones no longer returns microphones with deviceId 'default' & 'communications'. Reference: Chrome issues case 8 & 9.


  1. To avoid potential exceptions that may occur with incorrect parameter types, this version of the SDK adds a strong parameter type check for key APIs. If your previous business code does not match the parameter types described in the SDK documentation, an error may be reported when you call the interface after upgrading to this version. Please adjust the parameter type according to the error message and the SDK interface documentation.


Changed the response of TRTC.checkSystemRequirements. For details, please see the API document.

  • In v4.9.0 and later versions, isH264Supported in checkResult.detail is replaced by isH264EncodeSupported, isVp8EncodeSupported, isH264DecodeSupported, and isVp8DecodeSupported.


  1. Deleted the disused API Client.setDefaultMuteRemoteStream. Please use the autoSubscribe parameter of TRTC.createClient instead.

  2. Required verification of the roomId parameter for the Client.join() API.

  • If roomId is a number, it must be an integer from 1 to 4294967294.
  • If roomId is a string, it must not exceed 64 bytes and can contain the following characters:
    • Letters (A-Z and a-z)
    • Digits (0-9)
    • Space, "!", "#", "$", "%", "&", "(", ")", "+", "-", ":", ";", "<", "=", ".", ">", "?", "@", "[", "]", "^", "_", "{", "}", "|", "~", ","

Note: The default data type of roomId is number. To use string-type roomId, set useStringRoomId to true when calling TRTC.createClient.

Sample code:

// Use numeric roomId.
let client = TRTC.createClient({
await client.join({ roomId: 1024 });  // The roomId passed in must be an integer from 1 to 4294967294.
// Use string-type roomId.
let client = TRTC.createClient({
  useStringRoomId: true  // To use string-type roomId, set useStringRoomId to true.
await client.join({ roomId: 'hello' });  // The roomId passed in must be a string and must meet the requirements on length and characters.


Introduced a breaking change to the TRTC.checkSystemRequirements API.

  • In versions earlier than v4.7.0, a Boolean value is returned from the promise, which indicates whether the SDK is compatible with the browser checked.
  • In v4.7.0 and later versions, an object is returned from the promise, which contains detailed results of the compatibility check. For more information, please TRTC.checkSystemRequirements.

Sample code for old and new versions:

// Versions earlier than v4.7.0
TRTC.checkSystemRequirements().then((result) => {
  if(!result) {
     console('Your browser is not compatible with TRTC');
     // The SDK is not compatible with the browser. Ask the user to use the latest version of Chrome.
// v4.7.0 and later versions
TRTC.checkSystemRequirements().then((checkResult) => {
  if(!checkResult.result) {
     console.log('checkResult', checkResult.result, 'checkDetail', checkResult.detail);
      // The SDK is not compatible with the browser. Recommend a browser supported by the SDK based on the user’s device.