# 频道相关 (/zh-CN/api-reference/rtc/android/4.6.0/channel) > For AI agents: see the complete documentation index at [llms.txt](/llms.txt). ## getUserInfoByUid [#getuserinfobyuid] 通过传入用户 ID 获取用户信息。 ```java public abstract int getUserInfoByUid(int uid, UserInfo userInfo); ``` 当远端用户加入频道后,SDK 会获取该远端用户的用户 ID 和用户 User Account,并将其缓存在映射表中,同时在本地客户端触发 [onUserInfoUpdated](/zh-CN/api-reference/rtc/android/channel#callback_irtcengineeventhandler_onuserinfoupdated) 回调。收到该回调后,你可以调用 [getUserInfoByUid](/zh-CN/api-reference/rtc/android/channel#api_irtcengine_getuserinfobyuid) 方法并传入用户 ID,从 [UserInfo](/zh-CN/api-reference/rtc/android/class-and-enum/classes/class-userinfo) 对象中获取指定用户的用户 User Account。 ### 调用时机 [#调用时机] 该方法在收到 [onUserInfoUpdated](/zh-CN/api-reference/rtc/android/channel#callback_irtcengineeventhandler_onuserinfoupdated) 回调后调用。 ### 参数 [#参数] #### `uid` [#uid] `uid`,表示用户 ID。 #### `userInfo` [#userinfo] 输入和输出参数,用于标识用户信息的 [UserInfo](/zh-CN/api-reference/rtc/android/class-and-enum/classes/class-userinfo) 对象。详见 [UserInfo](/zh-CN/api-reference/rtc/android/class-and-enum/classes/class-userinfo)。 ### 返回值 [#返回值] - 0:方法调用成功。 - < 0:方法调用失败。详见[错误码](/zh-CN/realtime-media/rtc/reference/error-code)了解详情和解决建议。 ### 所属接口类 [#所属接口类] - [RtcEngine](/zh-CN/api-reference/rtc/android/full-sdk-api-list#class_irtcengine) ## getUserInfoByUidEx [#getuserinfobyuidex] 通过传入用户 ID 获取用户信息。 ```java public abstract int getUserInfoByUidEx(int uid, UserInfo userInfo, RtcConnection connection); ``` 当远端用户加入频道后,SDK 会获取该远端用户的用户 ID 和用户 User Account,并将其缓存在映射表中,同时在本地客户端触发 [onUserInfoUpdated](/zh-CN/api-reference/rtc/android/channel#callback_irtcengineeventhandler_onuserinfoupdated) 回调。收到该回调后,你可以调用 [getUserInfoByUidEx](/zh-CN/api-reference/rtc/android/channel#api_irtcengineex_getuserinfobyuidex) 并传入用户 ID,从 [UserInfo](/zh-CN/api-reference/rtc/android/class-and-enum/classes/class-userinfo) 对象中获取指定用户的用户 User Account。 ### 适用场景 [#适用场景] 适用于多频道场景。 ### 参数 [#参数-1] #### `uid` [#uid-1] 用户 ID。 #### `userInfo` [#userinfo-1] 用于标识用户信息的对象。详见 [UserInfo](/zh-CN/api-reference/rtc/android/class-and-enum/classes/class-userinfo)。 #### `connection` [#connection] 连接信息。详见 [RtcConnection](/zh-CN/api-reference/rtc/android/class-and-enum/classes/class-rtcconnection)。 ### 返回值 [#返回值-1] - 方法调用成功,返回 UserInfo 对象。 - 方法调用失败,返回 null。 ### 所属接口类 [#所属接口类-1] - [RtcEngineEx](/zh-CN/api-reference/rtc/android/full-sdk-api-list#class_irtcengineex) ## getUserInfoByUserAccount [#getuserinfobyuseraccount] 通过传入用户 User Account 获取用户信息。 ```java public abstract int getUserInfoByUserAccount(String userAccount, UserInfo userInfo); ``` 当远端用户加入频道后,SDK 会获取该远端用户的用户 ID 和用户 User Account,并将其缓存在映射表中,同时在本地客户端触发 [onUserInfoUpdated](/zh-CN/api-reference/rtc/android/channel#callback_irtcengineeventhandler_onuserinfoupdated) 回调。收到该回调后,你可以调用 [getUserInfoByUserAccount](/zh-CN/api-reference/rtc/android/channel#api_irtcengine_getuserinfobyuseraccount) 方法并传入用户 User Account,从 [UserInfo](/zh-CN/api-reference/rtc/android/class-and-enum/classes/class-userinfo) 对象中获取指定用户的信息。 ### 参数 [#参数-2] #### `userAccount` [#useraccount] 用户 User Account。 #### `userInfo` [#userinfo-2] 用于标识用户信息的 [UserInfo](/zh-CN/api-reference/rtc/android/class-and-enum/classes/class-userinfo) 对象。详见 [UserInfo](/zh-CN/api-reference/rtc/android/class-and-enum/classes/class-userinfo)。 ### 返回值 [#返回值-2] - 0:方法调用成功。 - < 0:方法调用失败。详见[错误码](/zh-CN/realtime-media/rtc/reference/error-code)了解详情和解决建议。 ### 所属接口类 [#所属接口类-2] - [RtcEngine](/zh-CN/api-reference/rtc/android/full-sdk-api-list#class_irtcengine) ## getUserInfoByUserAccountEx [#getuserinfobyuseraccountex] 通过用户 User Account 获取用户信息。 ```java public abstract int getUserInfoByUserAccountEx(String userAccount, UserInfo userInfo, RtcConnection connection); ``` 远端用户加入频道后,SDK 会获取该远端用户的用户 ID 和用户 User Account,并将其缓存在映射表中,同时在本地客户端触发 [onUserInfoUpdated](/zh-CN/api-reference/rtc/android/channel#callback_irtcengineeventhandler_onuserinfoupdated) 回调。收到该回调后,你可以调用 [getUserInfoByUserAccountEx](/zh-CN/api-reference/rtc/android/channel#api_irtcengineex_getuserinfobyuseraccountex) 并传入用户 User Account,从 [UserInfo](/zh-CN/api-reference/rtc/android/class-and-enum/classes/class-userinfo) 对象中获取指定用户的用户信息。 ### 适用场景 [#适用场景-1] 该方法适用于多频道场景。 ### 参数 [#参数-3] #### `userAccount` [#useraccount-1] 用户 User Account。 #### `userInfo` [#userinfo-3] 输入和输出参数,用于标识用户信息。详见 [UserInfo](/zh-CN/api-reference/rtc/android/class-and-enum/classes/class-userinfo)。 #### `connection` [#connection-1] 连接信息。详见 [RtcConnection](/zh-CN/api-reference/rtc/android/class-and-enum/classes/class-rtcconnection)。 ### 返回值 [#返回值-3] - 0:方法调用成功。 - < 0:方法调用失败。详见[错误码](/zh-CN/realtime-media/rtc/reference/error-code)了解详情和解决建议。 ### 所属接口类 [#所属接口类-3] - [RtcEngineEx](/zh-CN/api-reference/rtc/android/full-sdk-api-list#class_irtcengineex) ## joinChannel [1/2] [#joinchannel-12] 加入一个频道。 ```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 相同,否则可能会导致加入频道失败。 ### 调用时机 [#调用时机-1] 请在调用 [create [2/2]](/zh-CN/api-reference/rtc/android/initialize#api_irtcengine_initialize) 方法后调用本方法。 ### 相关回调 [#相关回调] 调用该方法成功后会触发以下回调: - 本地客户端: onJoinChannelSuccess 和 onConnectionStateChanged 回调。 - 远端客户端:如果是 COMMUNICATION 频道场景中有用户加入频道,或 LIVE_BROADCASTING 频道场景中有主播加入频道,则触发 onUserJoined 回调。 当由于网络状况不佳导致本地客户端与声网服务器的连接中断时,SDK 会尝试重连服务器。当本地客户端成功重回频道时,SDK 会触发本地客户端的 [onRejoinChannelSuccess](/zh-CN/api-reference/rtc/android/channel#callback_irtcengineeventhandler_onrejoinchannelsuccess) 回调。 ### 参数 [#参数-4] #### `token` [#token] 在你的服务器上生成的用于鉴权的 Token。 注: - (推荐)如果你的项目启用了安全模式(使用 App ID 和 Token 进行鉴权),该参数为必填。 - 如果你仅启用了测试模式(使用 App ID 进行鉴权),该参数为可选。成功加入频道后,24 小时后会自动退出频道。 - 如果你需要同时加入多个频道或在频道间切换,声网建议使用通配符 Token,这样每次加入频道时无需重新申请 Token。 #### `channelId` [#channelid] 频道名。在相同 App ID 的前提下,填写相同频道名的用户会进入同一个频道进行音视频互动。字符串长度必须小于 64 字节。支持的字符(共 89 个): - 所有小写英文字母:a 到 z。 - 所有大写英文字母:A 到 Z。 - 所有数字字符:0 到 9。 - "!", "#", "$", "%", "&", "(", ")", "+", "-", ":", ";", "<", "=", ".", ">", "?", "@", "[", "]", "^", "_", "\{", "\}", "|", "~", "," #### `optionalInfo` [#optionalinfo] (可选)预留参数。 #### `uid` [#uid-2] 用户 ID。用于标识频道中的用户以进行实时音视频互动。你需要自行设置和管理用户 ID,并确保同一频道中每个用户 ID 唯一。该参数为 32 位无符号整数,取值范围为 -2³¹ 到 2³¹-1。如果未指定用户 ID(或设置为 0),SDK 会自动分配一个随机用户 ID,并通过 [onJoinChannelSuccess](/zh-CN/api-reference/rtc/android/channel#callback_irtcengineeventhandler_onjoinchannelsuccess) 回调返回。你的应用需记录并维护该返回的用户 ID,SDK 不会保存。 ### 返回值 [#返回值-4] - 0:方法调用成功。 - < 0:方法调用失败。详见[错误码](/zh-CN/realtime-media/rtc/reference/error-code)了解详情和解决建议。 - -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 重新加入频道。 ### 所属接口类 [#所属接口类-4] - [RtcEngine](/zh-CN/api-reference/rtc/android/full-sdk-api-list#class_irtcengine) ## joinChannel [2/2] [#joinchannel-22] 加入频道并设置媒体选项。 ```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 一致,否则可能导致加入频道失败。 ### 调用时机 [#调用时机-2] 请在调用 [create [2/2]](/zh-CN/api-reference/rtc/android/initialize#api_irtcengine_initialize) 方法后调用该方法。 ### 相关回调 [#相关回调-1] 调用该方法成功后会触发以下回调: - 本地客户端: onJoinChannelSuccess 和 onConnectionStateChanged 回调。 - 远端客户端:如果用户在 COMMUNICATION 频道场景中加入频道,或主播在 LIVE_BROADCASTING 频道场景中加入频道,会触发 onUserJoined 回调。 当由于网络状况不佳导致本地客户端与声网服务器的连接中断时,SDK 会尝试重新连接服务器。当本地客户端成功重新加入频道时,SDK 会在本地客户端触发 [onRejoinChannelSuccess](/zh-CN/api-reference/rtc/android/channel#callback_irtcengineeventhandler_onrejoinchannelsuccess) 回调。 ### 参数 [#参数-5] #### `token` [#token-1] 在你的服务器上生成的用于鉴权的 Token。 注: - (推荐)如果你的项目启用了安全模式(使用 App ID 和 Token 进行鉴权),该参数为必填。 - 如果只启用了测试模式(使用 App ID 进行鉴权),该参数为可选。成功加入频道后,24 小时后会自动退出频道。 - 如果你需要同时加入多个频道或在频道间切换,声网建议使用通配符 Token,这样每次加入频道时无需重新申请 Token。 #### `channelId` [#channelid-1] 频道名。在相同 App ID 的前提下,填写相同频道名的用户会进入同一个频道进行音视频互动。字符串长度必须小于 64 字节。支持的字符(共 89 个): - 所有小写英文字母:a 到 z。 - 所有大写英文字母:A 到 Z。 - 所有数字字符:0 到 9。 - "!", "#", "$", "%", "&", "(", ")", "+", "-", ":", ";", "<", "=", ".", ">", "?", "@", "[", "]", "^", "_", "\{", "\}", "|", "~", ","。 #### `uid` [#uid-3] 用户 ID。用于标识频道中的用户。你需要自行设置和管理用户 ID,并确保同一频道中每个用户 ID 唯一。该参数为 32 位无符号整数,取值范围为 -2³¹ 到 2³¹-1。如果未指定用户 ID(或设置为 0),SDK 会自动分配一个随机用户 ID,并在 [onJoinChannelSuccess](/zh-CN/api-reference/rtc/android/channel#callback_irtcengineeventhandler_onjoinchannelsuccess) 回调中返回。你的应用必须记录并维护该返回的用户 ID,SDK 不会保存。 #### `options` [#options] 频道媒体选项,详见 [ChannelMediaOptions](/zh-CN/api-reference/rtc/android/class-and-enum/classes/class-channelmediaoptions)。 ### 返回值 [#返回值-5] - 0:方法调用成功。 - < 0:方法调用失败。详见[错误码](/zh-CN/realtime-media/rtc/reference/error-code)了解详情和解决建议。 - -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 重新加入频道。 ### 所属接口类 [#所属接口类-5] - [RtcEngine](/zh-CN/api-reference/rtc/android/full-sdk-api-list#class_irtcengine) ## joinChannelEx [#joinchannelex] 加入一个频道。 ```java public abstract int joinChannelEx(String token, RtcConnection connection, ChannelMediaOptions options, IRtcEngineEventHandler eventHandler); ``` 你可以多次调用此方法加入多个频道。 在多摄像头采集场景中,调用此方法后需要调用 `startPreview` 方法,并将 `sourceType` 设置为 `VIDEO_SOURCE_CAMERA_SECONDARY`,以确保第二路摄像头正常采集。 :::info[注] 如果你已经在一个频道中,不能使用相同的用户 ID 重新加入该频道。 在加入频道前,确保用于生成 Token 的 App ID 与调用 [create [2/2]](/zh-CN/api-reference/rtc/android/initialize#api_irtcengine_initialize) 方法时传入的 App ID 相同,否则可能会导致加入频道失败。 ::: ### 适用场景 [#适用场景-2] 该方法适用于多频道场景。 ### 调用时机 [#调用时机-3] 在调用 [create [2/2]](/zh-CN/api-reference/rtc/android/initialize#api_irtcengine_initialize) 方法之后调用。 ### 相关回调 [#相关回调-2] 成功调用该方法会触发以下回调: - 本地客户端: onJoinChannelSuccess 和 onConnectionStateChanged 回调。 - 远端客户端:如果是 COMMUNICATION 频道场景中有用户加入频道,或 LIVE_BROADCASTING 频道场景中有主播加入频道,则触发 onUserJoined 回调。 当由于网络状况不佳导致本地客户端与声网服务器的连接中断时,SDK 会尝试重连服务器。当本地客户端成功重新加入频道时,SDK 会触发本地客户端的 [onRejoinChannelSuccess](/zh-CN/api-reference/rtc/android/channel#callback_irtcengineeventhandler_onrejoinchannelsuccess) 回调。 ### 参数 [#参数-6] #### `token` [#token-2] 用于鉴权的 Token。 注: - (推荐)如果你的项目启用了安全模式(使用 App ID 和 Token 进行鉴权),该参数为必填。 - 如果你只启用了测试模式(使用 App ID 进行鉴权),该参数为可选。成功加入频道后,你将在 24 小时后自动退出频道。 - 如果你需要同时加入不同频道或在频道之间切换,声网建议使用通配符 Token,这样你每次加入频道时无需重新申请 Token。 #### `connection` [#connection-2] 连接信息。详见 [RtcConnection](/zh-CN/api-reference/rtc/android/class-and-enum/classes/class-rtcconnection)。 #### `options` [#options-1] 频道媒体选项。详见 [ChannelMediaOptions](/zh-CN/api-reference/rtc/android/class-and-enum/classes/class-channelmediaoptions)。 #### `eventHandler` [#eventhandler] 回调类。详见 [IRtcEngineEventHandler](/zh-CN/api-reference/rtc/android/full-sdk-api-list#class_irtcengineeventhandler)。你可以通过该参数传入的 `eventHandler` 对象获取多个频道的回调事件。 ### 返回值 [#返回值-6] - 0:方法调用成功。 - < 0:方法调用失败。详见[错误码](/zh-CN/realtime-media/rtc/reference/error-code)了解详情和解决建议。 - -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 以重新加入频道。 ### 所属接口类 [#所属接口类-6] - [RtcEngineEx](/zh-CN/api-reference/rtc/android/full-sdk-api-list#class_irtcengineex) ## joinChannelWithUserAccount [1/2] [#joinchannelwithuseraccount-12] 使用用户 User Account 和 Token 加入频道。 ```java public abstract int joinChannelWithUserAccount(String token, String channelName, String userAccount); ``` 调用 [registerLocalUserAccount](/zh-CN/api-reference/rtc/android/channel#api_irtcengine_registerlocaluseraccount) 注册用户 User Account 后再调用此方法加入频道,可以缩短进入频道所需的时间。如果你尚未调用 [registerLocalUserAccount](/zh-CN/api-reference/rtc/android/channel#api_irtcengine_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 设置为相同的参数类型。 ### 调用时机 [#调用时机-4] 请在调用 [create [2/2]](/zh-CN/api-reference/rtc/android/initialize#api_irtcengine_initialize) 方法后调用此方法。 ### 相关回调 [#相关回调-3] 本地客户端: [onLocalUserRegistered](/zh-CN/api-reference/rtc/android/channel#callback_irtcengineeventhandler_onlocaluserregistered)、 [onJoinChannelSuccess](/zh-CN/api-reference/rtc/android/channel#callback_irtcengineeventhandler_onjoinchannelsuccess) 和 [onConnectionStateChanged](/zh-CN/api-reference/rtc/android/network-and-other#callback_irtcengineeventhandler_onconnectionstatechanged) 回调。 远端客户端:如果用户在 `COMMUNICATION` 频道场景中加入频道,或主播在 `LIVE_BROADCASTING` 频道场景中加入频道,则会触发 [onUserJoined](/zh-CN/api-reference/rtc/android/channel#callback_irtcengineeventhandler_onuserjoined) 和 [onUserInfoUpdated](/zh-CN/api-reference/rtc/android/channel#callback_irtcengineeventhandler_onuserinfoupdated) 回调。 ### 参数 [#参数-7] #### `token` [#token-3] 在你的服务器上生成的用于鉴权的 Token。 注: - (推荐)如果你的项目启用了安全模式(使用 App ID 和 Token 进行鉴权),该参数为必填。 - 如果你只启用了测试模式(使用 App ID 进行鉴权),该参数为可选。成功加入频道后,你将在 24 小时后自动退出频道。 - 如果你需要同时加入不同频道或在频道间切换,声网建议使用通配符 Token,这样你每次加入频道时无需重新申请 Token。 #### `channelName` [#channelname] 频道名。在相同 App ID 的前提下,填写相同频道名的用户会进入同一个频道进行音视频互动。字符串长度必须小于 64 字节。支持的字符(共 89 个): - 所有小写英文字母:a 到 z。 - 所有大写英文字母:A 到 Z。 - 所有数字字符:0 到 9。 - "!", "#", "$", "%", "&", "(", ")", "+", "-", ":", ";", "<", "=", ".", ">", "?", "@", "[", "]", "^", "_", "\{", "\}", "|", "~", "," #### `userAccount` [#useraccount-2] 用户 User Account。用于标识频道中的用户以进行实时音视频互动。你需要自行设置和管理用户 User Account,并确保同一频道中的每个用户 User Account 唯一。该参数的最大长度为 255 字节,不能为空。支持的字符如下(共 89 个): - 26 个小写英文字母:a 到 z。 - 26 个大写英文字母:A 到 Z。 - 所有数字字符:0 到 9。 - 空格 - "!", "#", "$", "%", "&", "(", ")", "+", "-", ":", ";", "<", "=", ".", ">", "?", "@", "[", "]", "^", "_", "\{", "\}", "|", "~", "," ### 返回值 [#返回值-7] - 0:方法调用成功。 - < 0:方法调用失败。详见[错误码](/zh-CN/realtime-media/rtc/reference/error-code)了解详情和解决建议。 - -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 重新加入频道。 ### 所属接口类 [#所属接口类-7] - [RtcEngine](/zh-CN/api-reference/rtc/android/full-sdk-api-list#class_irtcengine) ## joinChannelWithUserAccount [2/2] [#joinchannelwithuseraccount-22] 使用用户 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 的类型一致。 ### 调用时机 [#调用时机-5] 在调用 [create [2/2]](/zh-CN/api-reference/rtc/android/initialize#api_irtcengine_initialize) 方法之后调用此方法。 ### 相关回调 [#相关回调-4] 本地客户端: [onLocalUserRegistered](/zh-CN/api-reference/rtc/android/channel#callback_irtcengineeventhandler_onlocaluserregistered)、 [onJoinChannelSuccess](/zh-CN/api-reference/rtc/android/channel#callback_irtcengineeventhandler_onjoinchannelsuccess) 和 [onConnectionStateChanged](/zh-CN/api-reference/rtc/android/network-and-other#callback_irtcengineeventhandler_onconnectionstatechanged) 回调。 远端客户端:如果用户在 `COMMUNICATION` 频道场景中加入频道,或主播在 `LIVE_BROADCASTING` 频道场景中加入频道,则触发 [onUserJoined](/zh-CN/api-reference/rtc/android/channel#callback_irtcengineeventhandler_onuserjoined) 和 [onUserInfoUpdated](/zh-CN/api-reference/rtc/android/channel#callback_irtcengineeventhandler_onuserinfoupdated) 回调。 ### 参数 [#参数-8] #### `token` [#token-4] 在你的服务器上生成的用于鉴权的 Token。 注: - (推荐)如果你的项目启用了安全模式(使用 App ID 和 Token 进行鉴权),此参数为必填。 - 如果你仅启用了测试模式(使用 App ID 进行鉴权),此参数为可选。成功加入频道后,24 小时后会自动退出频道。 - 如果你需要同时加入多个频道或在频道间切换,声网建议使用通配符 Token,这样你每次加入频道时无需重新申请 Token。 #### `channelName` [#channelname-1] 频道名。在相同 App ID 前提下,填写相同频道名的用户会进入同一个频道进行音视频互动。字符串长度必须小于 64 字节。支持的字符(共 89 个): - 所有小写英文字母:a 到 z。 - 所有大写英文字母:A 到 Z。 - 所有数字字符:0 到 9。 - "!", "#", "$", "%", "&", "(", ")", "+", "-", ":", ";", "<", "=", ".", ">", "?", "@", "[", "]", "^", "_", "\{", "\}", "|", "~", "," #### `userAccount` [#useraccount-3] 用户 User Account。你需要自行设置和管理用户 User Account,并确保同一频道内的每个用户 User Account 唯一。该参数最大长度为 255 字节,不能为空。支持的字符如下(共 89 个): - 26 个小写英文字母:a 到 z。 - 26 个大写英文字母:A 到 Z。 - 所有数字字符:0 到 9。 - 空格 - "!", "#", "$", "%", "&", "(", ")", "+", "-", ":", ";", "<", "=", ".", ">", "?", "@", "[", "]", "^", "_", "\{", "\}", "|", "~", "," #### `options` [#options-2] 频道媒体选项,详见 [ChannelMediaOptions](/zh-CN/api-reference/rtc/android/class-and-enum/classes/class-channelmediaoptions)。 ### 返回值 [#返回值-8] - 0:方法调用成功。 - < 0:方法调用失败。详见[错误码](/zh-CN/realtime-media/rtc/reference/error-code)了解详情和解决建议。 - -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 重新加入频道。 ### 所属接口类 [#所属接口类-8] - [RtcEngine](/zh-CN/api-reference/rtc/android/full-sdk-api-list#class_irtcengine) ## joinChannelWithUserAccountEx [#joinchannelwithuseraccountex] 使用用户 User Account 和 Token 加入频道,并设置媒体选项。 ```java public abstract int joinChannelWithUserAccountEx(String token, String channelId, String userAccount, ChannelMediaOptions options, IRtcEngineEventHandler eventHandler); ``` 在调用此方法之前,如果你尚未调用 [registerLocalUserAccount](/zh-CN/api-reference/rtc/android/channel#api_irtcengine_registerlocaluseraccount) 注册用户 User Account,SDK 会在你调用此方法加入频道时自动创建用户 User Account。提前调用 [registerLocalUserAccount](/zh-CN/api-reference/rtc/android/channel#api_irtcengine_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 的参数类型一致。 ### 适用场景 [#适用场景-3] 该方法适用于多频道场景。 ### 调用时机 [#调用时机-6] 在调用 [create [2/2]](/zh-CN/api-reference/rtc/android/initialize#api_irtcengine_initialize) 之后调用此方法。 ### 相关回调 [#相关回调-5] 本地客户端: [onLocalUserRegistered](/zh-CN/api-reference/rtc/android/channel#callback_irtcengineeventhandler_onlocaluserregistered)、 [onJoinChannelSuccess](/zh-CN/api-reference/rtc/android/channel#callback_irtcengineeventhandler_onjoinchannelsuccess) 和 [onConnectionStateChanged](/zh-CN/api-reference/rtc/android/network-and-other#callback_irtcengineeventhandler_onconnectionstatechanged) 回调。 远端客户端:如果用户在 `COMMUNICATION` 频道场景中加入频道,或主播在 `LIVE_BROADCASTING` 频道场景中加入频道,则触发 [onUserJoined](/zh-CN/api-reference/rtc/android/channel#callback_irtcengineeventhandler_onuserjoined) 和 [onUserInfoUpdated](/zh-CN/api-reference/rtc/android/channel#callback_irtcengineeventhandler_onuserinfoupdated) 回调。 ### 参数 [#参数-9] #### `token` [#token-5] 在你的服务器上生成的用于鉴权的 Token。 注: - (推荐)如果你的项目启用了安全模式(使用 App ID 和 Token 进行鉴权),该参数为必填。 - 如果你只启用了测试模式(使用 App ID 进行鉴权),该参数为可选。成功加入频道后,你将在 24 小时后自动退出频道。 - 如果你需要同时加入多个频道或在频道间切换,声网建议使用通配符 Token,这样你无需每次加入频道时都申请新的 Token。 #### `channelId` [#channelid-2] 频道名。在相同 App ID 的前提下,填写相同频道名的用户会进入同一个频道进行音视频互动。字符串长度必须小于 64 字节。支持的字符(共 89 个): - 所有小写英文字母:a 到 z。 - 所有大写英文字母:A 到 Z。 - 所有数字字符:0 到 9。 - "!", "#", "$", "%", "&", "(", ")", "+", "-", ":", ";", "<", "=", ".", ">", "?", "@", "[", "]", "^", "_", "\{", "\}", "|", "~", "," #### `userAccount` [#useraccount-4] 用户 User Account。你需要自行设置和管理用户 User Account,并确保同一频道中的每个用户 User Account 唯一。该参数的最大长度为 255 字节,不能为空。支持的字符如下(共 89 个): - 26 个小写英文字母:a 到 z。 - 26 个大写英文字母:A 到 Z。 - 所有数字字符:0 到 9。 - 空格 - "!", "#", "$", "%", "&", "(", ")", "+", "-", ":", ";", "<", "=", ".", ">", "?", "@", "[", "]", "^", "_", "\{", "\}", "|", "~", "," #### `options` [#options-3] 频道媒体选项。详见 [ChannelMediaOptions](/zh-CN/api-reference/rtc/android/class-and-enum/classes/class-channelmediaoptions)。 #### `eventHandler` [#eventhandler-1] [RtcEngineEx](/zh-CN/api-reference/rtc/android/full-sdk-api-list#class_irtcengineex) 的回调类。详见 [IRtcEngineEventHandler](/zh-CN/api-reference/rtc/android/full-sdk-api-list#class_irtcengineeventhandler)。你可以通过该参数传入的 `eventHandler` 对象获取多个频道的回调事件。 ### 返回值 [#返回值-9] - 0:方法调用成功。 - < 0:方法调用失败。详见[错误码](/zh-CN/realtime-media/rtc/reference/error-code)了解详情和解决建议。 - -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 后重新加入频道。 ### 所属接口类 [#所属接口类-9] - [RtcEngineEx](/zh-CN/api-reference/rtc/android/full-sdk-api-list#class_irtcengineex) ## leaveChannel [1/2] [#leavechannel-12] 离开频道。 ```java public abstract int leaveChannel(); ``` 调用该方法后,SDK 会终止音视频互动,释放与会话相关的所有资源。加入频道后,必须调用该方法结束通话,否则无法开始下一次通话。 注: - 如果在调用该方法后立即调用 destroy [2/2],SDK 不会触发 onLeaveChannel 回调。 - 此方法为异步调用。当该方法返回时,并不代表用户已完全离开频道。 - 如果你调用了 joinChannelEx 加入了多个频道,调用该方法会离开你加入的所有频道。 ### 调用时机 [#调用时机-7] 在加入频道后调用该方法。 ### 相关回调 [#相关回调-6] 调用该方法成功后会触发以下回调: - 本地客户端实例:会触发 onLeaveChannel 回调。 - 远端客户端实例:远端主播离开频道后会触发 onUserOffline 回调。 ### 返回值 [#返回值-10] - 0:方法调用成功。 - < 0:方法调用失败。详见[错误码](/zh-CN/realtime-media/rtc/reference/error-code)了解详情和解决建议。 - -1:发生通用错误(无明确原因)。 - -2:参数无效。 - -7:SDK 未初始化。 ### 所属接口类 [#所属接口类-10] - [RtcEngine](/zh-CN/api-reference/rtc/android/full-sdk-api-list#class_irtcengine) ## leaveChannel [2/2] [#leavechannel-22] 设置频道选项并离开频道。 ```java public abstract int leaveChannel(LeaveChannelOptions options); ``` 调用该方法后,SDK 会终止音视频互动,离开当前频道,并释放与会话相关的所有资源。如果你调用了 [joinChannelEx](/zh-CN/api-reference/rtc/android/channel#api_irtcengineex_joinchannelex) 加入了多个频道,调用该方法会离开你加入的所有频道。 :::info[注] 如果在调用该方法后立即调用 [destroy [2/2]](/zh-CN/api-reference/rtc/android/initialize#api_irtcengine_destroy1),SDK 不会触发 [onLeaveChannel](/zh-CN/api-reference/rtc/android/channel#callback_irtcengineeventhandler_onleavechannel) 回调。该方法为异步调用。当该方法返回时,并不一定表示用户已离开频道。 ::: ### 调用时机 [#调用时机-8] 在加入频道后调用该方法。 ### 相关回调 [#相关回调-7] 调用该方法成功后会触发以下回调: - 本地客户端实例:触发 onLeaveChannel 回调。 - 远端客户端实例:远端主播离开频道后触发 onUserOffline 回调。 ### 参数 [#参数-10] #### `options` [#options-4] 离开频道的选项,详见 [LeaveChannelOptions](/zh-CN/api-reference/rtc/android/class-and-enum/classes/class-leavechanneloptions)。 ### 返回值 [#返回值-11] - 0:方法调用成功。 - < 0:方法调用失败。详见[错误码](/zh-CN/realtime-media/rtc/reference/error-code)了解详情和解决建议。 ### 所属接口类 [#所属接口类-11] - [RtcEngine](/zh-CN/api-reference/rtc/android/full-sdk-api-list#class_irtcengine) ## leaveChannelEx [1/2] [#leavechannelex-12] 离开频道。 ```java public abstract int leaveChannelEx(RtcConnection connection); ``` 调用该方法后,SDK 会终止音视频互动,离开当前频道,并释放与会话相关的所有资源。调用 [joinChannelEx](/zh-CN/api-reference/rtc/android/channel#api_irtcengineex_joinchannelex) 加入频道后,必须调用此方法或 `leaveChannelEx` 结束通话,否则无法开始下一次通话。 注: - 如果在调用该方法后立即调用 destroy [2/2],SDK 不会触发 onLeaveChannel 回调。 - 该方法为异步调用,方法返回时并不代表用户已离开频道。 - 如果调用 leaveChannel [1/2] 或 leaveChannel [2/2],你将离开通过 joinChannel [1/2]、 joinChannel [2/2] 或 joinChannelEx 加入的所有频道。 ### 适用场景 [#适用场景-4] 该方法适用于多频道场景。 ### 调用时机 [#调用时机-9] 在调用 [joinChannelEx](/zh-CN/api-reference/rtc/android/channel#api_irtcengineex_joinchannelex) 之后调用该方法。 ### 相关回调 [#相关回调-8] 调用成功后会触发以下回调: - 本地客户端实例:触发 onLeaveChannel 回调。 - 远端客户端实例:远端主播离开频道后触发 onUserOffline 回调。 ### 参数 [#参数-11] #### `connection` [#connection-3] 连接信息,详见 [RtcConnection](/zh-CN/api-reference/rtc/android/class-and-enum/classes/class-rtcconnection)。 ### 返回值 [#返回值-12] - 0:方法调用成功。 - < 0:方法调用失败。详见[错误码](/zh-CN/realtime-media/rtc/reference/error-code)了解详情和解决建议。 ### 所属接口类 [#所属接口类-12] - [RtcEngineEx](/zh-CN/api-reference/rtc/android/full-sdk-api-list#class_irtcengineex) ## leaveChannelEx [2/2] [#leavechannelex-22] 设置频道参数并离开频道。 ```java public abstract int leaveChannelEx(RtcConnection connection, LeaveChannelOptions options); ``` #### `自从` [#自从-1] 自 v4.1.0 版本新增。 调用该方法后,SDK 会终止音视频互动,并释放与会话相关的所有资源。调用 [joinChannelEx](/zh-CN/api-reference/rtc/android/channel#api_irtcengineex_joinchannelex) 加入频道后,必须调用此方法或 `leaveChannelEx(RtcConnection connection)` 结束通话,否则无法开始下一次通话。 注: - 如果在调用该方法后立即调用 destroy(),SDK 不会触发 onLeaveChannel 回调。 - 此方法为异步调用。当该方法返回时,并不代表你已离开频道。 - 如果调用 leaveChannel() 或 leaveChannel(LeaveChannelOptions options),将会离开通过 joinChannel [1/2]、 joinChannel [2/2] 或 joinChannelEx 加入的所有频道。 ### 适用场景 [#适用场景-5] 该方法适用于多频道场景。 ### 调用时机 [#调用时机-10] 在调用 [joinChannelEx](/zh-CN/api-reference/rtc/android/channel#api_irtcengineex_joinchannelex) 之后调用该方法。 ### 相关回调 [#相关回调-9] 调用该方法成功后会触发以下回调: - 本地客户端实例:会触发 onLeaveChannel 回调。 - 远端客户端实例:远端主播离开频道后会触发 onUserOffline 回调。 ### 参数 [#参数-12] #### `connection` [#connection-4] 连接信息,详见 [RtcConnection](/zh-CN/api-reference/rtc/android/class-and-enum/classes/class-rtcconnection)。 #### `options` [#options-5] 离开频道的选项。 :::info[注] 该参数仅支持 [LeaveChannelOptions](/zh-CN/api-reference/rtc/android/class-and-enum/classes/class-leavechanneloptions) 中的 `stopMicrophoneRecording` 成员,设置其他成员无效。 ::: ### 返回值 [#返回值-13] - 0:方法调用成功。 - < 0:方法调用失败。详见[错误码](/zh-CN/realtime-media/rtc/reference/error-code)了解详情和解决建议。 ### 所属接口类 [#所属接口类-13] - [RtcEngineEx](/zh-CN/api-reference/rtc/android/full-sdk-api-list#class_irtcengineex) ## preloadChannel [#preloadchannel] 预加载指定频道以缩短观众加入频道的时间。 ```java public abstract int preloadChannel(String token, String channelName, int optionalUid); ``` 当观众需要频繁切换不同频道时,调用该方法可以缩短加入频道的时间,从而减少观众听到和看到主播的延迟时间。如果你加入了一个已预加载的频道,离开后想重新加入该频道,除非用于预加载频道的 Token 过期,否则无需再次调用该方法。 注: - 调用该方法时,请确保将用户角色设置为观众,且未将音频场景设置为 AUDIO_SCENARIO_CHORUS,否则该方法不生效。 - 你还需要确保用于预加载的频道名、用户 ID 和 Token 与加入频道时传入的值一致,否则该方法不生效。 - 一个 RtcEngine 实例最多支持预加载 20 个频道,超出限制时,仅最近的 20 个预加载频道生效。 - 预加载频道失败并不意味着无法加入频道,也不会增加加入频道所需的时间。 ### 参数 [#参数-13] #### `token` [#token-6] 在你的服务器上生成的用于鉴权的 Token。当用于预加载频道的 Token 过期时,你可以根据预加载的频道数量更新 Token: - 预加载一个频道时,调用该方法传入新的 Token。 - 预加载多个频道时: - 如果你为所有预加载频道使用通配符 Token,调用 updatePreloadChannelToken 更新 Token。注意:生成通配符 Token 时,确保用户 ID 不为 0。 - 如果你为不同频道使用不同的 Token,调用该方法传入你的用户 ID、频道名和新的 Token。 #### `channelName` [#channelname-2] 你想要预加载的频道名。该参数表示用户进行实时音视频互动的频道。在相同 App ID 的前提下,填写相同频道名的用户会进入同一个频道进行音视频互动。字符串长度必须小于 64 字节。支持的字符(共 89 个): - 所有小写英文字母:a 到 z。 - 所有大写英文字母:A 到 Z。 - 所有数字字符:0 到 9。 - "!", "#", "$", "%", "&", "(", ")", "+", "-", ":", ";", "<", "=", ".", ">", "?", "@", "[", "]", "^", "_", "\{", "\}", "|", "~", ","。 #### `optionalUid` [#optionaluid] 用户 ID。用于标识频道中的用户以进行实时音视频互动。你需要自行设置和管理用户 ID,并确保同一频道中的每个用户 ID 唯一。该参数为 32 位无符号整数,取值范围为 -2³¹ 到 2³¹-1。如果未指定用户 ID(或设置为 0),SDK 会分配一个随机用户 ID,并在 [onJoinChannelSuccess](/zh-CN/api-reference/rtc/android/channel#callback_irtcengineeventhandler_onjoinchannelsuccess) 回调中返回。你的应用必须记录并维护返回的用户 ID,SDK 不会保存。 ### 返回值 [#返回值-14] - 0:方法调用成功。 - < 0:方法调用失败。详见[错误码](/zh-CN/realtime-media/rtc/reference/error-code)了解详情和解决建议。 - -7: RtcEngine 对象尚未初始化。请先初始化 RtcEngine 对象再调用该方法。 - -102:频道名无效。请传入有效的频道名并重新加入频道。 ### 所属接口类 [#所属接口类-14] - [RtcEngine](/zh-CN/api-reference/rtc/android/full-sdk-api-list#class_irtcengine) ## preloadChannelWithUserAccount [#preloadchannelwithuseraccount] 预加载指定频道,缩短观众加入频道的时间。 ```java public abstract int preloadChannelWithUserAccount(String token, String channelName, String userAccount); ``` 当观众需要频繁切换不同频道时,调用该方法可以缩短加入频道的时间,从而减少观众听到和看到主播的延迟。如果你加入了一个已预加载的频道,离开后想重新加入同一个频道,除非用于预加载频道的 Token 过期,否则无需再次调用该方法。 注: - 调用该方法时,请确保将用户角色设置为观众,且未将音频场景设置为 AUDIO_SCENARIO_CHORUS,否则该方法不生效。 - 你需要确保用于预加载的用户 User Account、频道名和 Token 与加入频道时传入的值一致,否则该方法不生效。 - 一个 RtcEngine 实例最多支持预加载 20 个频道。超过该限制时,仅最近的 20 个预加载频道生效。 - 预加载频道失败不会影响加入频道的能力,也不会增加加入频道所需的时间。 ### 调用时机 [#调用时机-11] 为提升预加载频道的用户体验,声网建议在确认频道名和用户信息后尽早调用该方法。 ### 参数 [#参数-14] #### `token` [#token-7] 你在服务器上生成的用于鉴权的 Token。当用于预加载频道的 Token 过期时,你可以根据预加载的频道数量更新 Token: - 预加载一个频道时,调用该方法传入新的 Token。 - 预加载多个频道时: - 如果你为所有预加载频道使用通配符 Token,调用 updatePreloadChannelToken 更新 Token。注意:生成通配符 Token 时,确保用户 ID 不为 0。 - 如果你为不同频道使用不同的 Token,调用该方法传入用户 User Account、频道名和新的 Token。 #### `channelName` [#channelname-3] 你想要预加载的频道名。字符串长度必须小于 64 字节。支持的字符(共 89 个): - 所有小写英文字母:a 到 z。 - 所有大写英文字母:A 到 Z。 - 所有数字字符:0 到 9。 - "!", "#", "$", "%", "&", "(", ")", "+", "-", ":", ";", "<", "=", ".", ">", "?", "@", "[", "]", "^", "_", "\{", "\}", "|", "~", "," #### `userAccount` [#useraccount-5] 用户 User Account,用于标识频道中的用户。你需要自行设置和管理用户 User Account,并确保同一频道中的每个用户 User Account 唯一。该参数最大长度为 255 字节,不能为空。支持的字符如下(共 89 个): - 26 个小写英文字母:a 到 z。 - 26 个大写英文字母:A 到 Z。 - 所有数字字符:0 到 9。 - 空格 - "!", "#", "$", "%", "&", "(", ")", "+", "-", ":", ";", "<", "=", ".", ">", "?", "@", "[", "]", "^", "_", "\{", "\}", "|", "~", "," ### 返回值 [#返回值-15] - 0:方法调用成功。 - < 0:方法调用失败。详见[错误码](/zh-CN/realtime-media/rtc/reference/error-code)了解详情和解决建议。 - -2:参数无效,例如用户 User Account 为空。请传入有效参数后重新加入频道。 - -7: RtcEngine 对象尚未初始化。请先初始化 RtcEngine 对象后再调用该方法。 - -102:频道名无效。请传入有效的频道名后重新加入频道。 ### 所属接口类 [#所属接口类-15] - [RtcEngine](/zh-CN/api-reference/rtc/android/full-sdk-api-list#class_irtcengine) ## registerLocalUserAccount [#registerlocaluseraccount] 注册用户 User Account。 ```java public abstract int registerLocalUserAccount(String appId, String userAccount); ``` 该方法用于注册用户 User Account。注册成功后,用户 User Account 可用于在加入频道时标识本地用户身份。该方法为可选项。如果你希望使用用户 User Account 加入频道,可以选择以下任一方式: - 先调用 registerLocalUserAccount 方法注册用户 User Account,再调用 joinChannelWithUserAccount 方法加入频道,可缩短进入频道所需时间。 - 直接调用 joinChannelWithUserAccount 方法加入频道。 ### 相关回调 [#相关回调-10] 成功调用该方法后,SDK 会触发 [onLocalUserRegistered](/zh-CN/api-reference/rtc/android/channel#callback_irtcengineeventhandler_onlocaluserregistered) 回调,报告本地用户的用户 ID 和用户 User Account。 ### 参数 [#参数-15] #### `appId` [#appid] 声网控制台中项目的 App ID。 #### `userAccount` [#useraccount-6] 用户 User Account,用于在频道中标识用户身份以实现实时音视频互动。你需要自行设置并管理用户 User Account,并确保同一频道内的每个用户 User Account 唯一。该参数的最大长度为 255 字节,不能为空。支持的字符共 89 个,包括: - 26 个小写英文字母:a 到 z。 - 26 个大写英文字母:A 到 Z。 - 所有数字字符:0 到 9。 - 空格 - "!"、"#"、"$"、"%"、"&"、"("、")"、"+"、"-"、":"、";"、"<"、"="、"."、">"、"?"、"@"、"["、"]"、"^"、"_"、"\{"、"\}"、"|"、"~"、"," ### 返回值 [#返回值-16] - 0:方法调用成功。 - < 0:方法调用失败。详见[错误码](/zh-CN/realtime-media/rtc/reference/error-code)了解详情和解决建议。 ### 所属接口类 [#所属接口类-16] - [RtcEngine](/zh-CN/api-reference/rtc/android/full-sdk-api-list#class_irtcengine) ## renewToken [#renewtoken] 更新 Token。 ```java public abstract int renewToken(String token); ``` 成功调用该方法后,SDK 会触发 [onRenewTokenResult](/zh-CN/api-reference/rtc/android/channel#callback_irtcengineeventhandler_onrenewtokenresult) 回调。在单频道场景下,你可以在以下情况下调用该方法更新 Token: - 收到 onTokenPrivilegeWillExpire 回调,提示 Token 即将过期。 - Token 已过期时,SDK 会触发 onRequestToken 回调,并在 onConnectionStateChanged 回调中报告 CONNECTION_CHANGED_TOKEN_EXPIRED (9)。 ### 参数 [#参数-16] #### `token` [#token-8] 新的 Token。 ### 返回值 [#返回值-17] - 0:方法调用成功。 - < 0:方法调用失败。详见[错误码](/zh-CN/realtime-media/rtc/reference/error-code)了解详情和解决建议。 - -2:参数无效,例如传入的 Token 为空。 - -7: RtcEngine 对象尚未初始化。请先初始化 RtcEngine 对象再调用该方法。 - 110:Token 无效。请确保以下事项: - 生成 Token 时指定的用户 ID 与加入频道时使用的用户 ID 一致。 - 生成的 Token 与加入频道时传入的 Token 相同。 ### 所属接口类 [#所属接口类-17] - [RtcEngine](/zh-CN/api-reference/rtc/android/full-sdk-api-list#class_irtcengine) ## setChannelProfile [#setchannelprofile] 设置频道场景。 ```java public abstract int setChannelProfile(int profile); ``` SDK 会根据不同的频道场景采用不同的优化策略,例如在直播场景中优先保证视频质量。初始化 SDK 后,默认频道场景为直播。 :::info[注] 为确保实时通信质量,建议频道内所有用户使用相同的频道场景。不同频道场景下,SDK 的默认音频路由也不同,详见 `setDefaultAudioRouteToSpeakerphone`。 ::: ### 调用时机 [#调用时机-12] 在加入频道前调用此方法。 ### 参数 [#参数-17] #### `profile` [#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。 ### 返回值 [#返回值-18] - 0:方法调用成功。 - < 0:方法调用失败。详见[错误码](/zh-CN/realtime-media/rtc/reference/error-code)了解详情和解决建议。 - -2:参数无效。 - -7:SDK 未初始化。 ### 所属接口类 [#所属接口类-18] - [RtcEngine](/zh-CN/api-reference/rtc/android/full-sdk-api-list#class_irtcengine) ## setClientRole [1/2] [#setclientrole-12] 设置客户端实例的用户角色。 ```java public abstract int setClientRole(int role); ``` 你可以调用该方法将用户角色设置为主播或观众。用户角色决定了用户在 SDK 层的权限,包括是否可以在频道中发布音视频流。 你可以在加入频道前或加入频道后调用该方法: - 如果你在加入频道前调用该方法将用户角色设置为主播,并通过 setupLocalVideo 设置本地视频属性,则用户加入频道时会自动开启本地视频预览。 - 如果你在加入频道后调用该方法设置用户角色,SDK 会自动调用 muteLocalAudioStream 和 muteLocalVideoStream 更改音视频流的发布状态。 :::info[注] 在加入频道前调用该方法并将用户角色设置为 `CLIENT_ROLE_BROADCASTER` 时,本地客户端不会触发 [onClientRoleChanged](/zh-CN/api-reference/rtc/android/channel#callback_irtcengineeventhandler_onclientrolechanged) 回调。加入频道前调用该方法并将 `role` 设置为 `CLIENT_ROLE_AUDIENCE` 时也会触发该回调。 ::: ### 调用时机 [#调用时机-13] 你可以在加入频道前或加入频道后调用此方法。 ### 相关回调 [#相关回调-11] 如果你在加入频道后调用此方法切换用户角色,SDK 会触发以下回调: - 本地客户端触发 onClientRoleChanged 回调。 - 远端客户端触发 onUserJoined 或 onUserOffline 回调。 如果你在加入频道后调用此方法设置用户角色但失败,SDK 会触发 [onClientRoleChangeFailed](/zh-CN/api-reference/rtc/android/channel#callback_irtcengineeventhandler_onclientrolechangefailed) 回调,报告失败原因和当前用户角色。 ### 参数 [#参数-18] #### `role` [#role] :::info[注] 如果你将用户角色设置为观众,则无法在频道中发布音视频流。 ::: 用户角色: - CLIENT_ROLE_BROADCASTER (1):主播。 - CLIENT_ROLE_AUDIENCE (2):观众。 ### 返回值 [#返回值-19] - 0:方法调用成功。 - < 0:方法调用失败。详见[错误码](/zh-CN/realtime-media/rtc/reference/error-code)了解详情和解决建议。 - -1:发生通用错误(无具体原因)。 - -2:参数无效。 - -7:SDK 未初始化。 ### 所属接口类 [#所属接口类-19] - [RtcEngine](/zh-CN/api-reference/rtc/android/full-sdk-api-list#class_irtcengine) ## setClientRole [2/2] [#setclientrole-22] 设置直播场景下的用户角色和观众延迟等级。 ```java public abstract int setClientRole(int role, ClientRoleOptions options); ``` 默认情况下,SDK 会将用户角色设置为观众。你可以调用此方法将用户角色设置为主播。用户角色 (`role`) 决定了用户在 SDK 层级的权限,包括是否可以在频道中发布音视频流。 该方法与 `setClientRole(int role)` 的区别在于,它支持设置 `audienceLatencyLevel`。 `audienceLatencyLevel` 需要与 `role` 搭配使用,以确定用户在其权限范围内可享受的服务等级。例如,观众可以选择接收低延迟或超低延迟的远端流。 :::info[注] 当用户角色设置为主播时,观众延迟等级只能设置为 `AUDIENCE_LATENCY_LEVEL_ULTRA_LOW_LATENCY`。 在加入频道前调用此方法并将 `role` 设置为 `BROADCASTER` 时,本地客户端不会触发 [onClientRoleChanged](/zh-CN/api-reference/rtc/android/channel#callback_irtcengineeventhandler_onclientrolechanged) 回调。 在加入频道前调用此方法并将 `role` 设置为 `AUDIENCE` 时,也会触发该回调。 ::: ### 调用时机 [#调用时机-14] 你可以在加入频道前或加入频道后调用此方法。 - 如果你在加入频道前调用此方法并通过 setupLocalVideo 设置本地视频属性,则用户加入频道时会自动开启本地视频预览。 - 如果你在加入频道后调用此方法设置用户角色,SDK 会自动调用 muteLocalAudioStream 和 muteLocalVideoStream 方法来改变音视频流的发布状态。 ### 相关回调 [#相关回调-12] 如果你在加入频道后调用此方法切换用户角色,SDK 会触发以下回调: - 本地客户端触发 onClientRoleChanged 回调。注意:在加入频道前调用此方法并将 role 设置为 AUDIENCE 也会触发该回调。 - 远端客户端触发 onUserJoined 或 onUserOffline 回调。 如果你在加入频道后调用此方法设置用户角色但失败,SDK 会触发 [onClientRoleChangeFailed](/zh-CN/api-reference/rtc/android/channel#callback_irtcengineeventhandler_onclientrolechangefailed) 回调,报告失败原因和当前用户角色。 ### 参数 [#参数-19] #### `role` [#role-1] :::info[注] 如果你将用户角色设置为观众,则无法在频道中发布音视频流。如果你希望在直播过程中发布媒体流,请确保将用户角色设置为主播。 ::: 用户角色。 - CLIENT_ROLE_BROADCASTER (1):主播。 - CLIENT_ROLE_AUDIENCE (2):观众(默认)。 #### `options` [#options-6] 用户的详细选项,详见 [ClientRoleOptions](/zh-CN/api-reference/rtc/android/class-and-enum/classes/class-clientroleoptions)。 ### 返回值 [#返回值-20] - 0:方法调用成功。 - < 0:方法调用失败。详见[错误码](/zh-CN/realtime-media/rtc/reference/error-code)了解详情和解决建议。 - -1:发生通用错误(无明确原因)。 - -2:参数无效。 - -5:请求被拒绝。 - -7:SDK 未初始化。 ### 所属接口类 [#所属接口类-20] - [RtcEngine](/zh-CN/api-reference/rtc/android/full-sdk-api-list#class_irtcengine) ## updateChannelMediaOptions [#updatechannelmediaoptions] 在加入频道后更新频道媒体选项。 ```java public abstract int updateChannelMediaOptions(ChannelMediaOptions options); ``` ### 参数 [#参数-20] #### `options` [#options-7] 频道媒体选项。详见 [ChannelMediaOptions](/zh-CN/api-reference/rtc/android/class-and-enum/classes/class-channelmediaoptions)。 ### 返回值 [#返回值-21] - 0:方法调用成功。 - < 0:方法调用失败。详见[错误码](/zh-CN/realtime-media/rtc/reference/error-code)了解详情和解决建议。 - -2: ChannelMediaOptions 中某个成员的值无效,例如 Token 或用户 ID 无效。你需要填写有效的参数。 - -7: RtcEngine 对象尚未初始化。你需要先初始化 RtcEngine 对象再调用该方法。 - -8: RtcEngine 对象的内部状态错误。可能的原因是用户不在频道中。声网建议你使用 onConnectionStateChanged 回调判断用户是否在频道中。如果你收到 CONNECTION_STATE_DISCONNECTED (1)或 CONNECTION_STATE_FAILED (5)状态,说明用户不在频道中。你需要先调用 joinChannel 加入频道,再调用该方法。 ### 所属接口类 [#所属接口类-21] - [RtcEngine](/zh-CN/api-reference/rtc/android/full-sdk-api-list#class_irtcengine) ## updateChannelMediaOptionsEx [#updatechannelmediaoptionsex] 加入频道后更新频道媒体选项。 ```java public abstract int updateChannelMediaOptionsEx(ChannelMediaOptions options, RtcConnection connection); ``` ### 适用场景 [#适用场景-6] 该方法适用于多频道场景。 ### 参数 [#参数-21] #### `options` [#options-8] 频道媒体选项。详见 [ChannelMediaOptions](/zh-CN/api-reference/rtc/android/class-and-enum/classes/class-channelmediaoptions)。 #### `connection` [#connection-5] 连接信息。详见 [RtcConnection](/zh-CN/api-reference/rtc/android/class-and-enum/classes/class-rtcconnection)。 ### 返回值 [#返回值-22] - 0:方法调用成功。 - < 0:方法调用失败。详见[错误码](/zh-CN/realtime-media/rtc/reference/error-code)了解详情和解决建议。 - -2: ChannelMediaOptions 中的成员值无效,例如 token 或用户 ID 无效。你需要填写有效的参数。 - -7: RtcEngine 对象尚未初始化。你需要先初始化 RtcEngine 对象再调用该方法。 - -8: RtcEngine 对象的内部状态错误,可能的原因是用户不在频道中。声网建议你使用 onConnectionStateChanged 回调判断用户是否在频道中。如果你收到 CONNECTION_STATE_DISCONNECTED (1)或 CONNECTION_STATE_FAILED (5)状态,说明用户不在频道中。你需要先调用 joinChannel 加入频道,再调用该方法。 ### 所属接口类 [#所属接口类-22] - [RtcEngineEx](/zh-CN/api-reference/rtc/android/full-sdk-api-list#class_irtcengineex) ## updatePreloadChannelToken [#updatepreloadchanneltoken] 更新用于预加载频道的通配 Token。 ```java public abstract int updatePreloadChannelToken(String token); ``` 你需要自行维护通配 Token 的生命周期。当该 Token 过期时,需要生成新的通配 Token,并调用该方法传入新的 Token。 ### 适用场景 [#适用场景-7] 适用于涉及多个频道的场景,例如在不同频道之间切换时,使用通配 Token 可以避免用户每次加入新频道时都申请新的 Token,从而节省切换频道的时间,并减轻你的 Token 服务器的压力。 ### 参数 [#参数-22] #### `token` [#token-9] 新的 Token。 ### 返回值 [#返回值-23] - 0:方法调用成功。 - < 0:方法调用失败。详见[错误码](/zh-CN/realtime-media/rtc/reference/error-code)了解详情和解决建议。 - -2:参数无效,例如 Token 无效。你需要传入有效参数并重新加入频道。 - -7: RtcEngine 对象尚未初始化。你需要先初始化 RtcEngine 对象再调用此方法。 ### 所属接口类 [#所属接口类-23] - [RtcEngine](/zh-CN/api-reference/rtc/android/full-sdk-api-list#class_irtcengine) ## onClientRoleChanged [#onclientrolechanged] 用户角色或观众延迟级别发生变化回调。 ```java public void onClientRoleChanged(int oldRole, int newRole, ClientRoleOptions newRoleOptions) ``` :::info[注] 当你在加入频道前调用 [setClientRole [1/2]](/zh-CN/api-reference/rtc/android/channel#api_irtcengine_setclientrole1) 或 [setClientRole [2/2]](/zh-CN/api-reference/rtc/android/channel#api_irtcengine_setclientrole2) 并将用户角色设置为主播时,该回调不会被触发。 ::: ### 触发时机 [#触发时机] 该回调在以下任一情况下被触发: - 加入频道后调用 setClientRole [1/2] 或 setClientRole [2/2] 设置用户角色或观众延迟级别; - 加入频道前调用 setClientRole [1/2] 或 setClientRole [2/2] 并将用户角色设置为观众。 ### 参数 [#参数-23] #### `oldRole` [#oldrole] 用户切换前的角色: - CLIENT_ROLE_BROADCASTER (1):主播。 - CLIENT_ROLE_AUDIENCE (2):观众。 #### `newRole` [#newrole] 用户切换后的角色: - CLIENT_ROLE_BROADCASTER (1):主播。 - CLIENT_ROLE_AUDIENCE (2):观众。 #### `newRoleOptions` [#newroleoptions] 用户切换后的角色属性,详见 [ClientRoleOptions](/zh-CN/api-reference/rtc/android/class-and-enum/classes/class-clientroleoptions)。 ### 所属接口类 [#所属接口类-24] - [IRtcEngineEventHandler](/zh-CN/api-reference/rtc/android/full-sdk-api-list#class_irtcengineeventhandler) ## onClientRoleChangeFailed [#onclientrolechangefailed] 切换用户角色失败时的回调。 ```java public void onClientRoleChangeFailed(int reason, int currentRole) ``` 该回调用于通知切换用户角色失败的原因以及当前的用户角色。 ### 触发时机 [#触发时机-1] 该回调在本地用户加入频道后调用 [setClientRole [1/2]](/zh-CN/api-reference/rtc/android/channel#api_irtcengine_setclientrole1) 或 [setClientRole [2/2]](/zh-CN/api-reference/rtc/android/channel#api_irtcengine_setclientrole2) (带 [ClientRoleOptions](/zh-CN/api-reference/rtc/android/class-and-enum/classes/class-clientroleoptions) 参数)切换用户角色失败时被触发。 ### 参数 [#参数-24] #### `reason` [#reason] :::info[注] 仅在启用 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` [#currentrole] 当前的用户角色。 - CLIENT_ROLE_BROADCASTER (1):主播,可以发送和接收音视频流。 - CLIENT_ROLE_AUDIENCE (2):观众,只能接收音视频流。 ### 所属接口类 [#所属接口类-25] - [IRtcEngineEventHandler](/zh-CN/api-reference/rtc/android/full-sdk-api-list#class_irtcengineeventhandler) ## onError [#onerror] SDK 运行期间发生错误时触发的回调。 ```java public void onError(int err) ``` 该回调表示 SDK 运行期间发生了网络或媒体相关的错误。在大多数情况下,SDK 无法自动修复该问题并继续运行,需要你在应用层进行处理或通知用户。 ### 触发时机 [#触发时机-2] 该回调在 SDK 运行期间发生错误时被触发。 ### 参数 [#参数-25] #### `err` [#err] 错误码。详见[错误码](/zh-CN/realtime-media/rtc/reference/error-code)文档。 ### 所属接口类 [#所属接口类-26] - [IRtcEngineEventHandler](/zh-CN/api-reference/rtc/android/full-sdk-api-list#class_irtcengineeventhandler) ## onJoinChannelSuccess [#onjoinchannelsuccess] 本地用户成功加入频道回调。 ```java public void onJoinChannelSuccess(String channel, int uid, int elapsed) ``` ### 触发时机 [#触发时机-3] 该回调在你调用 `joinChannel`、 `joinChannelWithUserAccount`、 [joinChannelEx](/zh-CN/api-reference/rtc/android/channel#api_irtcengineex_joinchannelex) 或 [joinChannelWithUserAccountEx](/zh-CN/api-reference/rtc/android/channel#api_irtcengineex_joinchannelwithuseraccountex) 加入频道时被触发。 ### 参数 [#参数-26] #### `channel` [#channel] 频道名。 #### `uid` [#uid-4] 加入频道的用户 ID。 #### `elapsed` [#elapsed] 从本地用户调用 `joinChannel` 加入频道到 SDK 触发该回调的时间间隔,单位为毫秒。 ### 所属接口类 [#所属接口类-27] - [IRtcEngineEventHandler](/zh-CN/api-reference/rtc/android/full-sdk-api-list#class_irtcengineeventhandler) ## onLeaveChannel [#onleavechannel] 用户离开频道回调。 ```java public void onLeaveChannel(RtcStats stats) {} ``` ### 触发时机 [#触发时机-4] 该回调在你调用 [leaveChannel [1/2]](/zh-CN/api-reference/rtc/android/channel#api_irtcengine_leavechannel)、 [leaveChannel [2/2]](/zh-CN/api-reference/rtc/android/channel#api_irtcengine_leavechannel2)、 [leaveChannelEx [1/2]](/zh-CN/api-reference/rtc/android/channel#api_irtcengineex_leavechannelex) 或 [leaveChannelEx [2/2]](/zh-CN/api-reference/rtc/android/channel#api_irtcengineex_leavechannelex2) 离开频道后被触发。 ### 参数 [#参数-27] #### `stats` [#stats] 通话统计信息。详见 [RtcStats](/zh-CN/api-reference/rtc/android/class-and-enum/classes/class-rtcstats)。 ### 所属接口类 [#所属接口类-28] - [IRtcEngineEventHandler](/zh-CN/api-reference/rtc/android/full-sdk-api-list#class_irtcengineeventhandler) ## onLocalUserRegistered [#onlocaluserregistered] 本地用户注册用户 User Account 回调。 ```java public void onLocalUserRegistered(int uid, String userAccount) ``` #### `自从` [#自从-2] 自 v2.8.0 版本新增。 当本地用户成功调用 [registerLocalUserAccount](/zh-CN/api-reference/rtc/android/channel#api_irtcengine_registerlocaluseraccount) 方法注册用户 User Account,或调用 `joinChannelWithUserAccount` 方法加入频道后,SDK 会触发该回调,并返回本地用户的用户 ID 和用户 User Account。 ### 触发时机 [#触发时机-5] 该回调在本地用户成功注册用户 User Account 或加入频道后被触发。 ### 参数 [#参数-28] #### `uid` [#uid-5] 本地用户的用户 ID。 #### `userAccount` [#useraccount-7] 本地用户的用户 User Account。 ### 所属接口类 [#所属接口类-29] - [IRtcEngineEventHandler](/zh-CN/api-reference/rtc/android/full-sdk-api-list#class_irtcengineeventhandler) ## onRejoinChannelSuccess [#onrejoinchannelsuccess] 用户重新加入频道回调。 ```java public void onRejoinChannelSuccess(String channel, int uid, int elapsed) ``` 该回调在用户因网络问题与服务器断开连接后,SDK 自动尝试重连并成功重连时触发。 ### 触发时机 [#触发时机-6] 该回调在用户因网络问题与服务器断开连接后,SDK 自动尝试重连并成功重连时被触发。 ### 参数 [#参数-29] #### `channel` [#channel-1] 频道名。 #### `uid` [#uid-6] 重新加入频道的用户 ID。 #### `elapsed` [#elapsed-1] 从本地用户调用 `joinChannel` 到 SDK 触发该回调的时间间隔,单位为毫秒。 ### 所属接口类 [#所属接口类-30] - [IRtcEngineEventHandler](/zh-CN/api-reference/rtc/android/full-sdk-api-list#class_irtcengineeventhandler) ## onRenewTokenResult [#onrenewtokenresult] renewToken 调用结果回调。 ```java public void onRenewTokenResult(String token, Constants.RenewTokenErrorCode code) ``` #### `自从` [#自从-3] 自 v4.6.0 版本新增。 该回调在调用 [renewToken](/zh-CN/api-reference/rtc/android/channel#api_irtcengine_renewtoken) 方法后触发,用于通知更新结果。 ### 触发时机 [#触发时机-7] 该回调在你调用 [renewToken](/zh-CN/api-reference/rtc/android/channel#api_irtcengine_renewtoken) 方法后被触发。 ### 参数 [#参数-30] #### `token` [#token-10] 用于鉴权的 Token。 #### `code` [#code] 错误码。详见 [RenewTokenErrorCode](/zh-CN/api-reference/rtc/android/class-and-enum/enums/enum-renewtokenerrorcode)。 ### 所属接口类 [#所属接口类-31] - [IRtcEngineEventHandler](/zh-CN/api-reference/rtc/android/full-sdk-api-list#class_irtcengineeventhandler) ## onRequestToken [#onrequesttoken] Token 过期回调。 ```java public void onRequestToken() {} ``` 该回调在 Token 过期时被触发。收到该回调后,你需要在 Token 服务器上生成新的 Token,并通过以下方式之一更新 Token: - 单频道场景: - 调用 renewToken 更新 Token。 - 调用 leaveChannel 离开当前频道,然后在调用 joinChannel 加入频道时传入新的 Token。 - 多频道场景:调用 updateChannelMediaOptionsEx 传入新的 Token。 ### 触发时机 [#触发时机-8] 该回调在 Token 过期时被触发。 ### 所属接口类 [#所属接口类-32] - [IRtcEngineEventHandler](/zh-CN/api-reference/rtc/android/full-sdk-api-list#class_irtcengineeventhandler) ## onRtcStats [#onrtcstats] 报告当前通话统计信息的回调。 ```java public void onRtcStats(RtcStats stats) {} ``` ### 触发时机 [#触发时机-9] 该回调在用户加入频道后每两秒触发一次。 ### 参数 [#参数-31] #### `stats` [#stats-1] RTC 引擎的统计信息,详见 [RtcStats](/zh-CN/api-reference/rtc/android/class-and-enum/classes/class-rtcstats)。 ### 所属接口类 [#所属接口类-33] - [IRtcEngineEventHandler](/zh-CN/api-reference/rtc/android/full-sdk-api-list#class_irtcengineeventhandler) ## onTokenPrivilegeWillExpire [#ontokenprivilegewillexpire] Token 即将在 30 秒后过期时触发的回调。 ```java public void onTokenPrivilegeWillExpire(String token) ``` 收到该回调时,你需要在 Token 服务器上生成一个新的 Token,并通过以下方式之一更新 Token: - 单频道场景: - 调用 renewToken 传入新的 Token。 - 调用 leaveChannel 离开当前频道,然后在调用 joinChannel 加入频道时传入新的 Token。 - 多频道场景:调用 updateChannelMediaOptionsEx 传入新的 Token。 ### 触发时机 [#触发时机-10] 该回调在 Token 过期前 30 秒被触发。 ### 参数 [#参数-32] #### `token` [#token-11] 即将过期的 Token。 ### 所属接口类 [#所属接口类-34] - [IRtcEngineEventHandler](/zh-CN/api-reference/rtc/android/full-sdk-api-list#class_irtcengineeventhandler) ## onUserInfoUpdated [#onuserinfoupdated] 远端用户的用户 ID 和用户 User Account 信息更新回调。 ```java public void onUserInfoUpdated(int uid, UserInfo userInfo) {} ``` #### `自从` [#自从-4] 自 v2.8.0 版本新增。 当远端用户加入频道后,SDK 会获取该用户的用户 ID 和用户 User Account,并将其缓存在映射表中,然后在本地客户端触发该回调。 ### 触发时机 [#触发时机-11] 该回调在远端用户加入频道后,SDK 获取到其用户 ID 和用户 User Account 时被触发。 ### 参数 [#参数-33] #### `uid` [#uid-7] 远端用户的用户 ID。 #### `userInfo` [#userinfo-4] 包含远端用户的用户 ID 和用户 User Account 信息。详见 [UserInfo](/zh-CN/api-reference/rtc/android/class-and-enum/classes/class-userinfo)。 ### 所属接口类 [#所属接口类-35] - [IRtcEngineEventHandler](/zh-CN/api-reference/rtc/android/full-sdk-api-list#class_irtcengineeventhandler) ## onUserJoined [#onuserjoined] 远端用户或主播加入频道回调。 ```java public void onUserJoined(int uid, int elapsed) ``` 在通信频道中,该回调表示有远端用户加入频道。当本地用户加入频道时,SDK 也会触发该回调报告频道中已有的用户。在直播频道中,该回调表示有主播加入频道。声网建议将连麦主播数量限制为 32 人,最多支持 17 路视频主播。 ### 触发时机 [#触发时机-12] 该回调在以下任一情况下被触发: - 远端用户或主播加入频道。 - 远端用户加入频道后将用户角色切换为主播。 - 远端用户或主播在网络中断后重新加入频道。 ### 参数 [#参数-34] #### `uid` [#uid-8] 加入频道的用户 ID。 #### `elapsed` [#elapsed-2] 从本地用户调用 `joinChannel` 到该回调被触发的延迟(毫秒)。 ### 所属接口类 [#所属接口类-36] - [IRtcEngineEventHandler](/zh-CN/api-reference/rtc/android/full-sdk-api-list#class_irtcengineeventhandler) ## onUserOffline [#onuseroffline] 远端用户或主播离开频道时触发的回调。 ```java public void onUserOffline(int uid, int reason) ``` 用户离线通常有以下两种原因: - 离开频道:当用户或主播离开频道时,会发送一条离开消息。 - 掉线:在一段时间内(通信场景为 20 秒,直播场景更长)未收到用户或主播的数据包时,SDK 会认为其掉线。网络连接不佳可能导致误判,建议使用声网 RTM SDK 进行可靠的离线检测。 ### 触发时机 [#触发时机-13] 该回调在远端用户(在通信场景中)或主播(在直播场景中)离开频道时被触发。 ### 参数 [#参数-35] #### `uid` [#uid-9] 离开频道或掉线的用户 ID。 #### `reason` [#reason-1] 远端用户(在通信场景中)或主播(在直播场景中)离线的原因: - USER_OFFLINE_QUIT (0):用户主动退出通话,发送离开消息。 - USER_OFFLINE_DROPPED (1):SDK 超时未收到任何数据包,用户掉线。网络连接不佳可能导致误判,建议使用声网 RTM SDK 进行可靠的离线检测。 - USER_OFFLINE_BECOME_AUDIENCE (2):用户将角色从主播切换为观众。 ### 所属接口类 [#所属接口类-37] - [IRtcEngineEventHandler](/zh-CN/api-reference/rtc/android/full-sdk-api-list#class_irtcengineeventhandler)