需要访问旧版文档站？前往旧版文档官网首页。 (在新标签页打开)
声网文档中心

频道相关

  • Android

更新时间不可用

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：方法调用失败。详见错误码了解详情和解决建议。

所属接口类

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。

所属接口类

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：方法调用失败。详见错误码了解详情和解决建议。

所属接口类

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：方法调用失败。详见错误码了解详情和解决建议。

所属接口类

joinChannel [1/2]

加入一个频道。

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

默认情况下，用户会订阅频道中其他所有用户的音视频流，从而产生使用量和计费。如需停止订阅指定流或所有远端流，请调用 muteRemoteAudio/VideoStream 或 muteAllRemoteAudio/VideoStreams。

注：

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

调用时机

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

相关回调

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

当由于网络状况不佳导致本地客户端与声网服务器的连接中断时，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³¹ 到 2³¹-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 重新加入频道。

所属接口类

joinChannel [2/2]

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

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

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

注：

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

调用时机

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

相关回调

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

当由于网络状况不佳导致本地客户端与声网服务器的连接中断时，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 重新加入频道。

所属接口类

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] 方法之后调用。

相关回调

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

当由于网络状况不佳导致本地客户端与声网服务器的连接中断时，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 以重新加入频道。

所属接口类

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。 一旦用户加入频道，默认会订阅频道中所有其他用户的音视频流，从而产生用量和计费。如需停止订阅指定流或所有远端流，请调用 muteRemoteAudio/VideoStream 或 muteAllRemoteAudio/VideoStreams。

注：

  • 该方法仅支持用户同时加入一个频道。
  • 不同 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 重新加入频道。

所属接口类

joinChannelWithUserAccount [2/2]

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

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

自从

自 v3.3.0 版本新增。

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

注：

  • 此方法仅支持用户同时加入一个频道。
  • 不同 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 重新加入频道。

所属接口类

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 参数或调用 muteRemoteAudio/VideoStream 或 muteAllRemoteAudio/VideoStreams。

注：

  • 该方法仅支持用户同时加入一个频道。
  • 不同 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 后重新加入频道。

所属接口类

leaveChannel [1/2]

离开频道。

Java
public abstract int leaveChannel();

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

注：

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

调用时机

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

相关回调

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

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

返回值

  • 0：方法调用成功。

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

    • -1：发生通用错误（无明确原因）。
    • -2：参数无效。
    • -7：SDK 未初始化。

所属接口类

leaveChannel [2/2]

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

Java
public abstract int leaveChannel(LeaveChannelOptions options);

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

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

调用时机

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

相关回调

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

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

参数

参数名描述
options

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

表格内容超出当前宽度，可横向滚动查看更多列。

返回值

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

所属接口类

leaveChannelEx [1/2]

离开频道。

Java
public abstract int leaveChannelEx(RtcConnection connection);

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

注：

适用场景

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

调用时机

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

相关回调

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

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

参数

参数名描述
connection

连接信息，详见 RtcConnection。

表格内容超出当前宽度，可横向滚动查看更多列。

返回值

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

所属接口类

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：方法调用失败。详见错误码了解详情和解决建议。

所属接口类

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³¹ 到 2³¹-1。如果未指定用户 ID（或设置为 0），SDK 会分配一个随机用户 ID，并在 onJoinChannelSuccess 回调中返回。你的应用必须记录并维护返回的用户 ID，SDK 不会保存。

表格内容超出当前宽度，可横向滚动查看更多列。

返回值

  • 0：方法调用成功。

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

    • -7：RtcEngine 对象尚未初始化。请先初始化 RtcEngine 对象再调用该方法。
    • -102：频道名无效。请传入有效的频道名并重新加入频道。

所属接口类

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：频道名无效。请传入有效的频道名后重新加入频道。

所属接口类

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：方法调用失败。详见错误码了解详情和解决建议。

所属接口类

renewToken

更新 Token。

Java
public abstract int renewToken(String token);

成功调用该方法后，SDK 会触发 onRenewTokenResult 回调。在单频道场景下，你可以在以下情况下调用该方法更新 Token：

参数

参数名描述
token

新的 Token。

表格内容超出当前宽度，可横向滚动查看更多列。

返回值

  • 0：方法调用成功。

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

    • -2：参数无效，例如传入的 Token 为空。

    • -7：RtcEngine 对象尚未初始化。请先初始化 RtcEngine 对象再调用该方法。

    • 110：Token 无效。请确保以下事项：

      • 生成 Token 时指定的用户 ID 与加入频道时使用的用户 ID 一致。
      • 生成的 Token 与加入频道时传入的 Token 相同。

所属接口类

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 未初始化。

所属接口类

setClientRole [1/2]

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

Java
public abstract int setClientRole(int role);

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

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

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

调用时机

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

相关回调

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

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

参数

参数名描述
role

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

用户角色：

  • CLIENT_ROLE_BROADCASTER (1)：主播。
  • CLIENT_ROLE_AUDIENCE (2)：观众。
表格内容超出当前宽度，可横向滚动查看更多列。

返回值

  • 0：方法调用成功。

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

    • -1：发生通用错误（无具体原因）。
    • -2：参数无效。
    • -7：SDK 未初始化。

所属接口类

setClientRole [2/2]

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

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

默认情况下，SDK 会将用户角色设置为观众。你可以调用此方法将用户角色设置为主播。用户角色 (role) 决定了用户在 SDK 层级的权限，包括是否可以在频道中发布音视频流。 该方法与 setClientRole(int role) 的区别在于，它支持设置 audienceLatencyLevel。audienceLatencyLevel 需要与 role 搭配使用，以确定用户在其权限范围内可享受的服务等级。例如，观众可以选择接收低延迟或超低延迟的远端流。

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

调用时机

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

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

相关回调

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

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

参数

参数名描述
role

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

用户角色。

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

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

表格内容超出当前宽度，可横向滚动查看更多列。

返回值

  • 0：方法调用成功。

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

    • -1：发生通用错误（无明确原因）。
    • -2：参数无效。
    • -5：请求被拒绝。
    • -7：SDK 未初始化。

所属接口类

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 加入频道，再调用该方法。

所属接口类

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 加入频道，再调用该方法。

所属接口类

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 对象再调用此方法。

所属接口类

onClientRoleChanged

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

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

注： 当你在加入频道前调用 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。

表格内容超出当前宽度，可横向滚动查看更多列。

所属接口类

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)：观众，只能接收音视频流。
表格内容超出当前宽度，可横向滚动查看更多列。

所属接口类

onError

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

Java
public void onError(int err)

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

触发时机

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

参数

参数名描述
err

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

表格内容超出当前宽度，可横向滚动查看更多列。

所属接口类

onJoinChannelSuccess

本地用户成功加入频道回调。

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

触发时机

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

参数

参数名描述
channel

频道名。

uid

加入频道的用户 ID。

elapsed

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

表格内容超出当前宽度，可横向滚动查看更多列。

所属接口类

onLeaveChannel

用户离开频道回调。

Java
public void onLeaveChannel(RtcStats stats) {}

触发时机

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

参数

参数名描述
stats

通话统计信息。详见 RtcStats。

表格内容超出当前宽度，可横向滚动查看更多列。

所属接口类

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。

表格内容超出当前宽度，可横向滚动查看更多列。

所属接口类

onRejoinChannelSuccess

用户重新加入频道回调。

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

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

触发时机

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

参数

参数名描述
channel

频道名。

uid

重新加入频道的用户 ID。

elapsed

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

表格内容超出当前宽度，可横向滚动查看更多列。

所属接口类

onRenewTokenResult

renewToken 调用结果回调。

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

自从

自 v4.6.0 版本新增。

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

触发时机

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

参数

参数名描述
token

用于鉴权的 Token。

code

错误码。详见 RenewTokenErrorCode。

表格内容超出当前宽度，可横向滚动查看更多列。

所属接口类

onRequestToken

Token 过期回调。

Java
public void onRequestToken() {}

该回调在 Token 过期时被触发。收到该回调后，你需要在 Token 服务器上生成新的 Token，并根据场景更新 Token：

  • 单频道场景：

    • 调用 renewToken 传入新的 Token，无需先离开频道。SDK 会通过 onRenewTokenResult 回调报告更新结果。
    • 如果你的 App 需要离开并重新加入频道，也可以调用 leaveChannel 离开频道，然后在调用 joinChannel 时传入新的 Token。

  • 多频道场景：调用 updateChannelMediaOptionsEx 传入新的 Token。

触发时机

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

所属接口类

onRtcStats

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

Java
public void onRtcStats(RtcStats stats) {}

触发时机

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

参数

参数名描述
stats

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

表格内容超出当前宽度，可横向滚动查看更多列。

所属接口类

onTokenPrivilegeWillExpire

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

Java
public void onTokenPrivilegeWillExpire(String token)

收到该回调时，你需要在 Token 服务器上生成新的 Token，并根据场景更新 Token：

  • 单频道场景：

    • 调用 renewToken 传入新的 Token，无需先离开频道。SDK 会通过 onRenewTokenResult 回调报告更新结果。
    • 如果你的 App 需要离开并重新加入频道，也可以调用 leaveChannel 离开频道，然后在调用 joinChannel 时传入新的 Token。

  • 多频道场景：调用 updateChannelMediaOptionsEx 传入新的 Token。

触发时机

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

参数

参数名描述
token

即将过期的 Token。

表格内容超出当前宽度，可横向滚动查看更多列。

所属接口类

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。

表格内容超出当前宽度，可横向滚动查看更多列。

所属接口类

onUserJoined

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

Java
public void onUserJoined(int uid, int elapsed)

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

触发时机

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

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

参数

参数名描述
uid

加入频道的用户 ID。

elapsed

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

表格内容超出当前宽度，可横向滚动查看更多列。

所属接口类

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)：用户将角色从主播切换为观众。
表格内容超出当前宽度，可横向滚动查看更多列。

所属接口类

咨询电话

400 632 6626

上海声网科技有限公司

Copyright © 2026 声网保留所有权利