频道相关

getUserInfoByUid

通过传入用户 ID 获取用户信息。

Java

public abstract int getUserInfoByUid(int uid, UserInfo userInfo);

当远端用户加入频道后，SDK 会获取该远端用户的用户 ID 和用户 User Account，并将其缓存在映射表中，同时在本地客户端触发 onUserInfoUpdated 回调。收到该回调后，你可以调用 getUserInfoByUid 方法并传入用户 ID，从 UserInfo 对象中获取指定用户的用户 User Account。

调用时机

该方法在收到 onUserInfoUpdated 回调后调用。

参数

uid

uid，表示用户 ID。

userInfo

输入和输出参数，用于标识用户信息的 UserInfo 对象。详见 UserInfo。

返回值

• 0：方法调用成功。
• < 0：方法调用失败。详见错误码了解详情和解决建议。

所属接口类

• RtcEngine

getUserInfoByUidEx

通过传入用户 ID 获取用户信息。

Java

public abstract int getUserInfoByUidEx(int uid, UserInfo userInfo, RtcConnection connection);

当远端用户加入频道后，SDK 会获取该远端用户的用户 ID 和用户 User Account，并将其缓存在映射表中，同时在本地客户端触发 onUserInfoUpdated 回调。收到该回调后，你可以调用 getUserInfoByUidEx 并传入用户 ID，从 UserInfo 对象中获取指定用户的用户 User Account。

适用场景

适用于多频道场景。

参数

uid

用户 ID。

userInfo

用于标识用户信息的对象。详见 UserInfo。

connection

连接信息。详见 RtcConnection。

返回值

• 方法调用成功，返回 UserInfo 对象。
• 方法调用失败，返回 null。

所属接口类

• RtcEngineEx

getUserInfoByUserAccount

通过传入用户 User Account 获取用户信息。

Java

public abstract int getUserInfoByUserAccount(String userAccount, UserInfo userInfo);

当远端用户加入频道后，SDK 会获取该远端用户的用户 ID 和用户 User Account，并将其缓存在映射表中，同时在本地客户端触发 onUserInfoUpdated 回调。收到该回调后，你可以调用 getUserInfoByUserAccount 方法并传入用户 User Account，从 UserInfo 对象中获取指定用户的信息。

参数

userAccount

用户 User Account。

userInfo

用于标识用户信息的 UserInfo 对象。详见 UserInfo。

返回值

• 0：方法调用成功。
• < 0：方法调用失败。详见错误码了解详情和解决建议。

所属接口类

• RtcEngine

getUserInfoByUserAccountEx

通过用户 User Account 获取用户信息。

Java

public abstract int getUserInfoByUserAccountEx(String userAccount, UserInfo userInfo, RtcConnection connection);

远端用户加入频道后，SDK 会获取该远端用户的用户 ID 和用户 User Account，并将其缓存在映射表中，同时在本地客户端触发 onUserInfoUpdated 回调。收到该回调后，你可以调用 getUserInfoByUserAccountEx 并传入用户 User Account，从 UserInfo 对象中获取指定用户的用户信息。

适用场景

该方法适用于多频道场景。

参数

userAccount

用户 User Account。

userInfo

输入和输出参数，用于标识用户信息。详见 UserInfo。

connection

连接信息。详见 RtcConnection。

返回值

• 0：方法调用成功。
• < 0：方法调用失败。详见错误码了解详情和解决建议。

所属接口类

• RtcEngineEx

joinChannel [1/2]

加入一个频道。

Java

public abstract int joinChannel(String token, String channelId, String optionalInfo, int uid);

默认情况下，用户会订阅频道中其他所有用户的音视频流，从而产生使用量和计费。如需停止订阅指定流或所有远端流，请调用管理发布与订阅的相关方法。

信息

• 该方法仅支持用户同时加入一个频道。
• 不同 App ID 的用户无法互通。
• 加入频道前，请确保用于生成 Token 的 App ID 与调用 create [2/2] 方法时传入的 App ID 相同，否则可能会导致加入频道失败。

调用时机

请在调用 create [2/2] 方法后调用本方法。

相关回调

调用该方法成功后会触发以下回调：

• 本地客户端：onJoinChannelSuccess 和 onConnectionStateChanged 回调。
• 远端客户端：如果是 COMMUNICATION 频道场景中有用户加入频道，或 LIVE_BROADCASTING 频道场景中有主播加入频道，则触发 onUserJoined 回调。

当由于网络状况不佳导致本地客户端与声网服务器的连接中断时，SDK 会尝试重连服务器。当本地客户端成功重回频道时，SDK 会触发本地客户端的 onRejoinChannelSuccess 回调。

参数

token

在你的服务器上生成的用于鉴权的 Token。

信息

• （推荐）如果你的项目启用了安全模式（使用 App ID 和 Token 进行鉴权），该参数为必填。
• 如果你仅启用了测试模式（使用 App ID 进行鉴权），该参数为可选。成功加入频道后，24 小时后会自动退出频道。
• 如果你需要同时加入多个频道或在频道间切换，声网建议使用通配符 Token，这样每次加入频道时无需重新申请 Token。

channelId

频道名。在相同 App ID 的前提下，填写相同频道名的用户会进入同一个频道进行音视频互动。字符串长度必须小于 64 字节。支持的字符（共 89 个）：

• 所有小写英文字母：a 到 z。
• 所有大写英文字母：A 到 Z。
• 所有数字字符：0 到 9。
• "!", "#", "$", "%", "&", "(", ")", "+", "-", ":", ";", "<", "=", ".", ">", "?", "@", "[", "]", "^", "_", "{", "}", "|", "~", ","

optionalInfo

（可选）预留参数。

uid

用户 ID。用于标识频道中的用户以进行实时音视频互动。你需要自行设置和管理用户 ID，并确保同一频道中每个用户 ID 唯一。该参数为 32 位有符号整数，取值范围为 -2^31 到 2^31-1。如果未指定用户 ID（或设置为 0），SDK 会自动分配一个随机用户 ID，并通过 onJoinChannelSuccess 回调返回。你的应用需记录并维护该返回的用户 ID，SDK 不会保存。

返回值

• 0：方法调用成功。
• < 0：方法调用失败。详见错误码了解详情和解决建议。
  • -2：参数无效。例如，Token 无效，uid 参数未设置为整数，或 ChannelMediaOptions 中的成员值无效。请传入有效参数后重新加入频道。
  • -3：RtcEngine 对象初始化失败。请重新初始化 RtcEngine 对象。
  • -7：RtcEngine 对象尚未初始化。请先初始化 RtcEngine 对象再调用该方法。
  • -8：RtcEngine 对象内部状态错误。常见原因是在调用 startEchoTest 开始通话回声测试后，未调用 stopEchoTest 停止测试就调用该方法加入频道。请先调用 stopEchoTest 再调用该方法。
  • -17：加入频道请求被拒绝。常见原因是用户已在频道中。声网建议使用 onConnectionStateChanged 回调判断用户是否在频道中。只有在收到 CONNECTION_STATE_DISCONNECTED（1）状态时才调用该方法加入频道。
  • -102：频道名无效。请在 channelId 中传入有效的频道名重新加入频道。
  • -121：用户 ID 无效。请在 uid 中传入有效的用户 ID 重新加入频道。

所属接口类

• RtcEngine

joinChannel [2/2]

加入频道并设置媒体选项。

Java

public abstract int joinChannel(String token, String channelId, int uid, ChannelMediaOptions options);

该方法新增 options 参数，用于设置媒体选项，例如是否在频道内发布音视频流，或在加入频道时是否自动订阅所有远端用户的音视频流。默认情况下，用户会订阅频道中所有其他用户的音视频流，从而产生使用量和计费。如需停止订阅其他流，请设置 options 参数或调用管理发布与订阅的相关方法。

信息

• 该方法仅支持用户同时加入一个频道。
• 不同 App ID 的用户无法互通。
• 加入频道前，请确保用于生成 Token 的 App ID 与调用 create [2/2] 方法时传入的 App ID 一致，否则可能导致加入频道失败。

调用时机

请在调用 create [2/2] 方法后调用该方法。

相关回调

调用该方法成功后会触发以下回调：

• 本地客户端：onJoinChannelSuccess 和 onConnectionStateChanged 回调。
• 远端客户端：如果用户在 COMMUNICATION 频道场景中加入频道，或主播在 LIVE_BROADCASTING 频道场景中加入频道，会触发 onUserJoined 回调。

当由于网络状况不佳导致本地客户端与声网服务器的连接中断时，SDK 会尝试重新连接服务器。当本地客户端成功重新加入频道时，SDK 会在本地客户端触发 onRejoinChannelSuccess 回调。

参数

token

在你的服务器上生成的用于鉴权的 Token。

信息

• （推荐）如果你的项目启用了安全模式（使用 App ID 和 Token 进行鉴权），该参数为必填。
• 如果只启用了测试模式（使用 App ID 进行鉴权），该参数为可选。成功加入频道后，24 小时后会自动退出频道。
• 如果你需要同时加入多个频道或在频道间切换，声网建议使用通配符 Token，这样每次加入频道时无需重新申请 Token。

channelId

频道名。在相同 App ID 的前提下，填写相同频道名的用户会进入同一个频道进行音视频互动。字符串长度必须小于 64 字节。支持的字符（共 89 个）：

• 所有小写英文字母：a 到 z。
• 所有大写英文字母：A 到 Z。
• 所有数字字符：0 到 9。
• "!", "#", "$", "%", "&", "(", ")", "+", "-", ":", ";", "<", "=", ".", ">", "?", "@", "[", "]", "^", "_", "{", "}", "|", "~", ","。

uid

用户 ID。用于标识频道中的用户。你需要自行设置和管理用户 ID，并确保同一频道中每个用户 ID 唯一。该参数为 32 位有符号整数，取值范围为 -2³¹ 到 2³¹-1。如果未指定用户 ID（或设置为 0），SDK 会自动分配一个随机用户 ID，并在 onJoinChannelSuccess 回调中返回。你的应用必须记录并维护该返回的用户 ID，SDK 不会保存。

options

频道媒体选项，详见 ChannelMediaOptions。

返回值

• 0：方法调用成功。
• < 0：方法调用失败。详见错误码了解详情和解决建议。
  • -2：参数无效。例如，Token 无效，uid 参数未设置为整数，或 options 中的成员值无效。请传入有效参数并重新加入频道。
  • -3：RtcEngine 对象初始化失败。请重新初始化 RtcEngine 对象。
  • -7：RtcEngine 对象尚未初始化。请先初始化 RtcEngine 对象再调用该方法。
  • -8：RtcEngine 对象内部状态错误。常见原因是在调用 startEchoTest 开始通话回声测试后，未调用 stopEchoTest 停止测试就调用该方法加入频道。请先调用 stopEchoTest 再调用该方法。
  • -17：加入频道请求被拒绝。常见原因是用户已在频道中。声网建议使用 onConnectionStateChanged 回调判断用户是否在频道中。只有在收到 CONNECTION_STATE_DISCONNECTED（1）状态时才调用该方法加入频道。
  • -102：频道名无效。请在 channelId 中传入有效的频道名重新加入频道。
  • -121：用户 ID 无效。请在 uid 中传入有效的用户 ID 重新加入频道。

所属接口类

• RtcEngine

joinChannelEx

加入一个频道。

Java

public abstract int joinChannelEx(String token, RtcConnection connection, ChannelMediaOptions options, IRtcEngineEventHandler eventHandler);

你可以多次调用此方法加入多个频道。 在多摄像头采集场景中，调用此方法后需要调用 startPreview 方法，并将 sourceType 设置为 VIDEO_SOURCE_CAMERA_SECONDARY，以确保第二路摄像头正常采集。

信息

如果你已经在一个频道中，不能使用相同的用户 ID 重新加入该频道。 在加入频道前，确保用于生成 Token 的 App ID 与调用 create [2/2] 方法时传入的 App ID 相同，否则可能会导致加入频道失败。

适用场景

该方法适用于多频道场景。

调用时机

在调用 create [2/2] 方法之后调用。

相关回调

成功调用该方法会触发以下回调：

• 本地客户端：onJoinChannelSuccess 和 onConnectionStateChanged 回调。
• 远端客户端：如果是 COMMUNICATION 频道场景中有用户加入频道，或 LIVE_BROADCASTING 频道场景中有主播加入频道，则触发 onUserJoined 回调。

当由于网络状况不佳导致本地客户端与声网服务器的连接中断时，SDK 会尝试重连服务器。当本地客户端成功重新加入频道时，SDK 会触发本地客户端的 onRejoinChannelSuccess 回调。

参数

token

用于鉴权的 Token。

信息

• （推荐）如果你的项目启用了安全模式（使用 App ID 和 Token 进行鉴权），该参数为必填。
• 如果你只启用了测试模式（使用 App ID 进行鉴权），该参数为可选。成功加入频道后，你将在 24 小时后自动退出频道。
• 如果你需要同时加入不同频道或在频道之间切换，声网建议使用通配符 Token，这样你每次加入频道时无需重新申请 Token。

connection

连接信息。详见 RtcConnection。

options

频道媒体选项。详见 ChannelMediaOptions。

eventHandler

回调类。详见 IRtcEngineEventHandler。你可以通过该参数传入的 eventHandler 对象获取多个频道的回调事件。

返回值

• 0：方法调用成功。
• < 0：方法调用失败。详见错误码了解详情和解决建议。
  • -2：参数无效。例如，Token 无效，uid 参数未设置为整数，或 ChannelMediaOptions 中的成员值无效。你需要传入有效参数并重新加入频道。
  • -3：初始化 RtcEngine 对象失败。你需要重新初始化 RtcEngine 对象。
  • -7：RtcEngine 对象尚未初始化。你需要先初始化 RtcEngine 对象再调用此方法。
  • -8：RtcEngine 对象的内部状态错误。典型原因是在调用 startEchoTest 开始通话回路测试后，未调用 stopEchoTest 停止测试就调用此方法加入频道。你需要先调用 stopEchoTest 再调用此方法。
  • -17：加入频道请求被拒绝。典型原因是用户已在频道中。声网建议你通过 onConnectionStateChanged 回调判断用户是否在频道中。只有在收到 CONNECTION_STATE_DISCONNECTED（1）状态时才调用此方法加入频道。
  • -102：频道名无效。你需要在 channelId 中传入有效的频道名以重新加入频道。
  • -121：用户 ID 无效。你需要在 uid 中传入有效的用户 ID 以重新加入频道。

所属接口类

• RtcEngineEx

joinChannelWithUserAccount [1/2]

使用用户 User Account 和 Token 加入频道。

Java

public abstract int joinChannelWithUserAccount(String token, String channelName, String userAccount);

调用 registerLocalUserAccount 注册用户 User Account 后再调用此方法加入频道，可以缩短进入频道所需的时间。如果你尚未调用 registerLocalUserAccount 注册用户 User Account，当你调用此方法加入频道时，SDK 会自动为你创建一个用户 User Account。 一旦用户加入频道，默认会订阅频道中所有其他用户的音视频流，从而产生用量和计费。如需停止订阅指定流或所有远端流，请调用管理发布与订阅的相关方法。

信息

• 该方法仅支持用户同时加入一个频道。
• 不同 App ID 的用户无法互通。
• 加入频道前，请确保用于生成 Token 的 App ID 与调用 create [2/2] 方法时传入的 App ID 相同，否则可能会导致使用该 Token 加入频道失败。
• 为确保通信顺畅，请使用相同的参数类型标识用户。例如，如果某用户使用 uid 加入频道，则其他用户也应使用 uid；如果使用用户 User Account 加入频道，则其他用户也应使用用户 User Account。如果用户使用声网 Web SDK 加入频道，请确保用户 ID 设置为相同的参数类型。

调用时机

请在调用 create [2/2] 方法后调用此方法。

相关回调

本地客户端：onLocalUserRegistered、onJoinChannelSuccess 和 onConnectionStateChanged 回调。 远端客户端：如果用户在 COMMUNICATION 频道场景中加入频道，或主播在 LIVE_BROADCASTING 频道场景中加入频道，则会触发 onUserJoined 和 onUserInfoUpdated 回调。

参数

token

在你的服务器上生成的用于鉴权的 Token。

信息

• （推荐）如果你的项目启用了安全模式（使用 App ID 和 Token 进行鉴权），该参数为必填。
• 如果你只启用了测试模式（使用 App ID 进行鉴权），该参数为可选。成功加入频道后，你将在 24 小时后自动退出频道。
• 如果你需要同时加入不同频道或在频道间切换，声网建议使用通配符 Token，这样你每次加入频道时无需重新申请 Token。

channelName

频道名。在相同 App ID 的前提下，填写相同频道名的用户会进入同一个频道进行音视频互动。字符串长度必须小于 64 字节。支持的字符（共 89 个）：

• 所有小写英文字母：a 到 z。
• 所有大写英文字母：A 到 Z。
• 所有数字字符：0 到 9。
• "!", "#", "$", "%", "&", "(", ")", "+", "-", ":", ";", "<", "=", ".", ">", "?", "@", "[", "]", "^", "_", "{", "}", "|", "~", ","

userAccount

用户 User Account。用于标识频道中的用户以进行实时音视频互动。你需要自行设置和管理用户 User Account，并确保同一频道中的每个用户 User Account 唯一。该参数的最大长度为 255 字节，不能为空。支持的字符如下（共 89 个）：

• 26 个小写英文字母：a 到 z。
• 26 个大写英文字母：A 到 Z。
• 所有数字字符：0 到 9。
• 空格
• "!", "#", "$", "%", "&", "(", ")", "+", "-", ":", ";", "<", "=", ".", ">", "?", "@", "[", "]", "^", "_", "{", "}", "|", "~", ","

返回值

• 0：方法调用成功。
• < 0：方法调用失败。详见错误码了解详情和解决建议。
  • -2：参数无效。例如，Token 无效，uid 参数未设置为整数，或 ChannelMediaOptions 中某成员的值无效。你需要传入有效参数并重新加入频道。
  • -3：RtcEngine 对象初始化失败。你需要重新初始化 RtcEngine 对象。
  • -7：RtcEngine 对象尚未初始化。你需要先初始化 RtcEngine 对象再调用此方法。
  • -8：RtcEngine 对象内部状态错误。典型原因是调用 startEchoTest 开始通话回路测试后，未调用 stopEchoTest 停止测试就调用此方法加入频道。你需要先调用 stopEchoTest 再调用此方法。
  • -17：加入频道请求被拒绝。典型原因是用户已在频道中。声网建议你使用 onConnectionStateChanged 回调判断用户是否在频道中。只有在收到 CONNECTION_STATE_DISCONNECTED（1）状态时才调用此方法加入频道。
  • -102：频道名无效。你需要在 channelId 中传入有效的频道名重新加入频道。
  • -121：用户 ID 无效。你需要在 uid 中传入有效的用户 ID 重新加入频道。

所属接口类

• RtcEngine

joinChannelWithUserAccount [2/2]

使用用户 User Account 和 Token 加入频道，并设置媒体选项。

Java

public abstract int joinChannelWithUserAccount(String token, String channelName, String userAccount, ChannelMediaOptions options);

自从

自 v3.3.0 版本新增。

该方法新增了 options 参数，用于设置媒体选项，例如是否在频道内发布音视频流。默认情况下，用户会订阅频道内所有其他用户的音视频流，从而产生使用量和计费。如需停止订阅其他流，请设置 options 参数或调用管理发布与订阅的相关方法。

信息

• 此方法仅支持用户同时加入一个频道。
• 不同 App ID 的用户无法互通。
• 加入频道前，请确保用于生成 Token 的 App ID 与调用 create [2/2] 方法时传入的 App ID 相同，否则可能会因 Token 不匹配而加入频道失败。
• 为确保通信顺畅，请使用相同的参数类型标识用户。例如，如果某用户使用用户 ID 加入频道，则其他用户也应使用用户 ID；用户 User Account 亦同理。如果用户使用声网 Web SDK 加入频道，请确保用户 ID 的类型一致。

调用时机

在调用 create [2/2] 方法之后调用此方法。

相关回调

本地客户端：onLocalUserRegistered、onJoinChannelSuccess 和 onConnectionStateChanged 回调。 远端客户端：如果用户在 COMMUNICATION 频道场景中加入频道，或主播在 LIVE_BROADCASTING 频道场景中加入频道，则触发 onUserJoined 和 onUserInfoUpdated 回调。

参数

token

在你的服务器上生成的用于鉴权的 Token。

信息

• （推荐）如果你的项目启用了安全模式（使用 App ID 和 Token 进行鉴权），此参数为必填。
• 如果你仅启用了测试模式（使用 App ID 进行鉴权），此参数为可选。成功加入频道后，24 小时后会自动退出频道。
• 如果你需要同时加入多个频道或在频道间切换，声网建议使用通配符 Token，这样你每次加入频道时无需重新申请 Token。

channelName

频道名。在相同 App ID 前提下，填写相同频道名的用户会进入同一个频道进行音视频互动。字符串长度必须小于 64 字节。支持的字符（共 89 个）：

• 所有小写英文字母：a 到 z。
• 所有大写英文字母：A 到 Z。
• 所有数字字符：0 到 9。
• "!", "#", "$", "%", "&", "(", ")", "+", "-", ":", ";", "<", "=", ".", ">", "?", "@", "[", "]", "^", "_", "{", "}", "|", "~", ","

userAccount

用户 User Account。你需要自行设置和管理用户 User Account，并确保同一频道内的每个用户 User Account 唯一。该参数最大长度为 255 字节，不能为空。支持的字符如下（共 89 个）：

• 26 个小写英文字母：a 到 z。
• 26 个大写英文字母：A 到 Z。
• 所有数字字符：0 到 9。
• 空格
• "!", "#", "$", "%", "&", "(", ")", "+", "-", ":", ";", "<", "=", ".", ">", "?", "@", "[", "]", "^", "_", "{", "}", "|", "~", ","

options

频道媒体选项，详见 ChannelMediaOptions。

返回值

• 0：方法调用成功。
• < 0：方法调用失败。详见错误码了解详情和解决建议。
  • -2：参数无效。例如，Token 无效，uid 参数未设置为整数，或 ChannelMediaOptions 中某成员的值无效。请传入有效参数并重新加入频道。
  • -3：初始化 RtcEngine 对象失败。请重新初始化 RtcEngine 对象。
  • -7：RtcEngine 对象尚未初始化。请先初始化 RtcEngine 对象再调用此方法。
  • -8：RtcEngine 对象内部状态错误。典型原因是调用 startEchoTest 开始通话回声测试后，未调用 stopEchoTest 停止测试就调用此方法加入频道。请先调用 stopEchoTest 再调用此方法。
  • -17：加入频道请求被拒绝。典型原因是用户已在频道中。声网建议使用 onConnectionStateChanged 回调判断用户是否在频道中。仅当收到 CONNECTION_STATE_DISCONNECTED（1）状态时再调用此方法加入频道。
  • -102：频道名无效。请在 channelId 中传入有效的频道名重新加入频道。
  • -121：用户 ID 无效。请在 uid 中传入有效的用户 ID 重新加入频道。

所属接口类

• RtcEngine

joinChannelWithUserAccountEx

使用用户 User Account 和 Token 加入频道，并设置媒体选项。

Java

public abstract int joinChannelWithUserAccountEx(String token, String channelId, String userAccount, ChannelMediaOptions options, IRtcEngineEventHandler eventHandler);

在调用此方法之前，如果你尚未调用 registerLocalUserAccount 注册用户 User Account，SDK 会在你调用此方法加入频道时自动创建用户 User Account。提前调用 registerLocalUserAccount 可以缩短加入频道所需的时间。 一旦用户加入频道，默认会订阅频道中所有其他用户的音视频流，从而产生使用量和计费。如果你希望停止订阅其他用户的媒体流，可以设置 options 参数或调用管理发布与订阅的相关方法。

信息

• 该方法仅支持用户同时加入一个频道。
• 不同 App ID 的用户无法互通。
• 加入频道前，请确保用于生成 Token 的 App ID 与调用 create [2/2] 方法时传入的 App ID 相同，否则可能导致加入频道失败。
• 为确保通信顺畅，请使用相同的参数类型标识用户。例如，如果某用户使用 uid 加入频道，则其他用户也应使用 uid；如果使用用户 User Account 加入频道，则其他用户也应使用用户 User Account。若使用声网 Web SDK 加入频道，请确保用户 ID 的参数类型一致。

适用场景

该方法适用于多频道场景。

调用时机

在调用 create [2/2] 之后调用此方法。

相关回调

本地客户端：onLocalUserRegistered、onJoinChannelSuccess 和 onConnectionStateChanged 回调。 远端客户端：如果用户在 COMMUNICATION 频道场景中加入频道，或主播在 LIVE_BROADCASTING 频道场景中加入频道，则触发 onUserJoined 和 onUserInfoUpdated 回调。

参数

token

在你的服务器上生成的用于鉴权的 Token。

信息

• （推荐）如果你的项目启用了安全模式（使用 App ID 和 Token 进行鉴权），该参数为必填。
• 如果你只启用了测试模式（使用 App ID 进行鉴权），该参数为可选。成功加入频道后，你将在 24 小时后自动退出频道。
• 如果你需要同时加入多个频道或在频道间切换，声网建议使用通配符 Token，这样你无需每次加入频道时都申请新的 Token。

channelId

频道名。在相同 App ID 的前提下，填写相同频道名的用户会进入同一个频道进行音视频互动。字符串长度必须小于 64 字节。支持的字符（共 89 个）：

• 所有小写英文字母：a 到 z。
• 所有大写英文字母：A 到 Z。
• 所有数字字符：0 到 9。
• "!", "#", "$", "%", "&", "(", ")", "+", "-", ":", ";", "<", "=", ".", ">", "?", "@", "[", "]", "^", "_", "{", "}", "|", "~", ","

userAccount

用户 User Account。你需要自行设置和管理用户 User Account，并确保同一频道中的每个用户 User Account 唯一。该参数的最大长度为 255 字节，不能为空。支持的字符如下（共 89 个）：

• 26 个小写英文字母：a 到 z。
• 26 个大写英文字母：A 到 Z。
• 所有数字字符：0 到 9。
• 空格
• "!", "#", "$", "%", "&", "(", ")", "+", "-", ":", ";", "<", "=", ".", ">", "?", "@", "[", "]", "^", "_", "{", "}", "|", "~", ","

options

频道媒体选项。详见 ChannelMediaOptions。

eventHandler

RtcEngineEx 的回调类。详见 IRtcEngineEventHandler。你可以通过该参数传入的 eventHandler 对象获取多个频道的回调事件。

返回值

• 0：方法调用成功。
• < 0：方法调用失败。详见错误码了解详情和解决建议。
  • -2：参数无效。例如 Token 无效，uid 参数未设置为整数，或 ChannelMediaOptions 中某成员的值无效。请传入有效参数后重新加入频道。
  • -3：RtcEngine 对象初始化失败。请重新初始化 RtcEngine 对象。
  • -7：RtcEngine 对象尚未初始化。请先初始化后再调用此方法。
  • -8：RtcEngine 对象内部状态错误。典型原因是在调用 startEchoTest 开始通话回路测试后，未调用 stopEchoTest 停止测试就调用此方法。请先调用 stopEchoTest 再调用此方法。
  • -17：加入频道请求被拒绝。典型原因是用户已在频道中。建议通过 onConnectionStateChanged 回调确认用户是否已在频道中，除非收到 CONNECTION_STATE_DISCONNECTED（1）状态，否则不要调用此方法。
  • -102：频道名无效。请在 channelId 中传入有效的频道名后重新加入频道。
  • -121：用户 ID 无效。请在 uid 中传入有效的用户 ID 后重新加入频道。

所属接口类

• RtcEngineEx

leaveChannel [1/2]

离开频道。

Java

public abstract int leaveChannel();

调用该方法后，SDK 会终止音视频互动，释放与会话相关的所有资源。加入频道后，必须调用该方法结束通话，否则无法开始下一次通话。

信息

• 如果在调用该方法后立即调用 destroy [2/2]，SDK 不会触发 onLeaveChannel 回调。
• 此方法为异步调用。当该方法返回时，并不代表用户已完全离开频道。
• 如果你调用了 joinChannelEx 加入了多个频道，调用该方法会离开你加入的所有频道。

调用时机

在加入频道后调用该方法。

相关回调

调用该方法成功后会触发以下回调：

• 本地客户端实例：会触发 onLeaveChannel 回调。
• 远端客户端实例：远端主播离开频道后会触发 onUserOffline 回调。

返回值

• 0：方法调用成功。
• < 0：方法调用失败。详见错误码了解详情和解决建议。
  • -1：发生通用错误（无明确原因）。
  • -2：参数无效。
  • -7：SDK 未初始化。

所属接口类

• RtcEngine

leaveChannel [2/2]

设置频道选项并离开频道。

Java

public abstract int leaveChannel(LeaveChannelOptions options);

调用该方法后，SDK 会终止音视频互动，离开当前频道，并释放与会话相关的所有资源。如果你调用了 joinChannelEx 加入了多个频道，调用该方法会离开你加入的所有频道。

信息

如果在调用该方法后立即调用 destroy [2/2]，SDK 不会触发 onLeaveChannel 回调。该方法为异步调用。当该方法返回时，并不一定表示用户已离开频道。

调用时机

在加入频道后调用该方法。

相关回调

调用该方法成功后会触发以下回调：

• 本地客户端实例：触发 onLeaveChannel 回调。
• 远端客户端实例：远端主播离开频道后触发 onUserOffline 回调。

参数

options

离开频道的选项，详见 LeaveChannelOptions。

返回值

• 0：方法调用成功。
• < 0：方法调用失败。详见错误码了解详情和解决建议。

所属接口类

• RtcEngine

leaveChannelEx [1/2]

离开频道。

Java

public abstract int leaveChannelEx(RtcConnection connection);

调用该方法后，SDK 会终止音视频互动，离开当前频道，并释放与会话相关的所有资源。调用 joinChannelEx 加入频道后，必须调用此方法或 leaveChannelEx 结束通话，否则无法开始下一次通话。

信息

• 如果在调用该方法后立即调用 destroy [2/2]，SDK 不会触发 onLeaveChannel 回调。
• 该方法为异步调用，方法返回时并不代表用户已离开频道。
• 如果调用 leaveChannel [1/2] 或 leaveChannel [2/2]，你将离开通过 joinChannel [1/2]、joinChannel [2/2] 或 joinChannelEx 加入的所有频道。

适用场景

该方法适用于多频道场景。

调用时机

在调用 joinChannelEx 之后调用该方法。

相关回调

调用成功后会触发以下回调：

• 本地客户端实例：触发 onLeaveChannel 回调。
• 远端客户端实例：远端主播离开频道后触发 onUserOffline 回调。

参数

connection

连接信息，详见 RtcConnection。

返回值

• 0：方法调用成功。
• < 0：方法调用失败。详见错误码了解详情和解决建议。

所属接口类

• RtcEngineEx

leaveChannelEx [2/2]

设置频道参数并离开频道。

Java

public abstract int leaveChannelEx(RtcConnection connection, LeaveChannelOptions options);

自从

自 v4.1.0 版本新增。

调用该方法后，SDK 会终止音视频互动，并释放与会话相关的所有资源。调用 joinChannelEx 加入频道后，必须调用此方法或 leaveChannelEx(RtcConnection connection) 结束通话，否则无法开始下一次通话。

信息

• 如果在调用该方法后立即调用 destroy()，SDK 不会触发 onLeaveChannel 回调。
• 此方法为异步调用。当该方法返回时，并不代表你已离开频道。
• 如果调用 leaveChannel() 或 leaveChannel(LeaveChannelOptions options)，将会离开通过 joinChannel [1/2]、joinChannel [2/2] 或 joinChannelEx 加入的所有频道。

适用场景

该方法适用于多频道场景。

调用时机

在调用 joinChannelEx 之后调用该方法。

相关回调

调用该方法成功后会触发以下回调：

• 本地客户端实例：会触发 onLeaveChannel 回调。
• 远端客户端实例：远端主播离开频道后会触发 onUserOffline 回调。

参数

connection

连接信息，详见 RtcConnection。

options

离开频道的选项。

信息

该参数仅支持 LeaveChannelOptions 中的 stopMicrophoneRecording 成员，设置其他成员无效。

返回值

• 0：方法调用成功。
• < 0：方法调用失败。详见错误码了解详情和解决建议。

所属接口类

• RtcEngineEx

preloadChannel

预加载指定频道以缩短观众加入频道的时间。

Java

public abstract int preloadChannel(String token, String channelName, int optionalUid);

当观众需要频繁切换不同频道时，调用该方法可以缩短加入频道的时间，从而减少观众听到和看到主播的延迟时间。如果你加入了一个已预加载的频道，离开后想重新加入该频道，除非用于预加载频道的 Token 过期，否则无需再次调用该方法。

信息

• 调用该方法时，请确保将用户角色设置为观众，且未将音频场景设置为 AUDIO_SCENARIO_CHORUS，否则该方法不生效。
• 你还需要确保用于预加载的频道名、用户 ID 和 Token 与加入频道时传入的值一致，否则该方法不生效。
• 一个 RtcEngine 实例最多支持预加载 20 个频道，超出限制时，仅最近的 20 个预加载频道生效。
• 预加载频道失败并不意味着无法加入频道，也不会增加加入频道所需的时间。

参数

token

在你的服务器上生成的用于鉴权的 Token。当用于预加载频道的 Token 过期时，你可以根据预加载的频道数量更新 Token：

• 预加载一个频道时，调用该方法传入新的 Token。
• 预加载多个频道时：
  • 如果你为所有预加载频道使用通配符 Token，调用 updatePreloadChannelToken 更新 Token。注意：生成通配符 Token 时，确保用户 ID 不为 0。
  • 如果你为不同频道使用不同的 Token，调用该方法传入你的用户 ID、频道名和新的 Token。

channelName

你想要预加载的频道名。该参数表示用户进行实时音视频互动的频道。在相同 App ID 的前提下，填写相同频道名的用户会进入同一个频道进行音视频互动。字符串长度必须小于 64 字节。支持的字符（共 89 个）：

• 所有小写英文字母：a 到 z。
• 所有大写英文字母：A 到 Z。
• 所有数字字符：0 到 9。
• "!", "#", "$", "%", "&", "(", ")", "+", "-", ":", ";", "<", "=", ".", ">", "?", "@", "[", "]", "^", "_", "{", "}", "|", "~", ","。

optionalUid

用户 ID。用于标识频道中的用户以进行实时音视频互动。你需要自行设置和管理用户 ID，并确保同一频道中的每个用户 ID 唯一。该参数为 32 位有符号整数，取值范围为 -2^31 到 2^31-1。如果未指定用户 ID（或设置为 0），SDK 会分配一个随机用户 ID，并在 onJoinChannelSuccess 回调中返回。你的应用必须记录并维护返回的用户 ID，SDK 不会保存。

返回值

• 0：方法调用成功。
• < 0：方法调用失败。详见错误码了解详情和解决建议。
  • -7：RtcEngine 对象尚未初始化。请先初始化 RtcEngine 对象再调用该方法。
  • -102：频道名无效。请传入有效的频道名并重新加入频道。

所属接口类

• RtcEngine

preloadChannelWithUserAccount

预加载指定频道，缩短观众加入频道的时间。

Java

public abstract int preloadChannelWithUserAccount(String token, String channelName, String userAccount);

当观众需要频繁切换不同频道时，调用该方法可以缩短加入频道的时间，从而减少观众听到和看到主播的延迟。如果你加入了一个已预加载的频道，离开后想重新加入同一个频道，除非用于预加载频道的 Token 过期，否则无需再次调用该方法。

信息

• 调用该方法时，请确保将用户角色设置为观众，且未将音频场景设置为 AUDIO_SCENARIO_CHORUS，否则该方法不生效。
• 你需要确保用于预加载的用户 User Account、频道名和 Token 与加入频道时传入的值一致，否则该方法不生效。
• 一个 RtcEngine 实例最多支持预加载 20 个频道。超过该限制时，仅最近的 20 个预加载频道生效。
• 预加载频道失败不会影响加入频道的能力，也不会增加加入频道所需的时间。

调用时机

为提升预加载频道的用户体验，声网建议在确认频道名和用户信息后尽早调用该方法。

参数

token

你在服务器上生成的用于鉴权的 Token。当用于预加载频道的 Token 过期时，你可以根据预加载的频道数量更新 Token：

• 预加载一个频道时，调用该方法传入新的 Token。
• 预加载多个频道时：
  • 如果你为所有预加载频道使用通配符 Token，调用 updatePreloadChannelToken 更新 Token。注意：生成通配符 Token 时，确保用户 ID 不为 0。
  • 如果你为不同频道使用不同的 Token，调用该方法传入用户 User Account、频道名和新的 Token。

channelName

你想要预加载的频道名。字符串长度必须小于 64 字节。支持的字符（共 89 个）：

• 所有小写英文字母：a 到 z。
• 所有大写英文字母：A 到 Z。
• 所有数字字符：0 到 9。
• "!", "#", "$", "%", "&", "(", ")", "+", "-", ":", ";", "<", "=", ".", ">", "?", "@", "[", "]", "^", "_", "{", "}", "|", "~", ","

userAccount

用户 User Account，用于标识频道中的用户。你需要自行设置和管理用户 User Account，并确保同一频道中的每个用户 User Account 唯一。该参数最大长度为 255 字节，不能为空。支持的字符如下（共 89 个）：

• 26 个小写英文字母：a 到 z。
• 26 个大写英文字母：A 到 Z。
• 所有数字字符：0 到 9。
• 空格
• "!", "#", "$", "%", "&", "(", ")", "+", "-", ":", ";", "<", "=", ".", ">", "?", "@", "[", "]", "^", "_", "{", "}", "|", "~", ","

返回值

• 0：方法调用成功。
• < 0：方法调用失败。详见错误码了解详情和解决建议。
  • -2：参数无效，例如用户 User Account 为空。请传入有效参数后重新加入频道。
  • -7：RtcEngine 对象尚未初始化。请先初始化 RtcEngine 对象后再调用该方法。
  • -102：频道名无效。请传入有效的频道名后重新加入频道。

所属接口类

• RtcEngine

registerLocalUserAccount

注册用户 User Account。

Java

public abstract int registerLocalUserAccount(String appId, String userAccount);

该方法用于注册用户 User Account。注册成功后，用户 User Account 可用于在加入频道时标识本地用户身份。该方法为可选项。如果你希望使用用户 User Account 加入频道，可以选择以下任一方式：

• 先调用 registerLocalUserAccount 方法注册用户 User Account，再调用 joinChannelWithUserAccount 方法加入频道，可缩短进入频道所需时间。
• 直接调用 joinChannelWithUserAccount 方法加入频道。

相关回调

成功调用该方法后，SDK 会触发 onLocalUserRegistered 回调，报告本地用户的用户 ID 和用户 User Account。

参数

appId

声网控制台中项目的 App ID。

userAccount

用户 User Account，用于在频道中标识用户身份以实现实时音视频互动。你需要自行设置并管理用户 User Account，并确保同一频道内的每个用户 User Account 唯一。该参数的最大长度为 255 字节，不能为空。支持的字符共 89 个，包括：

• 26 个小写英文字母：a 到 z。
• 26 个大写英文字母：A 到 Z。
• 所有数字字符：0 到 9。
• 空格
• "!"、"#"、"$"、"%"、"&"、"("、")"、"+"、"-"、":"、";"、"<"、"="、"."、">"、"?"、"@"、"["、"]"、"^"、"_"、"{"、"}"、"|"、"~"、","

返回值

• 0：方法调用成功。
• < 0：方法调用失败。详见错误码了解详情和解决建议。

所属接口类

• RtcEngine

renewToken

更新 Token。

Java

public abstract int renewToken(String token);

调用该方法更新 Token。调用成功后，SDK 会触发 onRenewTokenResult 回调。Token 会在一段时间后过期，届时 SDK 将无法与服务器建立连接。声网建议在以下任一情况下，在你的服务器上生成新的 Token，并调用该方法进行更新：

• 收到 onTokenPrivilegeWillExpire 回调，提示 Token 即将过期。
• 收到 onRequestToken 回调，提示 Token 已过期。
• 收到 onConnectionStateChanged 回调，状态为 CONNECTION_CHANGED_TOKEN_EXPIRED（9）。

参数

token

新的 Token。

返回值

• 0：方法调用成功。
• < 0：方法调用失败。详见错误码了解详情和解决建议。
  • -2：参数无效，例如传入的 Token 为空。
  • -7：RtcEngine 对象尚未初始化。请先初始化 RtcEngine 对象再调用该方法。
  • 110：Token 无效。请确保以下事项：
    • 生成 Token 时指定的用户 ID 与加入频道时使用的用户 ID 一致。
    • 生成的 Token 与加入频道时传入的 Token 相同。

所属接口类

• RtcEngine

setChannelProfile

设置频道场景。

Java

public abstract int setChannelProfile(int profile);

SDK 会根据不同的频道场景采用不同的优化策略，例如在极速直播场景中优先保证视频质量。初始化 SDK 后，默认频道场景为极速直播。

信息

为确保实时通信质量，建议频道内所有用户使用相同的频道场景。不同频道场景下，SDK 的默认音频路由也不同，详见 setDefaultAudioRouteToSpeakerphone。

调用时机

在加入频道前调用此方法。

参数

profile

频道场景：

• CHANNEL_PROFILE_COMMUNICATION（0）：通信场景。建议使用 CHANNEL_PROFILE_LIVE_BROADCASTING 以获得更好的音视频体验。
• CHANNEL_PROFILE_LIVE_BROADCASTING（1）：（默认）极速直播场景。
• CHANNEL_PROFILE_GAME（2）：游戏场景。已废弃，请使用 CHANNEL_PROFILE_LIVE_BROADCASTING。
• CHANNEL_PROFILE_CLOUD_GAMING（3）：互动场景。该场景对延迟进行了优化，适用于用户之间需要频繁互动的场景。已废弃，请使用 CHANNEL_PROFILE_LIVE_BROADCASTING。

返回值

• 0：方法调用成功。
• < 0：方法调用失败。详见错误码了解详情和解决建议。
  • -2：参数无效。
  • -7：SDK 未初始化。

所属接口类

• RtcEngine

setClientRole [1/2]

设置客户端实例的用户角色。

Java

public abstract int setClientRole(int role);

你可以调用该方法将用户角色设置为主播或观众。用户角色决定了用户在 SDK 层的权限，包括是否可以在频道中发布音视频流。 你可以在加入频道前或加入频道后调用该方法：

• 如果你在加入频道前调用该方法将用户角色设置为主播，并通过 setupLocalVideo 设置本地视频属性，则用户加入频道时会自动开启本地视频预览。
• 如果你在加入频道后调用该方法设置用户角色，SDK 会自动调用 muteLocalAudioStream 和 muteLocalVideoStream 更改音视频流的发布状态。

信息

在加入频道前调用该方法并将用户角色设置为 CLIENT_ROLE_BROADCASTER 时，本地客户端不会触发 onClientRoleChanged 回调。加入频道前调用该方法并将 role 设置为 CLIENT_ROLE_AUDIENCE 时也会触发该回调。

调用时机

你可以在加入频道前或加入频道后调用此方法。

相关回调

如果你在加入频道后调用此方法切换用户角色，SDK 会触发以下回调：

• 本地客户端触发 onClientRoleChanged 回调。
• 远端客户端触发 onUserJoined 或 onUserOffline 回调。

如果你在加入频道后调用此方法设置用户角色但失败，SDK 会触发 onClientRoleChangeFailed 回调，报告失败原因和当前用户角色。

参数

role

信息

如果你将用户角色设置为观众，则无法在频道中发布音视频流。

用户角色：

• CLIENT_ROLE_BROADCASTER (1)：主播。
• CLIENT_ROLE_AUDIENCE (2)：观众。

返回值

• 0：方法调用成功。
• < 0：方法调用失败。详见错误码了解详情和解决建议。
  • -1：发生通用错误（无具体原因）。
  • -2：参数无效。
  • -7：SDK 未初始化。

所属接口类

• RtcEngine

setClientRole [2/2]

设置直播场景下的用户角色和观众延迟等级。

Java

public abstract int setClientRole(int role, ClientRoleOptions options);

默认情况下，SDK 会将用户角色设置为观众。你可以调用此方法将用户角色设置为主播。用户角色 (role) 决定了用户在 SDK 层级的权限，包括是否可以在频道中发布音视频流。 该方法与 setClientRole(int role) 的区别在于，它支持设置 audienceLatencyLevel。audienceLatencyLevel 需要与 role 搭配使用，以确定用户在其权限范围内可享受的服务等级。例如，观众可以选择接收低延迟或超低延迟的远端流。 如果你在加入频道前调用此方法并通过 setupLocalVideo 设置本地视频属性，则用户加入频道时会自动开启本地视频预览。 如果你在加入频道后调用此方法设置用户角色，SDK 会自动调用 muteLocalAudioStream 和 muteLocalVideoStream 方法来改变音视频流的发布状态。

信息

当用户角色设置为主播时，观众延迟等级只能设置为 AUDIENCE_LATENCY_LEVEL_ULTRA_LOW_LATENCY。 在加入频道前调用此方法并将 role 设置为 BROADCASTER 时，本地客户端不会触发 onClientRoleChanged 回调。 在加入频道前调用此方法并将 role 设置为 AUDIENCE 时，也会触发该回调。

调用时机

你可以在加入频道前或加入频道后调用此方法。

相关回调

如果你在加入频道后调用此方法切换用户角色，SDK 会触发以下回调：

• 本地客户端触发 onClientRoleChanged 回调。注意：在加入频道前调用此方法并将 role 设置为 AUDIENCE 也会触发该回调。
• 远端客户端触发 onUserJoined 或 onUserOffline 回调。

如果你在加入频道后调用此方法设置用户角色但失败，SDK 会触发 onClientRoleChangeFailed 回调，报告失败原因和当前用户角色。

参数

role

信息

如果你将用户角色设置为观众，则无法在频道中发布音视频流。如果你希望在直播过程中发布媒体流，请确保将用户角色设置为主播。

用户角色。

• CLIENT_ROLE_BROADCASTER (1)：主播。
• CLIENT_ROLE_AUDIENCE (2)：观众（默认）。

options

用户的详细选项，详见 ClientRoleOptions。

返回值

• 0：方法调用成功。
• < 0：方法调用失败。详见错误码了解详情和解决建议。
  • -1：发生通用错误（无明确原因）。
  • -2：参数无效。
  • -5：请求被拒绝。
  • -7：SDK 未初始化。

所属接口类

• RtcEngine

updateChannelMediaOptions

在加入频道后更新频道媒体选项。

Java

public abstract int updateChannelMediaOptions(ChannelMediaOptions options);

参数

options

频道媒体选项。详见 ChannelMediaOptions。

返回值

• 0：方法调用成功。
• < 0：方法调用失败。详见错误码了解详情和解决建议。
  • -2：ChannelMediaOptions 中某个成员的值无效，例如 Token 或用户 ID 无效。你需要填写有效的参数。
  • -7：RtcEngine 对象尚未初始化。你需要先初始化 RtcEngine 对象再调用该方法。
  • -8：RtcEngine 对象的内部状态错误。可能的原因是用户不在频道中。声网建议你使用 onConnectionStateChanged 回调判断用户是否在频道中。如果你收到 CONNECTION_STATE_DISCONNECTED（1）或 CONNECTION_STATE_FAILED（5）状态，说明用户不在频道中。你需要先调用 joinChannel 加入频道，再调用该方法。

所属接口类

• RtcEngine

updateChannelMediaOptionsEx

加入频道后更新频道媒体选项。

Java

public abstract int updateChannelMediaOptionsEx(ChannelMediaOptions options, RtcConnection connection);

适用场景

该方法适用于多频道场景。

参数

options

频道媒体选项。详见 ChannelMediaOptions。

connection

连接信息。详见 RtcConnection。

返回值

• 0：方法调用成功。
• < 0：方法调用失败。详见错误码了解详情和解决建议。
  • -2：ChannelMediaOptions 中的成员值无效，例如 token 或用户 ID 无效。你需要填写有效的参数。
  • -7：RtcEngine 对象尚未初始化。你需要先初始化 RtcEngine 对象再调用该方法。
  • -8：RtcEngine 对象的内部状态错误，可能的原因是用户不在频道中。声网建议你使用 onConnectionStateChanged 回调判断用户是否在频道中。如果你收到 CONNECTION_STATE_DISCONNECTED（1）或 CONNECTION_STATE_FAILED（5）状态，说明用户不在频道中。你需要先调用 joinChannel 加入频道，再调用该方法。

所属接口类

• RtcEngineEx

updatePreloadChannelToken

更新用于预加载频道的通配 Token。

Java

public abstract int updatePreloadChannelToken(String token);

你需要自行维护通配 Token 的生命周期。当该 Token 过期时，需要生成新的通配 Token，并调用该方法传入新的 Token。

适用场景

适用于涉及多个频道的场景，例如在不同频道之间切换时，使用通配 Token 可以避免用户每次加入新频道时都申请新的 Token，从而节省切换频道的时间，并减轻你的 Token 服务器的压力。

参数

token

新的 Token。

返回值

• 0：方法调用成功。
• < 0：方法调用失败。详见错误码了解详情和解决建议。
  • -2：参数无效，例如 Token 无效。你需要传入有效参数并重新加入频道。
  • -7：RtcEngine 对象尚未初始化。你需要先初始化 RtcEngine 对象再调用此方法。

所属接口类

• RtcEngine

onClientRoleChanged

用户角色或观众延迟级别发生变化回调。

Java

public void onClientRoleChanged(int oldRole, int newRole, ClientRoleOptions newRoleOptions)

信息

当你在加入频道前调用 setClientRole [1/2] 或 setClientRole [2/2] 并将用户角色设置为主播时，该回调不会被触发。

触发时机

该回调在以下任一情况下被触发：

• 加入频道后调用 setClientRole [1/2] 或 setClientRole [2/2] 设置用户角色或观众延迟级别；
• 加入频道前调用 setClientRole [1/2] 或 setClientRole [2/2] 并将用户角色设置为观众。

参数

oldRole

用户切换前的角色：

• CLIENT_ROLE_BROADCASTER (1)：主播。
• CLIENT_ROLE_AUDIENCE (2)：观众。

newRole

用户切换后的角色：

• CLIENT_ROLE_BROADCASTER (1)：主播。
• CLIENT_ROLE_AUDIENCE (2)：观众。

newRoleOptions

用户切换后的角色属性，详见 ClientRoleOptions。

所属接口类

• IRtcEngineEventHandler

onClientRoleChangeFailed

切换用户角色失败时的回调。

Java

public void onClientRoleChangeFailed(int reason, int currentRole)

该回调用于通知切换用户角色失败的原因以及当前的用户角色。

触发时机

该回调在本地用户加入频道后调用 setClientRole [1/2] 或 setClientRole [2/2]（带 ClientRoleOptions 参数）切换用户角色失败时被触发。

参数

reason

信息

仅在启用 128 人功能时会返回该枚举值。主播数量上限取决于启用 128 人功能时配置的实际主播数量。

用户角色切换失败的原因。

• CLIENT_ROLE_CHANGE_FAILED_TOO_MANY_BROADCASTERS (1)：频道中的主播数量已达上限。仅在启用 128 人功能时会返回该枚举值。
• CLIENT_ROLE_CHANGE_FAILED_NOT_AUTHORIZED (2)：请求被声网服务器拒绝。建议提示用户重试切换用户角色。
• CLIENT_ROLE_CHANGE_FAILED_REQUEST_TIME_OUT (3)：请求超时。建议提示用户检查网络连接并重试切换用户角色。自 v4.4.0 版本废弃，不建议使用。
• CLIENT_ROLE_CHANGE_FAILED_CONNECTION_FAILED (4)：SDK 连接失败。你可以通过 onConnectionStateChanged 回调中报告的 reason 进行排查。自 v4.4.0 版本废弃，不建议使用。

currentRole

当前的用户角色。

• CLIENT_ROLE_BROADCASTER (1)：主播，可以发送和接收音视频流。
• CLIENT_ROLE_AUDIENCE (2)：观众，只能接收音视频流。

所属接口类

• IRtcEngineEventHandler

onError

SDK 运行期间发生错误时触发的回调。

Java

public void onError(int err)

该回调表示 SDK 运行期间发生了网络或媒体相关的错误。在大多数情况下，SDK 无法自动修复该问题并继续运行，需要你在应用层进行处理或通知用户。

触发时机

该回调在 SDK 运行期间发生错误时被触发。

参数

err

错误码。详见错误码文档。

所属接口类

• IRtcEngineEventHandler

onJoinChannelSuccess

远端用户成功加入频道回调。

Java

public void onJoinChannelSuccess(String channel, int uid, int elapsed)

触发时机

该回调在你调用 joinChannel、joinChannelWithUserAccount、joinChannelEx 或 joinChannelWithUserAccountEx 加入频道时被触发。

参数

channel

频道名。

uid

加入频道的用户 ID。

elapsed

从本地用户调用 joinChannel 加入频道到 SDK 触发该回调的时间间隔，单位为毫秒。

所属接口类

• IRtcEngineEventHandler

onLeaveChannel

用户离开频道回调。

Java

public void onLeaveChannel(RtcStats stats) {}

触发时机

该回调在你调用 leaveChannel [1/2]、leaveChannel [2/2]、leaveChannelEx [1/2] 或 leaveChannelEx [2/2] 离开频道后被触发。

参数

stats

通话统计信息。详见 RtcStats。

所属接口类

• IRtcEngineEventHandler

onLocalUserRegistered

本地用户注册用户 User Account 回调。

Java

public void onLocalUserRegistered(int uid, String userAccount)

自从

自 v2.8.0 版本新增。

当本地用户成功调用 registerLocalUserAccount 方法注册用户 User Account，或调用 joinChannelWithUserAccount 方法加入频道后，SDK 会触发该回调，并返回本地用户的用户 ID 和用户 User Account。

触发时机

该回调在本地用户成功注册用户 User Account 或加入频道后被触发。

参数

uid

本地用户的用户 ID。

userAccount

本地用户的用户 User Account。

所属接口类

• IRtcEngineEventHandler

onRejoinChannelSuccess

用户重新加入频道回调。

Java

public void onRejoinChannelSuccess(String channel, int uid, int elapsed)

该回调在用户因网络问题与服务器断开连接后，SDK 自动尝试重连并成功重连时触发。

触发时机

该回调在用户因网络问题与服务器断开连接后，SDK 自动尝试重连并成功重连时被触发。

参数

channel

频道名。

uid

重新加入频道的用户 ID。

elapsed

从本地用户调用 joinChannel 到 SDK 触发该回调的时间间隔，单位为毫秒。

所属接口类

• IRtcEngineEventHandler

onRenewTokenResult

renewToken 调用结果回调。

Java

public void onRenewTokenResult(String token, Constants.RenewTokenErrorCode code)

自从

自 v4.6.0 版本新增。

该回调在调用 renewToken 方法后触发，用于通知更新结果。

触发时机

该回调在你调用 renewToken 方法后被触发。

参数

token

用于鉴权的 Token。

code

错误码。详见 RenewTokenErrorCode。

所属接口类

• IRtcEngineEventHandler

onRequestToken

Token 过期回调。

Java

public void onRequestToken() {}

该回调在 Token 过期时被触发。收到该回调后，你需要在 Token 服务器上生成新的 Token，并通过以下方式之一更新 Token：

• 单频道场景：
  • 调用 renewToken 更新 Token。
  • 调用 leaveChannel 离开当前频道，然后在调用 joinChannel 加入频道时传入新的 Token。
• 多频道场景：调用 updateChannelMediaOptionsEx 传入新的 Token。

触发时机

该回调在 Token 过期时被触发。

所属接口类

• IRtcEngineEventHandler

onRtcStats

报告当前通话统计信息的回调。

Java

public void onRtcStats(RtcStats stats) {}

触发时机

该回调在用户加入频道后每两秒触发一次。

参数

stats

RTC 引擎的统计信息，详见 RtcStats。

所属接口类

• IRtcEngineEventHandler

onTokenPrivilegeWillExpire

Token 即将在 30 秒后过期时触发的回调。

Java

public void onTokenPrivilegeWillExpire(String token)

收到该回调时，你需要在 Token 服务器上生成一个新的 Token，并通过以下方式之一更新 Token：

• 单频道场景：
  • 调用 renewToken 传入新的 Token。
  • 调用 leaveChannel 离开当前频道，然后在调用 joinChannel 加入频道时传入新的 Token。
• 多频道场景：调用 updateChannelMediaOptionsEx 传入新的 Token。

触发时机

该回调在 Token 过期前 30 秒被触发。

参数

token

即将过期的 Token。

所属接口类

• IRtcEngineEventHandler

onUserInfoUpdated

远端用户的用户 ID 和用户 User Account 信息更新回调。

Java

public void onUserInfoUpdated(int uid, UserInfo userInfo) {}

自从

自 v2.8.0 版本新增。

当远端用户加入频道后，SDK 会获取该用户的用户 ID 和用户 User Account，并将其缓存在映射表中，然后在本地客户端触发该回调。

触发时机

该回调在远端用户加入频道后，SDK 获取到其用户 ID 和用户 User Account 时被触发。

参数

uid

远端用户的用户 ID。

userInfo

包含远端用户的用户 ID 和用户 User Account 信息。详见 UserInfo。

所属接口类

• IRtcEngineEventHandler

onUserJoined

远端用户或主播加入频道回调。

Java

public void onUserJoined(int uid, int elapsed)

在通信频道中，该回调表示有远端用户加入频道。当本地用户加入频道时，SDK 也会触发该回调报告频道中已有的用户。在极速直播频道中，该回调表示有主播加入频道。声网建议将连麦主播数量限制为 32 人，最多支持 17 路视频主播。

触发时机

该回调在以下任一情况下被触发：

• 远端用户或主播加入频道。
• 远端用户加入频道后将用户角色切换为主播。
• 远端用户或主播在网络中断后重新加入频道。

参数

uid

加入频道的用户 ID。

elapsed

从本地用户调用 joinChannel 到该回调被触发的延迟（毫秒）。

所属接口类

• IRtcEngineEventHandler

onUserOffline

远端用户或主播离开频道时触发的回调。

Java

public void onUserOffline(int uid, int reason)

用户离线通常有以下两种原因：

• 离开频道：当用户或主播离开频道时，会发送一条离开消息。
• 掉线：在一段时间内（频道场景为 20 秒，极速直播场景更长）未收到用户或主播的数据包时，SDK 会认为其掉线。网络连接不佳可能导致误判，建议使用声网 RTM SDK 进行可靠的离线检测。

触发时机

该回调在远端用户（在频道场景中）或主播（在极速直播场景中）离开频道时被触发。

参数

uid

离开频道或掉线的用户 ID。

reason

远端用户（在频道场景中）或主播（在极速直播场景中）离线的原因：

• USER_OFFLINE_QUIT (0)：用户主动退出通话，发送离开消息。
• USER_OFFLINE_DROPPED (1)：SDK 超时未收到任何数据包，用户掉线。网络连接不佳可能导致误判，建议使用声网 RTM SDK 进行可靠的离线检测。
• USER_OFFLINE_BECOME_AUDIENCE (2)：用户将角色从主播切换为观众。

所属接口类

• IRtcEngineEventHandler