# 频道相关 (/zh-CN/api-reference/rtc/unity/channel)
> For AI agents: see the complete documentation index at [llms.txt](/llms.txt).
## GetUserInfoByUid [#getuserinfobyuid]
通过 UID 获取用户信息。
```csharp
public abstract int GetUserInfoByUid(uint uid, ref UserInfo userInfo);
```
远端用户加入频道后,SDK 会获取到该远端用户的 UID 和 User Account,然后缓存一个包含了远端用户 UID 和 User Account 的映射表,并在本地触发 [OnUserInfoUpdated](/zh-CN/api-reference/rtc/unity/channel#callback_irtcengineeventhandler_onuserinfoupdated) 回调。收到回调后,调用该方法传入 UID 来获取包含了指定用户 User Account 的 [UserInfo](/zh-CN/api-reference/rtc/unity/class-userinfo) 对象。
### 调用时机 [#调用时机]
在收到 [OnUserInfoUpdated](/zh-CN/api-reference/rtc/unity/channel#callback_irtcengineeventhandler_onuserinfoupdated) 回调后调用。
### 相关回调 [#相关回调]
[OnUserInfoUpdated](/zh-CN/api-reference/rtc/unity/channel#callback_irtcengineeventhandler_onuserinfoupdated)
### 参数 [#参数]
用户 ID。
输入和输出参数。标识用户的 [UserInfo](/zh-CN/api-reference/rtc/unity/class-userinfo) 对象:
- 输入值:一个 [UserInfo](/zh-CN/api-reference/rtc/unity/class-userinfo) 对象。
- 输出值:一个包含了用户 User Account 和 UID 的 [UserInfo](/zh-CN/api-reference/rtc/unity/class-userinfo) 对象。
### 返回值 [#返回值]
- 0: 方法调用成功。
- < 0: 方法调用失败。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。
### 所属接口类 [#所属接口类]
- [IRtcEngine](/zh-CN/api-reference/rtc/unity/rtc-interface-class#class_irtcengine)
## GetUserInfoByUserAccount [#getuserinfobyuseraccount]
通过 User Account 获取用户信息。
```csharp
public abstract int GetUserInfoByUserAccount(string userAccount, ref UserInfo userInfo);
```
远端用户加入频道后,SDK 会获取到该远端用户的 UID 和 User Account,然后缓存一个包含了远端用户 UID 和 User Account 的映射表,并在本地触发 [OnUserInfoUpdated](/zh-CN/api-reference/rtc/unity/channel#callback_irtcengineeventhandler_onuserinfoupdated) 回调。收到回调后,调用该方法传入 User Account 来获取包含了指定用户 UID 的 [UserInfo](/zh-CN/api-reference/rtc/unity/class-userinfo) 对象。
### 调用时机 [#调用时机-1]
在收到 [OnUserInfoUpdated](/zh-CN/api-reference/rtc/unity/channel#callback_irtcengineeventhandler_onuserinfoupdated) 回调后调用。
### 相关回调 [#相关回调-1]
[OnUserInfoUpdated](/zh-CN/api-reference/rtc/unity/channel#callback_irtcengineeventhandler_onuserinfoupdated)
### 参数 [#参数-1]
用户 User Account。
输入和输出参数。标识用户的 [UserInfo](/zh-CN/api-reference/rtc/unity/class-userinfo) 对象:
- 输入值:一个 [UserInfo](/zh-CN/api-reference/rtc/unity/class-userinfo) 对象。
- 输出值:一个包含了用户 User Account 和 UID 的 [UserInfo](/zh-CN/api-reference/rtc/unity/class-userinfo) 对象。
### 返回值 [#返回值-1]
- 0: 方法调用成功。
- < 0: 方法调用失败。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。
### 所属接口类 [#所属接口类-1]
- [IRtcEngine](/zh-CN/api-reference/rtc/unity/rtc-interface-class#class_irtcengine)
## JoinChannel [1/2] [#joinchannel-12]
加入频道。
```csharp
public abstract int JoinChannel(string token, string channelId, string info = "", uint uid = 0);
```
加入频道后,默认情况下用户订阅频道内所有其他用户的音频流和视频流,因此会产生用量并影响计费。如果想取消订阅,可以通过相应的 mute 方法实现。
:::note
注:
- 该方法仅支持用户一次加入一个频道。
- 使用不同 App ID 的 App 不能互通。
- 加入频道前,请确保用于生成 Token 的 App ID 和调用 [Initialize](/zh-CN/api-reference/rtc/unity/initialize#api_irtcengine_initialize) 方法初始化引擎时使用的是同一个 App ID,否则使用 Token 加入频道会失败。
:::
### 调用时机 [#调用时机-2]
该方法需要在 [Initialize](/zh-CN/api-reference/rtc/unity/initialize#api_irtcengine_initialize) 之后再调用。
### 相关回调 [#相关回调-2]
成功调用该方法加入频道后会触发以下回调:
- 本地会触发 [OnJoinChannelSuccess](/zh-CN/api-reference/rtc/unity/channel#callback_irtcengineeventhandler_onjoinchannelsuccess) 和 [OnConnectionStateChanged](/zh-CN/api-reference/rtc/unity/network#callback_irtcengineeventhandler_onconnectionstatechanged) 回调。
- 通信场景下的用户和直播场景下的主播加入频道后,远端会触发 [OnUserJoined](/zh-CN/api-reference/rtc/unity/channel#callback_irtcengineeventhandler_onuserjoined) 回调。
在网络状况不理想的情况下,客户端可能会与声网服务器失去连接,此时 SDK 会自动尝试重连,重连成功后,本地会触发 [OnRejoinChannelSuccess](/zh-CN/api-reference/rtc/unity/channel#callback_irtcengineeventhandler_onrejoinchannelsuccess) 回调。
### 参数 [#参数-2]
在服务端生成的用于鉴权的动态密钥。详见[使用 Token 鉴权](/zh-CN/realtime-media/rtc/build/setup-and-access/token-authentication)。
:::note
注:
- (推荐)如果你的项目开启了安全模式,即选择 APP ID + Token 为鉴权机制,则该参数为必填。
- 如果你的项目仅开启调试模式,即选择 APP ID 为鉴权机制,则无需填入 Token 即可加入频道。成功加入频道 24 小时后会自动退出该频道。
- 如果你需要同时加入多个频道或在频道间频繁切换,声网推荐你使用通配 Token 以避免每加入一个新的频道都需向服务端申请一个新的 Token,详见 [使用通配 Token](/zh-CN/realtime-media/rtc/build/security-and-auth/wildcard-token)。
:::
频道名。该参数标识用户进行实时音视频互动的频道。App ID 一致的前提下,填入相同频道名的用户会进入同一个频道进行音视频互动。该参数为长度在 64 字节以内的字符串。以下为支持的字符集范围(共 89 个字符):
- 26 个小写英文字母 a~z
- 26 个大写英文字母 A~Z
- 10 个数字 0~9
- "!"、"#"、"$"、"%"、"&"、"("、")"、"+"、"-"、":"、";"、"<"、"="、"."、">"、"?"、"@"、"["、"]"、"^"、"_"、"\{"、"\}"、"|"、"~"、","
(非必选项) 预留参数。
用户 ID。该参数用于标识在实时音视频互动频道中的用户。你需要自行设置和管理用户 ID,并确保同一频道内的每个用户 ID 是唯一的。该参数为 32 位无符号整数。建议设置范围:1 到 2³² - 1。如果不指定(即设为 0),SDK 会自动分配一个,并在 [OnJoinChannelSuccess](/zh-CN/api-reference/rtc/unity/channel#callback_irtcengineeventhandler_onjoinchannelsuccess) 回调中返回, 应用层必须记住该返回值并维护,SDK 不对该返回值进行维护。
### 返回值 [#返回值-2]
- 0:方法调用成功。
- < 0:方法调用失败。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。
- -2:传入的参数无效。例如,使用了不合法的 Token,`uid` 参数未设置为整型,或 [ChannelMediaOptions](/zh-CN/api-reference/rtc/unity/class-channelmediaoptions) 成员值不合法。你需要填入有效的参数,重新加入频道。
- -3:[IRtcEngine](/zh-CN/api-reference/rtc/unity/rtc-interface-class#class_irtcengine) 对象初始化失败。你需要重新初始化 [IRtcEngine](/zh-CN/api-reference/rtc/unity/rtc-interface-class#class_irtcengine) 对象。
- -7:[IRtcEngine](/zh-CN/api-reference/rtc/unity/rtc-interface-class#class_irtcengine) 对象尚未初始化。你需要在调用该方法前成功初始化 [IRtcEngine](/zh-CN/api-reference/rtc/unity/rtc-interface-class#class_irtcengine) 对象。
- -8:[IRtcEngine](/zh-CN/api-reference/rtc/unity/rtc-interface-class#class_irtcengine) 对象内部状态错误。可能的原因是:调用 [StartEchoTest](/zh-CN/api-reference/rtc/unity/network#api_irtcengine_startechotest3) 开始通话回路测试后,未调用 [StopEchoTest](/zh-CN/api-reference/rtc/unity/network#api_irtcengine_stopechotest) 停止测试就调用该方法加入频道。你需要在该方法前调用 [StopEchoTest](/zh-CN/api-reference/rtc/unity/network#api_irtcengine_stopechotest)。
- -17:加入频道被拒绝。可能的原因是用户已经在频道中。建议通过 [OnConnectionStateChanged](/zh-CN/api-reference/rtc/unity/network#callback_irtcengineeventhandler_onconnectionstatechanged) 回调判断用户是否在频道中。除收到 `CONNECTION_STATE_DISCONNECTED`(1) 状态外,不要再次调用该方法加入频道。
- -102:频道名无效。你需要在 `channelId` 中填入有效的频道名,重新加入频道。
- -121:用户 ID 无效。你需要在 `uid` 中填入有效的用户 ID,重新加入频道。
### 所属接口类 [#所属接口类-2]
- [IRtcEngine](/zh-CN/api-reference/rtc/unity/rtc-interface-class#class_irtcengine)
## JoinChannel [2/2] [#joinchannel-22]
设置媒体选项并加入频道。
```csharp
public abstract int JoinChannel(string token, string channelId, uint uid,
ChannelMediaOptions options);
```
相比 [JoinChannel [1/2]](/zh-CN/api-reference/rtc/unity/channel#api_irtcengine_joinchannel1),该方法增加了 `options` 参数,用于设置媒体选项,如是否在频道内发布音视频流等。用户加入频道时是否自动订阅频道内所有远端音视频流。默认情况下,用户订阅频道内所有其他用户的音频流和视频流,因此会产生用量并影响计费。如果想取消订阅,可以通过设置 `options` 参数或相应的 mute 方法实现。
:::note
注:
- 该方法仅支持用户一次加入一个频道。
- 使用不同 App ID 的 App 不能互通。
- 加入频道前,请确保用于生成 Token 的 App ID 和调用 [Initialize](/zh-CN/api-reference/rtc/unity/initialize#api_irtcengine_initialize) 方法初始化引擎时使用的是同一个 App ID,否则使用 Token 加入频道会失败。
:::
### 调用时机 [#调用时机-3]
该方法需要在 [Initialize](/zh-CN/api-reference/rtc/unity/initialize#api_irtcengine_initialize) 之后再调用。
### 相关回调 [#相关回调-3]
成功调用该方法加入频道后会触发以下回调:
- 本地会触发 [OnJoinChannelSuccess](/zh-CN/api-reference/rtc/unity/channel#callback_irtcengineeventhandler_onjoinchannelsuccess) 和 [OnConnectionStateChanged](/zh-CN/api-reference/rtc/unity/network#callback_irtcengineeventhandler_onconnectionstatechanged) 回调。
- 通信场景下的用户和直播场景下的主播加入频道后,远端会触发 [OnUserJoined](/zh-CN/api-reference/rtc/unity/channel#callback_irtcengineeventhandler_onuserjoined) 回调。
在网络状况不理想的情况下,客户端可能会与声网服务器失去连接,此时 SDK 会自动尝试重连,重连成功后,本地会触发 [OnRejoinChannelSuccess](/zh-CN/api-reference/rtc/unity/channel#callback_irtcengineeventhandler_onrejoinchannelsuccess) 回调。
### 参数 [#参数-3]
在服务端生成的用于鉴权的动态密钥。详见[使用 Token 鉴权](/zh-CN/realtime-media/rtc/build/setup-and-access/token-authentication)。
:::note
注:
- (推荐)如果你的项目开启了安全模式,即选择 APP ID + Token 为鉴权机制,则该参数为必填。
- 如果你的项目仅开启调试模式,即选择 APP ID 为鉴权机制,则无需填入 Token 即可加入频道。成功加入频道 24 小时后会自动退出该频道。
- 如果你需要同时加入多个频道或在频道间频繁切换,声网推荐你使用通配 Token 以避免每加入一个新的频道都需向服务端申请一个新的 Token,详见 [使用通配 Token](/zh-CN/realtime-media/rtc/build/security-and-auth/wildcard-token)。
:::
频道名。该参数标识用户进行实时音视频互动的频道。App ID 一致的前提下,填入相同频道名的用户会进入同一个频道进行音视频互动。该参数为长度在 64 字节以内的字符串。以下为支持的字符集范围(共 89 个字符):
- 26 个小写英文字母 a~z
- 26 个大写英文字母 A~Z
- 10 个数字 0~9
- "!"、"#"、"$"、"%"、"&"、"("、")"、"+"、"-"、":"、";"、"<"、"="、"."、">"、"?"、"@"、"["、"]"、"^"、"_"、"\{"、"\}"、"|"、"~"、","
用户 ID。该参数用于标识在实时音视频互动频道中的用户。你需要自行设置和管理用户 ID,并确保同一频道内的每个用户 ID 是唯一的。该参数为 32 位无符号整数。建议设置范围:1 到 2³² - 1。如果不指定(即设为 0),SDK 会自动分配一个,并在 [OnJoinChannelSuccess](/zh-CN/api-reference/rtc/unity/channel#callback_irtcengineeventhandler_onjoinchannelsuccess) 回调中返回, 应用层必须记住该返回值并维护,SDK 不对该返回值进行维护。
频道媒体设置选项。详见 [ChannelMediaOptions](/zh-CN/api-reference/rtc/unity/class-channelmediaoptions)。
### 返回值 [#返回值-3]
- 0:方法调用成功。
- < 0:方法调用失败。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。
- -2:传入的参数无效。例如,使用了不合法的 Token,`uid` 参数未设置为整型,或 [ChannelMediaOptions](/zh-CN/api-reference/rtc/unity/class-channelmediaoptions) 成员值不合法。你需要填入有效的参数,重新加入频道。
- -3:[IRtcEngine](/zh-CN/api-reference/rtc/unity/rtc-interface-class#class_irtcengine) 对象初始化失败。你需要重新初始化 [IRtcEngine](/zh-CN/api-reference/rtc/unity/rtc-interface-class#class_irtcengine) 对象。
- -7:[IRtcEngine](/zh-CN/api-reference/rtc/unity/rtc-interface-class#class_irtcengine) 对象尚未初始化。你需要在调用该方法前成功初始化 [IRtcEngine](/zh-CN/api-reference/rtc/unity/rtc-interface-class#class_irtcengine) 对象。
- -8:[IRtcEngine](/zh-CN/api-reference/rtc/unity/rtc-interface-class#class_irtcengine) 对象内部状态错误。可能的原因是:调用 [StartEchoTest](/zh-CN/api-reference/rtc/unity/network#api_irtcengine_startechotest3) 开始通话回路测试后,未调用 [StopEchoTest](/zh-CN/api-reference/rtc/unity/network#api_irtcengine_stopechotest) 停止测试就调用该方法加入频道。你需要在该方法前调用 [StopEchoTest](/zh-CN/api-reference/rtc/unity/network#api_irtcengine_stopechotest)。
- -17:加入频道被拒绝。可能的原因是用户已经在频道中。建议通过 [OnConnectionStateChanged](/zh-CN/api-reference/rtc/unity/network#callback_irtcengineeventhandler_onconnectionstatechanged) 回调判断用户是否在频道中。除收到 `CONNECTION_STATE_DISCONNECTED`(1) 状态外,不要再次调用该方法加入频道。
- -102:频道名无效。你需要在 `channelId` 中填入有效的频道名,重新加入频道。
- -121:用户 ID 无效。你需要在 `uid` 中填入有效的用户 ID,重新加入频道。
### 所属接口类 [#所属接口类-3]
- [IRtcEngine](/zh-CN/api-reference/rtc/unity/rtc-interface-class#class_irtcengine)
## JoinChannelEx [#joinchannelex]
加入频道。
```csharp
public abstract int JoinChannelEx(string token, RtcConnection connection, ChannelMediaOptions options);
```
调用该方法,你可以同时加入多个频道。如果你想在不同的设备上加入相同的频道,请确保你在不同设备上使用的用户 ID 都不同。
:::note
注: 如果你已经在一个频道内,你不能用相同的用户 ID 再次加入该频道。
加入频道前,请确保用于生成 Token 的 App ID 和调用 [Initialize](/zh-CN/api-reference/rtc/unity/initialize#api_irtcengine_initialize) 方法初始化引擎时使用的是同一个 App ID,否则使用 Token 加入频道会失败。
:::
### 适用场景 [#适用场景]
该方法适用于多频道场景。
### 调用时机 [#调用时机-4]
该方法需要在 [Initialize](/zh-CN/api-reference/rtc/unity/initialize#api_irtcengine_initialize) 之后调用。
在多摄像头采集场景下,你需要在调用该方法之后调用 [StartPreview [2/2]](/zh-CN/api-reference/rtc/unity/video/video-basic#api_irtcengine_startpreview2) 方法设置 `sourceType` 为 `VIDEO_SOURCE_CAMERA_SECONDARY`,以确保第二个摄像头采集正常。
### 相关回调 [#相关回调-4]
成功调用该方法加入频道后会触发以下回调:
- 本地会触发 [OnJoinChannelSuccess](/zh-CN/api-reference/rtc/unity/channel#callback_irtcengineeventhandler_onjoinchannelsuccess) 和 [OnConnectionStateChanged](/zh-CN/api-reference/rtc/unity/network#callback_irtcengineeventhandler_onconnectionstatechanged) 回调。
- 通信场景下的用户和直播场景下的主播加入频道后,远端会触发 [OnUserJoined](/zh-CN/api-reference/rtc/unity/channel#callback_irtcengineeventhandler_onuserjoined) 回调。
在网络状况不理想的情况下,客户端可能会与声网服务器失去连接,此时 SDK 会自动尝试重连,重连成功后,本地会触发 [OnRejoinChannelSuccess](/zh-CN/api-reference/rtc/unity/channel#callback_irtcengineeventhandler_onrejoinchannelsuccess) 回调。
### 参数 [#参数-4]
在服务端生成的用于鉴权的动态密钥。详见[使用 Token 鉴权](/zh-CN/realtime-media/rtc/build/setup-and-access/token-authentication)。
:::note
注:
- (推荐)如果你的项目开启了安全模式,即选择 APP ID + Token 为鉴权机制,则该参数为必填。
- 如果你的项目仅开启调试模式,即选择 APP ID 为鉴权机制,则无需填入 Token 即可加入频道。成功加入频道 24 小时后会自动退出该频道。
- 如果你需要同时加入多个频道或在频道间频繁切换,声网推荐你使用通配 Token 以避免每加入一个新的频道都需向服务端申请一个新的 Token,详见 [使用通配 Token](/zh-CN/realtime-media/rtc/build/security-and-auth/wildcard-token)。
:::
Connection 信息。详见 [RtcConnection](/zh-CN/api-reference/rtc/unity/class-rtcconnection)。
频道媒体设置选项。详见 [ChannelMediaOptions](/zh-CN/api-reference/rtc/unity/class-channelmediaoptions)。
### 返回值 [#返回值-4]
- 0:方法调用成功。
- < 0:方法调用失败。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。
- -2:传入的参数无效。例如,使用了不合法的 Token,`uid` 参数未设置为整型,或 [ChannelMediaOptions](/zh-CN/api-reference/rtc/unity/class-channelmediaoptions) 成员值不合法。你需要填入有效的参数,重新加入频道。
- -3:[IRtcEngine](/zh-CN/api-reference/rtc/unity/rtc-interface-class#class_irtcengine) 对象初始化失败。你需要重新初始化 [IRtcEngine](/zh-CN/api-reference/rtc/unity/rtc-interface-class#class_irtcengine) 对象。
- -7:[IRtcEngine](/zh-CN/api-reference/rtc/unity/rtc-interface-class#class_irtcengine) 对象尚未初始化。你需要在调用该方法前成功初始化 [IRtcEngine](/zh-CN/api-reference/rtc/unity/rtc-interface-class#class_irtcengine) 对象。
- -8:[IRtcEngine](/zh-CN/api-reference/rtc/unity/rtc-interface-class#class_irtcengine) 对象内部状态错误。可能的原因是:调用 [StartEchoTest](/zh-CN/api-reference/rtc/unity/network#api_irtcengine_startechotest3) 开始通话回路测试后,未调用 [StopEchoTest](/zh-CN/api-reference/rtc/unity/network#api_irtcengine_stopechotest) 停止测试就调用该方法加入频道。你需要在该方法前调用 [StopEchoTest](/zh-CN/api-reference/rtc/unity/network#api_irtcengine_stopechotest)。
- -17:加入频道被拒绝。可能的原因是用户已经在频道中。建议通过 [OnConnectionStateChanged](/zh-CN/api-reference/rtc/unity/network#callback_irtcengineeventhandler_onconnectionstatechanged) 回调判断用户是否在频道中。除收到 `CONNECTION_STATE_DISCONNECTED`(1) 状态外,不要再次调用该方法加入频道。
- -102:频道名无效。你需要在 `channelId` 中填入有效的频道名,重新加入频道。
- -121:用户 ID 无效。你需要在 `uid` 中填入有效的用户 ID,重新加入频道。
### 所属接口类 [#所属接口类-4]
- [IRtcEngineEx](/zh-CN/api-reference/rtc/unity/rtc-interface-class#class_irtcengineex)
## JoinChannelWithUserAccount [1/2] [#joinchannelwithuseraccount-12]
使用 User Account 和 Token 加入频道。
```csharp
public abstract int JoinChannelWithUserAccount(string token, string channelId, string userAccount);
```
调用该方法前,如果你未调用 [RegisterLocalUserAccount](/zh-CN/api-reference/rtc/unity/channel#api_irtcengine_registerlocaluseraccount) 注册一个 User Account,调用该方法加入频道时,SDK 会自动为你创建一个 User Account。先调用 [RegisterLocalUserAccount](/zh-CN/api-reference/rtc/unity/channel#api_irtcengine_registerlocaluseraccount) 方法注册 Account,再调用此方法加入频道,可以缩短进入频道的时间。
用户成功加入频道后,默认订阅频道内所有其他用户的音频流和视频流,因此产生用量并影响计费。如果想取消订阅,可以通过调用相应的 mute 方法实现。
:::note
注: 为保证通信质量,请确保频道内使用同一类型的数据标识用户身份。即同一频道内需要统一使用 UID 或 User Account。如果有用户通过 Web SDK 加入频道,请确保 Web 加入的用户也是同样类型。
- 该方法仅支持用户一次加入一个频道。
- 使用不同 App ID 的 App 不能互通。
- 加入频道前,请确保用于生成 Token 的 App ID 和调用 [Initialize](/zh-CN/api-reference/rtc/unity/initialize#api_irtcengine_initialize) 方法初始化引擎时使用的是同一个 App ID,否则使用 Token 加入频道会失败。
:::
### 调用时机 [#调用时机-5]
该方法需要在 [Initialize](/zh-CN/api-reference/rtc/unity/initialize#api_irtcengine_initialize) 之后再调用。
### 相关回调 [#相关回调-5]
成功加入频道后,会触发以下回调:
- 本地:[OnLocalUserRegistered](/zh-CN/api-reference/rtc/unity/channel#callback_irtcengineeventhandler_onlocaluserregistered)、[OnJoinChannelSuccess](/zh-CN/api-reference/rtc/unity/channel#callback_irtcengineeventhandler_onjoinchannelsuccess) 和 [OnConnectionStateChanged](/zh-CN/api-reference/rtc/unity/network#callback_irtcengineeventhandler_onconnectionstatechanged) 回调。
- 远端:通信场景下的用户和直播场景下的主播加入频道后,远端会分别触发 [OnUserJoined](/zh-CN/api-reference/rtc/unity/channel#callback_irtcengineeventhandler_onuserjoined) 和 [OnUserInfoUpdated](/zh-CN/api-reference/rtc/unity/channel#callback_irtcengineeventhandler_onuserinfoupdated) 回调。
### 参数 [#参数-5]
在服务端生成的用于鉴权的动态密钥。详见[使用 Token 鉴权](/zh-CN/realtime-media/rtc/build/setup-and-access/token-authentication)。
:::note
注:
- (推荐)如果你的项目开启了安全模式,即选择 APP ID + Token 为鉴权机制,则该参数为必填。
- 如果你的项目仅开启调试模式,即选择 APP ID 为鉴权机制,则无需填入 Token 即可加入频道。成功加入频道 24 小时后会自动退出该频道。
- 如果你需要同时加入多个频道或在频道间频繁切换,声网推荐你使用通配 Token 以避免每加入一个新的频道都需向服务端申请一个新的 Token,详见 [使用通配 Token](/zh-CN/realtime-media/rtc/build/security-and-auth/wildcard-token)。
:::
用户 User Account。该参数用于标识实时音视频互动频道中的用户。你需要自行设置和管理用户的 User Account,并确保同一频道中每个用户的 User Account 是唯一的。 该参数为必填,最大不超过 255 字节,不可填 `null`。以下为支持的字符集范围(共 89 个字符):
- 26 个小写英文字母 a-z
- 26 个大写英文字母 A-Z
- 10 个数字 0-9
- 空格
- "!"、"#"、"$"、"%"、"&"、"("、")"、"+"、"-"、":"、";"、"<"、"="、"."、">"、"?"、"@"、"["、"]"、"^"、"_"、"\{"、"\}"、"|"、"~"、","
### 返回值 [#返回值-5]
- 0:方法调用成功。
- < 0:方法调用失败。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。
- -2:传入的参数无效。例如,使用了不合法的 Token,`uid` 参数未设置为整型,或 [ChannelMediaOptions](/zh-CN/api-reference/rtc/unity/class-channelmediaoptions) 成员值不合法。你需要填入有效的参数,重新加入频道。
- -3:[IRtcEngine](/zh-CN/api-reference/rtc/unity/rtc-interface-class#class_irtcengine) 对象初始化失败。你需要重新初始化 [IRtcEngine](/zh-CN/api-reference/rtc/unity/rtc-interface-class#class_irtcengine) 对象。
- -7:[IRtcEngine](/zh-CN/api-reference/rtc/unity/rtc-interface-class#class_irtcengine) 对象尚未初始化。你需要在调用该方法前成功初始化 [IRtcEngine](/zh-CN/api-reference/rtc/unity/rtc-interface-class#class_irtcengine) 对象。
- -8:[IRtcEngine](/zh-CN/api-reference/rtc/unity/rtc-interface-class#class_irtcengine) 对象内部状态错误。可能的原因是:调用 [StartEchoTest](/zh-CN/api-reference/rtc/unity/network#api_irtcengine_startechotest3) 开始通话回路测试后,未调用 [StopEchoTest](/zh-CN/api-reference/rtc/unity/network#api_irtcengine_stopechotest) 停止测试就调用该方法加入频道。你需要在该方法前调用 [StopEchoTest](/zh-CN/api-reference/rtc/unity/network#api_irtcengine_stopechotest)。
- -17:加入频道被拒绝。可能的原因是用户已经在频道中。建议通过 [OnConnectionStateChanged](/zh-CN/api-reference/rtc/unity/network#callback_irtcengineeventhandler_onconnectionstatechanged) 回调判断用户是否在频道中。除收到 `CONNECTION_STATE_DISCONNECTED`(1) 状态外,不要再次调用该方法加入频道。
- -102:频道名无效。你需要在 `channelId` 中填入有效的频道名,重新加入频道。
- -121:用户 ID 无效。你需要在 `uid` 中填入有效的用户 ID,重新加入频道。
### 所属接口类 [#所属接口类-5]
- [IRtcEngine](/zh-CN/api-reference/rtc/unity/rtc-interface-class#class_irtcengine)
## JoinChannelWithUserAccount [2/2] [#joinchannelwithuseraccount-22]
使用 User Account 和 Token 加入频道,并设置频道媒体选项。
```csharp
public abstract int JoinChannelWithUserAccount(string token, string channelId, string userAccount,
ChannelMediaOptions options);
```
调用该方法前,如果你未调用 [RegisterLocalUserAccount](/zh-CN/api-reference/rtc/unity/channel#api_irtcengine_registerlocaluseraccount) 注册一个 User Account,调用该方法加入频道时,SDK 会自动为你创建一个 User Account。先调用 [RegisterLocalUserAccount](/zh-CN/api-reference/rtc/unity/channel#api_irtcengine_registerlocaluseraccount) 方法注册 Account,再调用此方法加入频道,可以缩短进入频道的时间。
相比 [JoinChannelWithUserAccount [1/2]](/zh-CN/api-reference/rtc/unity/channel#api_irtcengine_joinchannelwithuseraccount1),该方法增加了 `options` 参数,用于在加入频道时设置媒体选项,如是否在频道内发布音视频流等。默认情况下,用户订阅频道内所有其他用户的音频流和视频流,因此会产生用量并影响计费。如果想取消订阅,可以通过设置 `options` 参数或相应的 mute 方法实现。
:::note
注: 为保证通信质量,请确保频道内使用同一类型的数据标识用户身份。即同一频道内需要统一使用 UID 或 User Account。如果有用户通过 Web SDK 加入频道,请确保 Web 加入的用户也是同样类型。
- 该方法仅支持用户一次加入一个频道。
- 使用不同 App ID 的 App 不能互通。
- 加入频道前,请确保用于生成 Token 的 App ID 和调用 [Initialize](/zh-CN/api-reference/rtc/unity/initialize#api_irtcengine_initialize) 方法初始化引擎时使用的是同一个 App ID,否则使用 Token 加入频道会失败。
:::
### 调用时机 [#调用时机-6]
该方法需要在 [Initialize](/zh-CN/api-reference/rtc/unity/initialize#api_irtcengine_initialize) 之后再调用。
### 相关回调 [#相关回调-6]
成功加入频道后,会触发以下回调:
- 本地:[OnLocalUserRegistered](/zh-CN/api-reference/rtc/unity/channel#callback_irtcengineeventhandler_onlocaluserregistered)、[OnJoinChannelSuccess](/zh-CN/api-reference/rtc/unity/channel#callback_irtcengineeventhandler_onjoinchannelsuccess) 和 [OnConnectionStateChanged](/zh-CN/api-reference/rtc/unity/network#callback_irtcengineeventhandler_onconnectionstatechanged) 回调。
- 远端:通信场景下的用户和直播场景下的主播加入频道后,远端会分别触发 [OnUserJoined](/zh-CN/api-reference/rtc/unity/channel#callback_irtcengineeventhandler_onuserjoined) 和 [OnUserInfoUpdated](/zh-CN/api-reference/rtc/unity/channel#callback_irtcengineeventhandler_onuserinfoupdated) 回调。
### 参数 [#参数-6]
在服务端生成的用于鉴权的动态密钥。详见[使用 Token 鉴权](/zh-CN/realtime-media/rtc/build/setup-and-access/token-authentication)。
:::note
注:
- (推荐)如果你的项目开启了安全模式,即选择 APP ID + Token 为鉴权机制,则该参数为必填。
- 如果你的项目仅开启调试模式,即选择 APP ID 为鉴权机制,则无需填入 Token 即可加入频道。成功加入频道 24 小时后会自动退出该频道。
- 如果你需要同时加入多个频道或在频道间频繁切换,声网推荐你使用通配 Token 以避免每加入一个新的频道都需向服务端申请一个新的 Token,详见 [使用通配 Token](/zh-CN/realtime-media/rtc/build/security-and-auth/wildcard-token)。
:::
用户 User Account。该参数用于标识实时音视频互动频道中的用户。你需要自行设置和管理用户的 User Account,并确保同一频道中每个用户的 User Account 是唯一的。 该参数为必填,最大不超过 255 字节,不可填 `null`。以下为支持的字符集范围(共 89 个字符):
- 26 个小写英文字母 a-z
- 26 个大写英文字母 A-Z
- 10 个数字 0-9
- 空格
- "!"、"#"、"$"、"%"、"&"、"("、")"、"+"、"-"、":"、";"、"<"、"="、"."、">"、"?"、"@"、"["、"]"、"^"、"_"、"\{"、"\}"、"|"、"~"、","
频道媒体设置选项。详见 [ChannelMediaOptions](/zh-CN/api-reference/rtc/unity/class-channelmediaoptions)。
### 返回值 [#返回值-6]
- 0:方法调用成功。
- < 0:方法调用失败。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。
- -2:传入的参数无效。例如,使用了不合法的 Token,`uid` 参数未设置为整型,或 [ChannelMediaOptions](/zh-CN/api-reference/rtc/unity/class-channelmediaoptions) 成员值不合法。你需要填入有效的参数,重新加入频道。
- -3:[IRtcEngine](/zh-CN/api-reference/rtc/unity/rtc-interface-class#class_irtcengine) 对象初始化失败。你需要重新初始化 [IRtcEngine](/zh-CN/api-reference/rtc/unity/rtc-interface-class#class_irtcengine) 对象。
- -7:[IRtcEngine](/zh-CN/api-reference/rtc/unity/rtc-interface-class#class_irtcengine) 对象尚未初始化。你需要在调用该方法前成功初始化 [IRtcEngine](/zh-CN/api-reference/rtc/unity/rtc-interface-class#class_irtcengine) 对象。
- -8:[IRtcEngine](/zh-CN/api-reference/rtc/unity/rtc-interface-class#class_irtcengine) 对象内部状态错误。可能的原因是:调用 [StartEchoTest](/zh-CN/api-reference/rtc/unity/network#api_irtcengine_startechotest3) 开始通话回路测试后,未调用 [StopEchoTest](/zh-CN/api-reference/rtc/unity/network#api_irtcengine_stopechotest) 停止测试就调用该方法加入频道。你需要在该方法前调用 [StopEchoTest](/zh-CN/api-reference/rtc/unity/network#api_irtcengine_stopechotest)。
- -17:加入频道被拒绝。可能的原因是用户已经在频道中。建议通过 [OnConnectionStateChanged](/zh-CN/api-reference/rtc/unity/network#callback_irtcengineeventhandler_onconnectionstatechanged) 回调判断用户是否在频道中。除收到 `CONNECTION_STATE_DISCONNECTED`(1) 状态外,不要再次调用该方法加入频道。
- -102:频道名无效。你需要在 `channelId` 中填入有效的频道名,重新加入频道。
- -121:用户 ID 无效。你需要在 `uid` 中填入有效的用户 ID,重新加入频道。
### 所属接口类 [#所属接口类-6]
- [IRtcEngine](/zh-CN/api-reference/rtc/unity/rtc-interface-class#class_irtcengine)
## LeaveChannel [1/2] [#leavechannel-12]
离开频道。
```csharp
public abstract int LeaveChannel();
```
调用该方法后,SDK 会终止音视频互动、离开当前频道,并会释放会话相关的所有资源。
成功加入频道后,必须调用本方法结束通话,否则无法开始下一次通话。
:::note
注:
- 该方法是异步操作,调用返回时并没有真正退出频道。
- 如果你已调用 [JoinChannelEx](/zh-CN/api-reference/rtc/unity/channel#api_irtcengineex_joinchannelex) 加入多个频道,调用本方法后会同时离开所有已加入的频道。
如果你调用了该方法后立即调用 [Dispose](/zh-CN/api-reference/rtc/unity/initialize#api_irtcengine_release) 方法,SDK 将不会触发 [OnLeaveChannel](/zh-CN/api-reference/rtc/unity/channel#callback_irtcengineeventhandler_onleavechannel) 回调。
:::
### 调用时机 [#调用时机-7]
该方法需要在加入频道后调用。
### 相关回调 [#相关回调-7]
成功调用该方法离开频道后会触发以下回调:
- 本地:[OnLeaveChannel](/zh-CN/api-reference/rtc/unity/channel#callback_irtcengineeventhandler_onleavechannel) 回调。
- 远端:主播离开频道后,远端会触发 [OnUserOffline](/zh-CN/api-reference/rtc/unity/channel#callback_irtcengineeventhandler_onuseroffline) 回调。
### 参数 [#参数-7]
成功离开频道的回调,提供通话相关的统计信息,详见 [RtcStats](/zh-CN/api-reference/rtc/unity/class-rtcstats)。
### 返回值 [#返回值-7]
- 0(ERR_OK): 方法调用成功。
- < 0: 方法调用失败。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。
- -1: 一般性的错误(未明确归类)。
- -2: 参数无效。
- -7: SDK 尚未初始化。
### 所属接口类 [#所属接口类-7]
- [IRtcEngine](/zh-CN/api-reference/rtc/unity/rtc-interface-class#class_irtcengine)
## LeaveChannel [2/2] [#leavechannel-22]
设置频道选项并离开频道。
```csharp
public abstract int LeaveChannel(LeaveChannelOptions options);
```
调用该方法后,SDK 会终止音视频互动、离开当前频道,并会释放会话相关的所有资源。
成功加入频道后,必须调用本方法或者 [LeaveChannel [1/2]](/zh-CN/api-reference/rtc/unity/channel#api_irtcengine_leavechannel) 结束通话,否则无法开始下一次通话。如果你已调用 [JoinChannelEx](/zh-CN/api-reference/rtc/unity/channel#api_irtcengineex_joinchannelex) 加入多个频道,调用本方法后会同时离开所有已加入的频道。
:::note
注: 该方法是异步操作,调用返回时并没有真正退出频道。
如果你调用了该方法后立即调用 [Dispose](/zh-CN/api-reference/rtc/unity/initialize#api_irtcengine_release) 方法,SDK 将不会触发 [OnLeaveChannel](/zh-CN/api-reference/rtc/unity/channel#callback_irtcengineeventhandler_onleavechannel) 回调。
:::
### 调用时机 [#调用时机-8]
该方法需要在加入频道后调用。
### 相关回调 [#相关回调-8]
成功调用该方法离开频道后会触发以下回调:
- 本地:[OnLeaveChannel](/zh-CN/api-reference/rtc/unity/channel#callback_irtcengineeventhandler_onleavechannel) 回调。
- 远端:主播离开频道后,远端会触发 [OnUserOffline](/zh-CN/api-reference/rtc/unity/channel#callback_irtcengineeventhandler_onuseroffline) 回调。
### 参数 [#参数-8]
离开频道的选项,详见 [LeaveChannelOptions](/zh-CN/api-reference/rtc/unity/class-leavechanneloptions)。
### 返回值 [#返回值-8]
- 0: 方法调用成功。
- < 0: 方法调用失败。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。
### 所属接口类 [#所属接口类-8]
- [IRtcEngine](/zh-CN/api-reference/rtc/unity/rtc-interface-class#class_irtcengine)
## LeaveChannelEx [1/2] [#leavechannelex-12]
离开频道。
```csharp
public abstract int LeaveChannelEx(RtcConnection connection);
```
调用该方法后,SDK 会终止音视频互动、离开当前频道,并会释放会话相关的所有资源。
调用 [JoinChannelEx](/zh-CN/api-reference/rtc/unity/channel#api_irtcengineex_joinchannelex) 成功加入频道后,必须调用本方法或 [LeaveChannelEx [2/2]](/zh-CN/api-reference/rtc/unity/channel#api_irtcengineex_leavechannelex2) 结束通话,否则无法开始下一次通话。
:::note
注:
- 该方法是异步操作,调用返回时并没有真正退出频道。
- 如果你调用了 [LeaveChannel [1/2]](/zh-CN/api-reference/rtc/unity/channel#api_irtcengine_leavechannel) 或 [LeaveChannel [2/2]](/zh-CN/api-reference/rtc/unity/channel#api_irtcengine_leavechannel2),会同时离开 [JoinChannel [1/2]](/zh-CN/api-reference/rtc/unity/channel#api_irtcengine_joinchannel1) 或 [JoinChannel [2/2]](/zh-CN/api-reference/rtc/unity/channel#api_irtcengine_joinchannel2) 及 [JoinChannelEx](/zh-CN/api-reference/rtc/unity/channel#api_irtcengineex_joinchannelex) 加入的频道。
如果你调用了该方法后立即调用 [Dispose](/zh-CN/api-reference/rtc/unity/play/mediaplayer/mediaplayer-initialize#api_imediaplayer_dispose_imediaplayer) 方法,SDK 将不会触发 [OnLeaveChannel](/zh-CN/api-reference/rtc/unity/channel#callback_irtcengineeventhandler_onleavechannel) 回调。
:::
### 适用场景 [#适用场景-1]
该方法适用于多频道场景。
### 调用时机 [#调用时机-9]
该方法需要在 [JoinChannelEx](/zh-CN/api-reference/rtc/unity/channel#api_irtcengineex_joinchannelex) 后调用。
### 相关回调 [#相关回调-9]
成功调用该方法离开频道后会触发以下回调:
- 本地:[OnLeaveChannel](/zh-CN/api-reference/rtc/unity/channel#callback_irtcengineeventhandler_onleavechannel) 回调。
- 远端:主播离开频道后,远端会触发 [OnUserOffline](/zh-CN/api-reference/rtc/unity/channel#callback_irtcengineeventhandler_onuseroffline) 回调。
### 参数 [#参数-9]
Connection 信息。详见 [RtcConnection](/zh-CN/api-reference/rtc/unity/class-rtcconnection)。
### 返回值 [#返回值-9]
- 0: 方法调用成功。
- < 0: 方法调用失败。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。
### 所属接口类 [#所属接口类-9]
- [IRtcEngineEx](/zh-CN/api-reference/rtc/unity/rtc-interface-class#class_irtcengineex)
## LeaveChannelEx [2/2] [#leavechannelex-22]
设置频道选项并离开频道。
```csharp
public abstract int LeaveChannelEx(RtcConnection connection, LeaveChannelOptions options);
```
调用该方法后,SDK 会终止音视频互动、离开当前频道,并会释放会话相关的所有资源。
调用 [JoinChannelEx](/zh-CN/api-reference/rtc/unity/channel#api_irtcengineex_joinchannelex) 成功加入频道后,必须调用本方法或 [LeaveChannelEx [1/2]](/zh-CN/api-reference/rtc/unity/channel#api_irtcengineex_leavechannelex) 结束通话,否则无法开始下一次通话。
:::note
注:
- 该方法是异步操作,调用返回时并没有真正退出频道。
- 如果你调用了 [LeaveChannel [1/2]](/zh-CN/api-reference/rtc/unity/channel#api_irtcengine_leavechannel) 或 [LeaveChannel [2/2]](/zh-CN/api-reference/rtc/unity/channel#api_irtcengine_leavechannel2) 后,会同时离开 [JoinChannel [1/2]](/zh-CN/api-reference/rtc/unity/channel#api_irtcengine_joinchannel1) 或 [JoinChannel [2/2]](/zh-CN/api-reference/rtc/unity/channel#api_irtcengine_joinchannel2) 及 [JoinChannelEx](/zh-CN/api-reference/rtc/unity/channel#api_irtcengineex_joinchannelex) 加入的频道。
如果你调用了该方法后立即调用 [Dispose](/zh-CN/api-reference/rtc/unity/play/mediaplayer/mediaplayer-initialize#api_imediaplayer_dispose_imediaplayer) 方法,SDK 将不会触发 [OnLeaveChannel](/zh-CN/api-reference/rtc/unity/channel#callback_irtcengineeventhandler_onleavechannel) 回调。
:::
### 适用场景 [#适用场景-2]
该方法适用于多频道场景。
### 调用时机 [#调用时机-10]
该方法需要在 [JoinChannelEx](/zh-CN/api-reference/rtc/unity/channel#api_irtcengineex_joinchannelex) 后调用。
### 相关回调 [#相关回调-10]
成功调用该方法离开频道后会触发以下回调:
- 本地:[OnLeaveChannel](/zh-CN/api-reference/rtc/unity/channel#callback_irtcengineeventhandler_onleavechannel) 回调。
- 远端:主播离开频道后,远端会触发 [OnUserOffline](/zh-CN/api-reference/rtc/unity/channel#callback_irtcengineeventhandler_onuseroffline) 回调。
### 参数 [#参数-10]
Connection 信息。详见 [RtcConnection](/zh-CN/api-reference/rtc/unity/class-rtcconnection)。
离开频道的选项,详见 [LeaveChannelOptions](/zh-CN/api-reference/rtc/unity/class-leavechanneloptions)。
:::note
注: 该参数仅支持设置 [LeaveChannelOptions](/zh-CN/api-reference/rtc/unity/class-leavechanneloptions) 中的 `stopMicrophoneRecording` 成员,设置其他成员均不生效。
:::
### 返回值 [#返回值-10]
- 0: 方法调用成功。
- < 0: 方法调用失败。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。
### 所属接口类 [#所属接口类-10]
- [IRtcEngineEx](/zh-CN/api-reference/rtc/unity/rtc-interface-class#class_irtcengineex)
## PreloadChannel [#preloadchannel]
使用 `token`、`channelId`、`uid` 预加载频道。
```csharp
public abstract int PreloadChannel(string token, string channelId, uint uid);
```
调用该方法可以减少观众频繁切换频道时加入频道的时间,从而缩短观众听到主播首帧音频以及看到首帧画面的耗时,提升观众端的视频体验。
如果当前频道已经成功预加载,观众加入、离开频道后如需再次加入该频道,只要预加载时传入的 Token 仍在有效期内,则无需重新预加载。
:::note
注: 预加载不生效不会影响后续正常加入频道,也不会增加加入频道的耗时。
- 调用该方法时,请确保用户角色设为观众、音频应用场景设为非合唱场景(`AUDIO_SCENARIO_CHORUS`),否则预加载不生效。
- 请确保预加载频道时传入的频道名、用户 ID、Token 和后续加入频道时传入的值相同,否则预加载不生效。
- 目前一个 [IRtcEngine](/zh-CN/api-reference/rtc/unity/rtc-interface-class#class_irtcengine) 实例最多支持预加载 20 个频道,如超出限制,仅最新预加载的 20 个频道生效。
:::
### 调用时机 [#调用时机-11]
为了提升预加载频道的用户体验,声网推荐你在确认频道名、用户信息后、加入频道前,尽早调用该方法。
### 参数 [#参数-11]
在服务端生成的用于鉴权的动态密钥。详见[使用 Token 鉴权](/zh-CN/realtime-media/rtc/build/setup-and-access/token-authentication)。
Token 过期后,根据预加载频道的数量,你可以通过不同方式来传入用于预加载频道的新 Token:
- 预加载一个频道时:调用此方法来传入新的 Token。
- 预加载多个频道时:
- 如果你使用了通配的 Token,调用 [UpdatePreloadChannelToken](/zh-CN/api-reference/rtc/unity/channel#api_irtcengine_updatepreloadchanneltoken) 来更新所有预加载频道的 Token。生成通配 Token 时,用户 ID 不得设为 0。详见 [使用通配 Token](/zh-CN/realtime-media/rtc/build/security-and-auth/wildcard-token)。
- 如果你使用了不同的 Token:调用此方法并传入你的用户 ID、对应的频道名和更新后的 Token。
待预加载的频道名。该参数标识用户进行实时音视频互动的频道。App ID 一致的前提下,填入相同频道名的用户会进入同一个频道进行音视频互动。
该参数为长度在 64 字节以内的字符串。以下为支持的字符集范围(共 89 个字符):
- 26 个小写英文字母 a~z
- 26 个大写英文字母 A~Z
- 10 个数字 0~9
- "!"、"#"、"$"、"%"、"&"、"("、")"、"+"、"-"、":"、";"、"<"、"="、"."、">"、"?"、"@"、"["、"]"、"^"、"_"、"\{"、"\}"、"|"、"~"、","
用户 ID。该参数用于标识在实时音视频互动频道中的用户。你需要自行设置和管理用户 ID,并确保同一频道内的每个用户 ID 是唯一的。该参数为 32 位无符号整数。建议设置范围:1 到 2³² - 1。如果不指定(即设为 0),SDK 会自动分配一个,并在 [OnJoinChannelSuccess](/zh-CN/api-reference/rtc/unity/channel#callback_irtcengineeventhandler_onjoinchannelsuccess) 回调中返回, 应用层必须记住该返回值并维护,SDK 不对该返回值进行维护。
### 返回值 [#返回值-11]
- 0:方法调用成功。
- < 0:方法调用失败。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。
- -7:[IRtcEngine](/zh-CN/api-reference/rtc/unity/rtc-interface-class#class_irtcengine) 对象尚未初始化。你需要在调用该方法前成功初始化 [IRtcEngine](/zh-CN/api-reference/rtc/unity/rtc-interface-class#class_irtcengine) 对象。
- -102:频道名无效。你需要填入有效的频道名,重新加入频道。
### 所属接口类 [#所属接口类-11]
- [IRtcEngine](/zh-CN/api-reference/rtc/unity/rtc-interface-class#class_irtcengine)
## PreloadChannelWithUserAccount [#preloadchannelwithuseraccount]
使用 `token`、`channelId`、`userAccount` 预加载频道。
```csharp
public abstract int PreloadChannel(string token, string channelId, string userAccount);
```
调用该方法可以减少观众频繁切换频道时加入频道的时间,从而缩短观众听到主播首帧音频以及看到首帧画面的耗时,提升观众端的视频体验。
如果当前频道已经成功预加载,观众加入、离开频道后如需再次加入该频道,只要预加载时传入的 Token 仍在有效期内,则无需重新预加载。
:::note
注: 预加载不生效不会影响后续正常加入频道,也不会增加加入频道的耗时。
- 调用该方法时,请确保用户角色设为观众、音频应用场景设为非合唱场景(`AUDIO_SCENARIO_CHORUS`),否则预加载不生效。
- 请确保预加载频道时传入的频道名、用户 User Account、Token 和后续加入频道时传入的值相同,否则预加载不生效。
- 目前一个 [IRtcEngine](/zh-CN/api-reference/rtc/unity/rtc-interface-class#class_irtcengine) 实例最多支持预加载 20 个频道,如超出限制,仅最新预加载的 20 个频道生效。
:::
### 调用时机 [#调用时机-12]
为了提升预加载频道的用户体验,声网推荐你在确认频道名、用户信息后、加入频道前,尽早调用该方法。
### 参数 [#参数-12]
在服务端生成的用于鉴权的动态密钥。详见[使用 Token 鉴权](/zh-CN/realtime-media/rtc/build/setup-and-access/token-authentication)。
Token 过期后,根据预加载频道的数量,你可以通过不同方式来传入用于预加载频道的新 Token:
- 预加载一个频道时:调用此方法来传入新的 Token。
- 预加载多个频道时:
- 如果你使用了通配的 Token,调用 [UpdatePreloadChannelToken](/zh-CN/api-reference/rtc/unity/channel#api_irtcengine_updatepreloadchanneltoken) 来更新所有预加载频道的 Token。生成通配 Token 时,用户 ID 不得设为 0。详见 [使用通配 Token](/zh-CN/realtime-media/rtc/build/security-and-auth/wildcard-token)。
- 如果你使用了不同的 Token:调用此方法并传入你的用户 ID、对应的频道名和更新后的 Token。
待预加载的频道名。该参数标识用户进行实时音视频互动的频道。App ID 一致的前提下,填入相同频道名的用户会进入同一个频道进行音视频互动。
该参数为长度在 64 字节以内的字符串。以下为支持的字符集范围(共 89 个字符):
- 26 个小写英文字母 a~z
- 26 个大写英文字母 A~Z
- 10 个数字 0~9
- "!"、"#"、"$"、"%"、"&"、"("、")"、"+"、"-"、":"、";"、"<"、"="、"."、">"、"?"、"@"、"["、"]"、"^"、"_"、"\{"、"\}"、"|"、"~"、","
用户 User Account。该参数用于标识实时音视频互动频道中的用户。你需要自行设置和管理用户的 User Account,并确保同一频道中每个用户的 User Account 是唯一的。 该参数为必填,最大不超过 255 字节,不可填 `null`。以下为支持的字符集范围(共 89 个字符):
- 26 个小写英文字母 a-z
- 26 个大写英文字母 A-Z
- 10 个数字 0-9
- 空格
- "!"、"#"、"$"、"%"、"&"、"("、")"、"+"、"-"、":"、";"、"<"、"="、"."、">"、"?"、"@"、"["、"]"、"^"、"_"、"\{"、"\}"、"|"、"~"、","
### 返回值 [#返回值-12]
- 0:方法调用成功。
- < 0:方法调用失败。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。
- -2:传入的参数无效。例如,User Account 为空。你需要填入有效的参数,重新加入频道。
- -7:[IRtcEngine](/zh-CN/api-reference/rtc/unity/rtc-interface-class#class_irtcengine) 对象尚未初始化。你需要在调用该方法前成功初始化 [IRtcEngine](/zh-CN/api-reference/rtc/unity/rtc-interface-class#class_irtcengine) 对象。
- -102:频道名无效。你需要填入有效的频道名,重新加入频道。
### 所属接口类 [#所属接口类-12]
- [IRtcEngine](/zh-CN/api-reference/rtc/unity/rtc-interface-class#class_irtcengine)
## RegisterLocalUserAccount [#registerlocaluseraccount]
注册本地用户 User Account。
```csharp
public abstract int RegisterLocalUserAccount(string appId, string userAccount);
```
该方法为本地用户注册一个 User Account。注册成功后,该 User Account 即可标识该本地用户的身份,用户可以使用它加入频道。
该方法为可选。如果你希望用户使用 User Account 加入频道,可参考下列任意一种方式实现:
- 先调用 [RegisterLocalUserAccount](/zh-CN/api-reference/rtc/unity/channel#api_irtcengine_registerlocaluseraccount) 方法注册 Account,再调用 [JoinChannelWithUserAccount [1/2]](/zh-CN/api-reference/rtc/unity/channel#api_irtcengine_joinchannelwithuseraccount1) 或 [JoinChannelWithUserAccount [2/2]](/zh-CN/api-reference/rtc/unity/channel#api_irtcengine_joinchannelwithuseraccount2) 方法加入频道,可以缩短进入频道的时间。
- 直接调用 [JoinChannelWithUserAccount [1/2]](/zh-CN/api-reference/rtc/unity/channel#api_irtcengine_joinchannelwithuseraccount1) 或 [JoinChannelWithUserAccount [2/2]](/zh-CN/api-reference/rtc/unity/channel#api_irtcengine_joinchannelwithuseraccount2) 方法加入频道。
:::note
注:
- 请确保在该方法中设置的 `userAccount` 在频道中的唯一性。
- 为保证通信质量,请确保频道内使用同一类型的数据标识用户身份。即同一频道内需要统一使用 UID 或 User Account。如果有用户通过 Web SDK 加入频道,请确保 Web 加入的用户也是同样类型。
:::
### 相关回调 [#相关回调-11]
成功调用该方法后,本地会触发 [OnLocalUserRegistered](/zh-CN/api-reference/rtc/unity/channel#callback_irtcengineeventhandler_onlocaluserregistered) 回调,告知本地用户的 UID 和 User Account。
### 参数 [#参数-13]
你的项目在控制台注册的 App ID。
用户 User Account。该参数用于标识实时音视频互动频道中的用户。你需要自行设置和管理用户的 User Account,并确保同一频道中每个用户的 User Account 是唯一的。该参数为必填,最大不超过 255 字节,不可填 `null`。以下为支持的字符集范围(共 89 个字符):
- 26 个小写英文字母 a-z
- 26 个大写英文字母 A-Z
- 10 个数字 0-9
- 空格
- "!"、"#"、"$"、"%"、"&"、"("、")"、"+"、"-"、":"、";"、"<"、"="、"."、">"、"?"、"@"、"["、"]"、"^"、"_"、"\{"、"\}"、"|"、"~"、","
### 返回值 [#返回值-13]
- 0: 方法调用成功。
- < 0: 方法调用失败。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。
### 所属接口类 [#所属接口类-13]
- [IRtcEngine](/zh-CN/api-reference/rtc/unity/rtc-interface-class#class_irtcengine)
## RenewToken [#renewtoken]
更新 Token。
```csharp
public abstract int RenewToken(string token);
```
该方法用于更新 Token。Token 会在一定时间后失效,此时 SDK 将无法和服务器建立连接。
### 调用时机 [#调用时机-13]
在单频道场景下,你可以在以下情况下调用该方法更新 Token:
- 收到 `onTokenPrivilegeWillExpire` 回调,提示 Token 即将过期。
- Token 已过期时,SDK 会触发 `onRequestToken` 回调,并在 `onConnectionStateChanged` 回调中报告 `CONNECTION_CHANGED_TOKEN_EXPIRED`(9)。
### 参数 [#参数-14]
新生成的 Token。
### 返回值 [#返回值-14]
- 0: 方法调用成功。
- < 0: 方法调用失败。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。
- -2:传入的参数无效。例如,Token 为空。
- -7:[IRtcEngine](/zh-CN/api-reference/rtc/unity/rtc-interface-class#class_irtcengine) 对象尚未初始化。你需要在调用该方法前成功初始化 [IRtcEngine](/zh-CN/api-reference/rtc/unity/rtc-interface-class#class_irtcengine) 对象。
- -110:Token 无效。请确保:
- 生成 Token 时指定的用户 ID 与加入频道时使用的用户 ID 一致,
- 生成的 Token 和加入频道使用的 Token 一致。
### 所属接口类 [#所属接口类-14]
- [IRtcEngine](/zh-CN/api-reference/rtc/unity/rtc-interface-class#class_irtcengine)
## SetChannelProfile [#setchannelprofile]
设置频道场景。
```csharp
public abstract int SetChannelProfile(CHANNEL_PROFILE_TYPE profile);
```
你可以调用该方法设置频道的使用场景。SDK 会针对不同的使用场景采用不同的优化策略,如直播场景优先保证画质。SDK 初始化后默认的频道场景为直播场景。
:::note
注: 为保证实时音视频质量,相同频道内的用户必须使用同一种频道场景。
:::
### 调用时机 [#调用时机-14]
该方法需要在加入频道前调用。
### 参数 [#参数-15]
频道使用场景。详见 [CHANNEL_PROFILE_TYPE](/zh-CN/api-reference/rtc/unity/enum-channelprofiletype)。
### 返回值 [#返回值-15]
- 0: 方法调用成功。
- < 0: 方法调用失败。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。
- -2: 参数无效。
- -7: SDK 尚未初始化。
### 所属接口类 [#所属接口类-15]
- [IRtcEngine](/zh-CN/api-reference/rtc/unity/rtc-interface-class#class_irtcengine)
## SetClientRole [1/2] [#setclientrole-12]
设置用户角色。
```csharp
public abstract int SetClientRole(CLIENT_ROLE_TYPE role);
```
SDK 默认设置用户角色为观众,你可以调用该方法设置用户角色为主播。用户角色(`role`)确定用户在 SDK 层的权限,包含是否可以发送流等。
:::note
注: 在频道外调用本方法并将用户角色设为 `BROADCASTER`(主播)时,本地不会触发 [OnClientRoleChanged](/zh-CN/api-reference/rtc/unity/channel#callback_irtcengineeventhandler_onclientrolechanged) 回调。
:::
### 调用时机 [#调用时机-15]
该方法在加入频道前后均可调用。
如果你在加入频道前调用该方法设置用户角色为主播、并且调用 [SetEnable](/zh-CN/api-reference/rtc/unity/video/video-rendering#api_videosurface_setenable) 方法开启视频渲染,则用户加入频道时会自动开启本地视频预览。
如果你在加入频道后调用该方法切换用户角色,调用成功后,SDK 会自动调用 [MuteLocalAudioStream](/zh-CN/api-reference/rtc/unity/publishnsubscribe#api_irtcengine_mutelocalaudiostream) 和 [MuteLocalVideoStream](/zh-CN/api-reference/rtc/unity/publishnsubscribe#api_irtcengine_mutelocalvideostream) 修改发布音视频流的状态。
### 相关回调 [#相关回调-12]
如果你在加入频道后成功调用该方法切换用户角色,SDK 会触发下列回调:
- 本地触发 [OnClientRoleChanged](/zh-CN/api-reference/rtc/unity/channel#callback_irtcengineeventhandler_onclientrolechanged) 回调。在加入频道前调用该方法并将 `role` 设为 `AUDIENCE`(观众)时,也会触发该回调。
- 远端触发 [OnUserJoined](/zh-CN/api-reference/rtc/unity/channel#callback_irtcengineeventhandler_onuserjoined) 或 [OnUserOffline](/zh-CN/api-reference/rtc/unity/channel#callback_irtcengineeventhandler_onuseroffline) 回调。
如果你在加入频道后调用该方法切换用户角色失败,SDK 会触发 [OnClientRoleChangeFailed](/zh-CN/api-reference/rtc/unity/channel#callback_irtcengineeventhandler_onclientrolechangefailed),报告切换失败的原因和当前的用户角色。
### 参数 [#参数-16]
用户角色。详见 [CLIENT_ROLE_TYPE](/zh-CN/api-reference/rtc/unity/enum-clientroletype)。
:::note
注: 角色为观众的用户无法在频道内发布音视频流。在直播场景下发流时,请确保你的用户角色已切换为主播。
:::
### 返回值 [#返回值-16]
- 0: 方法调用成功。
- < 0: 方法调用失败。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。
- -1: 一般性的错误(未明确归类)。
- -2: 参数无效。
- -7: SDK 尚未初始化。
### 所属接口类 [#所属接口类-16]
- [IRtcEngine](/zh-CN/api-reference/rtc/unity/rtc-interface-class#class_irtcengine)
## SetClientRole [2/2] [#setclientrole-22]
设置直播场景下的用户角色和观众端延时级别。
```csharp
public abstract int SetClientRole(CLIENT_ROLE_TYPE role, ClientRoleOptions options);
```
SDK 默认设置用户角色为观众,你可以调用该方法设置用户角色为主播。用户角色(`role`)确定用户在 SDK 层的权限,包含是否有发流权限等。
该方法与 [SetClientRole [1/2]](/zh-CN/api-reference/rtc/unity/channel#api_irtcengine_setclientrole1) 的区别在于,该方法还支持设置观众端延时级别(`audienceLatencyLevel`)。`audienceLatencyLevel` 需与 `role` 结合使用,确定用户在其权限范围内可以享受到的服务。例如对于观众,选择接收低延时还是超低延时的视频流。
不同的延时级别会影响计费,详见[计费策略](/zh-CN/realtime-media/rtc/reference/billing-strategy)。
:::note
注: 当用户角色设为主播时,观众端延时级别仅支持设置为 AUDIENCE_LATENCY_LEVEL_ULTRA_LOW_LATENCY(超低延时)。
在加入频道前调用该方法并将 `role` 设为 `BROADCASTER`(主播)时,本地不会触发 [OnClientRoleChanged](/zh-CN/api-reference/rtc/unity/channel#callback_irtcengineeventhandler_onclientrolechanged) 回调。
:::
### 调用时机 [#调用时机-16]
该方法在加入频道前后均可调用。
如果你在加入频道前调用该方法设置用户角色为主播、并且调用 [SetEnable](/zh-CN/api-reference/rtc/unity/video/video-rendering#api_videosurface_setenable) 方法开启视频渲染,则用户加入频道时会自动开启本地视频预览。
如果你在加入频道后调用该方法切换用户角色,调用成功后,SDK 会自动调用 [MuteLocalAudioStream](/zh-CN/api-reference/rtc/unity/publishnsubscribe#api_irtcengine_mutelocalaudiostream) 和 [MuteLocalVideoStream](/zh-CN/api-reference/rtc/unity/publishnsubscribe#api_irtcengine_mutelocalvideostream) 修改发布音视频流的状态。
### 相关回调 [#相关回调-13]
如果你在加入频道后成功调用该方法切换用户角色,SDK 会触发下列回调:
- 本地触发 [OnClientRoleChanged](/zh-CN/api-reference/rtc/unity/channel#callback_irtcengineeventhandler_onclientrolechanged) 回调。在加入频道前调用该方法并将 `role` 设为 `AUDIENCE`(观众)时,也会触发该回调。
- 远端触发 [OnUserJoined](/zh-CN/api-reference/rtc/unity/channel#callback_irtcengineeventhandler_onuserjoined) 或 [OnUserOffline](/zh-CN/api-reference/rtc/unity/channel#callback_irtcengineeventhandler_onuseroffline) 回调。
如果你在加入频道后调用该方法切换用户角色失败,SDK 会触发 [OnClientRoleChangeFailed](/zh-CN/api-reference/rtc/unity/channel#callback_irtcengineeventhandler_onclientrolechangefailed),报告切换失败的原因和当前的用户角色。
### 参数 [#参数-17]
用户角色。详见 [CLIENT_ROLE_TYPE](/zh-CN/api-reference/rtc/unity/enum-clientroletype)。
:::note
注: 角色为观众的用户无法在频道内发布音视频流。在直播场景下发流时,请确保你的用户角色已切换为主播。
:::
用户具体设置,包含用户级别。详见 [ClientRoleOptions](/zh-CN/api-reference/rtc/unity/class-clientroleoptions)。
### 返回值 [#返回值-17]
- 0: 方法调用成功。
- < 0: 方法调用失败。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。
- -1: 一般性的错误(未明确归类)。
- -2: 参数无效。
- -5: 调用被拒绝。
- -7: SDK 尚未初始化。
### 所属接口类 [#所属接口类-17]
- [IRtcEngine](/zh-CN/api-reference/rtc/unity/rtc-interface-class#class_irtcengine)
## UpdateChannelMediaOptions [#updatechannelmediaoptions]
加入频道后更新频道媒体选项。
```csharp
public abstract int UpdateChannelMediaOptions(ChannelMediaOptions options);
```
### 参数 [#参数-18]
频道媒体选项,详见 [ChannelMediaOptions](/zh-CN/api-reference/rtc/unity/class-channelmediaoptions)。
### 返回值 [#返回值-18]
- 0: 方法调用成功。
- < 0: 方法调用失败。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。
- -2:[ChannelMediaOptions](/zh-CN/api-reference/rtc/unity/class-channelmediaoptions) 成员值设置无效。例如,使用了不合法的 Token,设置了无效的用户角色。你需要填入有效的参数。
- -7:[IRtcEngine](/zh-CN/api-reference/rtc/unity/rtc-interface-class#class_irtcengine) 对象尚未初始化。你需要在调用该方法前成功初始化 [IRtcEngine](/zh-CN/api-reference/rtc/unity/rtc-interface-class#class_irtcengine) 对象。
- -8:[IRtcEngine](/zh-CN/api-reference/rtc/unity/rtc-interface-class#class_irtcengine) 对象内部状态错误。可能的原因是用户不在频道中。建议通过 [OnConnectionStateChanged](/zh-CN/api-reference/rtc/unity/network#callback_irtcengineeventhandler_onconnectionstatechanged) 回调判断用户是否在频道中。如果收到 `CONNECTION_STATE_DISCONNECTED`(1) 或 `CONNECTION_STATE_FAILED`(5),则表示用户不在频道中。你需要在调用该方法前调用 [JoinChannel [2/2]](/zh-CN/api-reference/rtc/unity/channel#api_irtcengine_joinchannel2) 加入频道。
### 所属接口类 [#所属接口类-18]
- [IRtcEngine](/zh-CN/api-reference/rtc/unity/rtc-interface-class#class_irtcengine)
## UpdateChannelMediaOptionsEx [#updatechannelmediaoptionsex]
加入频道后更新频道媒体选项。
```csharp
public abstract int UpdateChannelMediaOptionsEx(ChannelMediaOptions options, RtcConnection connection);
```
### 参数 [#参数-19]
频道媒体选项,详见 [ChannelMediaOptions](/zh-CN/api-reference/rtc/unity/class-channelmediaoptions)。
Connection 信息。详见 [RtcConnection](/zh-CN/api-reference/rtc/unity/class-rtcconnection)。
### 返回值 [#返回值-19]
- 0: 方法调用成功。
- < 0: 方法调用失败。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。
- -2:[ChannelMediaOptions](/zh-CN/api-reference/rtc/unity/class-channelmediaoptions) 成员值设置无效。例如,使用了不合法的 Token,设置了无效的用户角色。你需要填入有效的参数。
- -7:[IRtcEngine](/zh-CN/api-reference/rtc/unity/rtc-interface-class#class_irtcengine) 对象尚未初始化。你需要在调用该方法前成功初始化 [IRtcEngine](/zh-CN/api-reference/rtc/unity/rtc-interface-class#class_irtcengine) 对象。
- -8:[IRtcEngine](/zh-CN/api-reference/rtc/unity/rtc-interface-class#class_irtcengine) 对象内部状态错误。可能的原因是用户不在频道中。建议通过 [OnConnectionStateChanged](/zh-CN/api-reference/rtc/unity/network#callback_irtcengineeventhandler_onconnectionstatechanged) 回调判断用户是否在频道中。如果收到 `CONNECTION_STATE_DISCONNECTED`(1) 或 `CONNECTION_STATE_FAILED`(5),则表示用户不在频道中。你需要在调用该方法前调用 [JoinChannel [2/2]](/zh-CN/api-reference/rtc/unity/channel#api_irtcengine_joinchannel2) 加入频道。
### 所属接口类 [#所属接口类-19]
- [IRtcEngineEx](/zh-CN/api-reference/rtc/unity/rtc-interface-class#class_irtcengineex)
## UpdatePreloadChannelToken [#updatepreloadchanneltoken]
更新预加载频道的通配 Token。
```csharp
public abstract int UpdatePreloadChannelToken(string token);
```
你需要自行维护通配 Token 的生命周期。当通配 Token 过期后,你需要在你的服务端生成新的通配 Token,然后通过此方法来传入新的 Token。
### 适用场景 [#适用场景-3]
在需要频繁切换频道及多频道场景下,使用通配 Token 可以避免观众在切换不同频道时需多次申请 Token 从而导致切换频道时间增长,可以进一步加快切换频道的速度,同时减少你的 Token 服务端的压力。
### 参数 [#参数-20]
新的 Token。
### 返回值 [#返回值-20]
- 0: 方法调用成功。
- < 0: 方法调用失败。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。
- -2:传入的参数无效。例如,使用了不合法的 Token。你需要填入有效的参数,重新加入频道。
- -7:[IRtcEngine](/zh-CN/api-reference/rtc/unity/rtc-interface-class#class_irtcengine) 对象尚未初始化。你需要在调用该方法前成功初始化 [IRtcEngine](/zh-CN/api-reference/rtc/unity/rtc-interface-class#class_irtcengine) 对象。
### 所属接口类 [#所属接口类-20]
- [IRtcEngine](/zh-CN/api-reference/rtc/unity/rtc-interface-class#class_irtcengine)
## OnClientRoleChanged [#onclientrolechanged]
用户角色、观众端延时级别已切换回调。
```csharp
public virtual void OnClientRoleChanged(RtcConnection connection, CLIENT_ROLE_TYPE oldRole, CLIENT_ROLE_TYPE newRole, ClientRoleOptions newRoleOptions) { }
```
:::note
注: 当你在加入频道前调用 [SetClientRole [1/2]](/zh-CN/api-reference/rtc/unity/channel#api_irtcengine_setclientrole1) 或 [SetClientRole [2/2]](/zh-CN/api-reference/rtc/unity/channel#api_irtcengine_setclientrole2) 并将用户角色设为 `BROADCASTER` 时,不会触发此回调。
:::
### 触发时机 [#触发时机]
在以下任意一种情况时,会触发此回调:
- 在加入频道后调用 [SetClientRole [1/2]](/zh-CN/api-reference/rtc/unity/channel#api_irtcengine_setclientrole1) 或 [SetClientRole [2/2]](/zh-CN/api-reference/rtc/unity/channel#api_irtcengine_setclientrole2) 设置用户角色或观众端延时级别。
- 在加入频道前调用 [SetClientRole [1/2]](/zh-CN/api-reference/rtc/unity/channel#api_irtcengine_setclientrole1) 或 [SetClientRole [2/2]](/zh-CN/api-reference/rtc/unity/channel#api_irtcengine_setclientrole2) 并将用户角色设为 `AUDIENCE`。
### 参数 [#参数-21]
Connection 信息。详见 [RtcConnection](/zh-CN/api-reference/rtc/unity/class-rtcconnection)。
切换前的角色:[CLIENT_ROLE_TYPE](/zh-CN/api-reference/rtc/unity/enum-clientroletype)。
切换后的角色:[CLIENT_ROLE_TYPE](/zh-CN/api-reference/rtc/unity/enum-clientroletype)。
切换后的角色属性。详见 [ClientRoleOptions](/zh-CN/api-reference/rtc/unity/class-clientroleoptions)。
### 所属接口类 [#所属接口类-21]
- [IRtcEngineEventHandler](/zh-CN/api-reference/rtc/unity/rtc-interface-class#class_irtcengineeventhandler)
## OnClientRoleChangeFailed [#onclientrolechangefailed]
用户角色切换失败回调。
```csharp
public virtual void OnClientRoleChangeFailed(RtcConnection connection, CLIENT_ROLE_CHANGE_FAILED_REASON reason, CLIENT_ROLE_TYPE currentRole) { }
```
当用户角色切换失败时,你可以通过此回调得知切换失败的原因和当前的用户角色。
### 触发时机 [#触发时机-1]
本地用户加入频道后调用 [SetClientRole [1/2]](/zh-CN/api-reference/rtc/unity/channel#api_irtcengine_setclientrole1) 或 [SetClientRole [2/2]](/zh-CN/api-reference/rtc/unity/channel#api_irtcengine_setclientrole2) 设置用户角色失败时,SDK 会触发该回调。
### 参数 [#参数-22]
切换用户角色失败的原因。详见 [CLIENT_ROLE_CHANGE_FAILED_REASON](/zh-CN/api-reference/rtc/unity/enum-clientrolechangefailedreason)。
当前用户角色。详见 [CLIENT_ROLE_TYPE](/zh-CN/api-reference/rtc/unity/enum-clientroletype)。
Connection 信息。详见 [RtcConnection](/zh-CN/api-reference/rtc/unity/class-rtcconnection)。
### 所属接口类 [#所属接口类-22]
- [IRtcEngineEventHandler](/zh-CN/api-reference/rtc/unity/rtc-interface-class#class_irtcengineeventhandler)
## OnError [#onerror]
发生错误回调。
```csharp
public virtual void OnError(int err, string msg) { }
```
该回调方法表示 SDK 运行时出现了网络或媒体相关的错误。通常情况下,SDK 上报的错误意味着 SDK 无法自动恢复,需要 App 干预或提示用户。
### 参数 [#参数-23]
错误码。详见 [ERROR_CODE_TYPE](/zh-CN/api-reference/rtc/unity/enum-errorcodetype)。
错误描述。
### 所属接口类 [#所属接口类-23]
- [IRtcEngineEventHandler](/zh-CN/api-reference/rtc/unity/rtc-interface-class#class_irtcengineeventhandler)
## OnJoinChannelSuccess [#onjoinchannelsuccess]
成功加入频道回调。
```csharp
public virtual void OnJoinChannelSuccess(RtcConnection connection, int elapsed) {}
```
该回调方法表示该客户端成功加入了指定的频道。
### 触发时机 [#触发时机-2]
当你调用 [JoinChannel [1/2]](/zh-CN/api-reference/rtc/unity/channel#api_irtcengine_joinchannel1)、[JoinChannel [2/2]](/zh-CN/api-reference/rtc/unity/channel#api_irtcengine_joinchannel2)、[JoinChannelWithUserAccount [1/2]](/zh-CN/api-reference/rtc/unity/channel#api_irtcengine_joinchannelwithuseraccount1)、[JoinChannelWithUserAccount [2/2]](/zh-CN/api-reference/rtc/unity/channel#api_irtcengine_joinchannelwithuseraccount2)、 [JoinChannelEx](/zh-CN/api-reference/rtc/unity/channel#api_irtcengineex_joinchannelex) 方法成功加入频道后,SDK 会触发该回调。
### 参数 [#参数-24]
Connection 信息。详见 [RtcConnection](/zh-CN/api-reference/rtc/unity/class-rtcconnection)。
从本地调用 [JoinChannel [2/2]](/zh-CN/api-reference/rtc/unity/channel#api_irtcengine_joinchannel2) 开始到发生此事件过去的时间(毫秒)。
### 所属接口类 [#所属接口类-24]
- [IRtcEngineEventHandler](/zh-CN/api-reference/rtc/unity/rtc-interface-class#class_irtcengineeventhandler)
## OnLeaveChannel [#onleavechannel]
离开频道回调。
```csharp
public virtual void OnLeaveChannel(RtcConnection connection, RtcStats stats) {}
```
你可以通过该回调获取此次通话的总通话时长、SDK 收发数据的流量等信息。
### 触发时机 [#触发时机-3]
当你成功调用 [LeaveChannel [1/2]](/zh-CN/api-reference/rtc/unity/channel#api_irtcengine_leavechannel)、[LeaveChannel [2/2]](/zh-CN/api-reference/rtc/unity/channel#api_irtcengine_leavechannel2)、[LeaveChannelEx [1/2]](/zh-CN/api-reference/rtc/unity/channel#api_irtcengineex_leavechannelex) 或 [LeaveChannelEx [2/2]](/zh-CN/api-reference/rtc/unity/channel#api_irtcengineex_leavechannelex2) 离开频道后,SDK 会触发该回调。
### 参数 [#参数-25]
Connection 信息。详见 [RtcConnection](/zh-CN/api-reference/rtc/unity/class-rtcconnection)。
通话的统计数据,详见 [RtcStats](/zh-CN/api-reference/rtc/unity/class-rtcstats)。
### 所属接口类 [#所属接口类-25]
- [IRtcEngineEventHandler](/zh-CN/api-reference/rtc/unity/rtc-interface-class#class_irtcengineeventhandler)
## OnLocalUserRegistered [#onlocaluserregistered]
本地用户成功注册 User Account 回调。
```csharp
public virtual void OnLocalUserRegistered(uint uid, string userAccount) {}
```
本地用户成功调用 [RegisterLocalUserAccount](/zh-CN/api-reference/rtc/unity/channel#api_irtcengine_registerlocaluseraccount) 方法注册用户 User Account,或调用 [JoinChannelWithUserAccount [2/2]](/zh-CN/api-reference/rtc/unity/channel#api_irtcengine_joinchannelwithuseraccount2) 加入频道后,SDK 会触发该回调,并告知本地用户的 UID 和 User Account。
### 参数 [#参数-26]
本地用户的 ID。
本地用户的 User Account。
### 所属接口类 [#所属接口类-26]
- [IRtcEngineEventHandler](/zh-CN/api-reference/rtc/unity/rtc-interface-class#class_irtcengineeventhandler)
## OnRejoinChannelSuccess [#onrejoinchannelsuccess]
成功重新加入频道回调。
```csharp
public virtual void OnRejoinChannelSuccess(RtcConnection connection, int elapsed) {}
```
### 触发时机 [#触发时机-4]
有时候由于网络原因,客户端可能会和服务器失去连接,SDK 会进行自动重连,自动重连成功后触发此回调方法。
### 参数 [#参数-27]
Connection 信息。详见 [RtcConnection](/zh-CN/api-reference/rtc/unity/class-rtcconnection)。
从调用 [JoinChannel [2/2]](/zh-CN/api-reference/rtc/unity/channel#api_irtcengine_joinchannel2) 方法到触发该回调的时间间隔(毫秒)。
### 所属接口类 [#所属接口类-27]
- [IRtcEngineEventHandler](/zh-CN/api-reference/rtc/unity/rtc-interface-class#class_irtcengineeventhandler)
## OnRenewTokenResult [#onrenewtokenresult]
`renewToken` 方法调用结果回调。
```csharp
public virtual void OnRenewTokenResult(RtcConnection connection, string token, RENEW_TOKEN_ERROR_CODE code)
```
:::info[自从]
自 v4.6.2 版本新增。
:::
当你调用 `renewToken` 方法更新 Token 后,该回调会被触发,用于通知更新结果。
### 参数 [#参数-28]
更新的 Token。
错误码,详见 [RENEW_TOKEN_ERROR_CODE](/zh-CN/api-reference/rtc/unity/enum-renewtokenerrorcode)。
### 所属接口类 [#所属接口类-28]
- [IRtcEngineEventHandler](/zh-CN/api-reference/rtc/unity/rtc-interface-class#class_irtcengineeventhandler)
## OnRequestToken [#onrequesttoken]
Token 已过期回调。
```csharp
public virtual void OnRequestToken(RtcConnection connection) {}
```
在音视频互动过程中,如果 Token 失效,SDK 会触发该回调报告 Token 已过期。
当收到该回调时,你需要重新在服务端生成新的 Token,然后根据场景更新 Token:
- 单频道场景:
- 调用 [RenewToken](/zh-CN/api-reference/rtc/unity/channel#api_irtcengine_renewtoken) 传入新的 Token,无需先离开频道。SDK 会通过 [OnRenewTokenResult](/zh-CN/api-reference/rtc/unity/channel#callback_irtcengineeventhandler_onrenewtokenresult) 回调报告更新结果。
- 如果你的 App 需要离开并重新加入频道,也可以调用 [LeaveChannel [2/2]](/zh-CN/api-reference/rtc/unity/channel#api_irtcengine_leavechannel2) 离开频道,然后在调用 [JoinChannel [2/2]](/zh-CN/api-reference/rtc/unity/channel#api_irtcengine_joinchannel2) 时传入新的 Token。
- 多频道场景:调用 [UpdateChannelMediaOptionsEx](/zh-CN/api-reference/rtc/unity/channel#api_irtcengineex_updatechannelmediaoptionsex) 传入新的 Token。
### 参数 [#参数-29]
Connection 信息。详见 [RtcConnection](/zh-CN/api-reference/rtc/unity/class-rtcconnection)。
### 所属接口类 [#所属接口类-29]
- [IRtcEngineEventHandler](/zh-CN/api-reference/rtc/unity/rtc-interface-class#class_irtcengineeventhandler)
## OnRtcStats [#onrtcstats]
当前通话相关的统计信息回调。
```csharp
public virtual void OnRtcStats(RtcConnection connection, RtcStats stats) {}
```
### 触发时机 [#触发时机-5]
SDK 定期向 App 报告当前通话的统计信息,每两秒触发一次。
### 参数 [#参数-30]
Connection 信息。详见 [RtcConnection](/zh-CN/api-reference/rtc/unity/class-rtcconnection)。
RTC 引擎统计数据,详见 [RtcStats](/zh-CN/api-reference/rtc/unity/class-rtcstats)。
### 所属接口类 [#所属接口类-30]
- [IRtcEngineEventHandler](/zh-CN/api-reference/rtc/unity/rtc-interface-class#class_irtcengineeventhandler)
## OnTokenPrivilegeWillExpire [#ontokenprivilegewillexpire]
Token 即将在 30s 内过期回调。
```csharp
public virtual void OnTokenPrivilegeWillExpire(RtcConnection connection, string token) {}
```
当收到该回调时,你需要重新在服务端生成新的 Token,然后根据场景更新 Token:
- 单频道场景:
- 调用 [RenewToken](/zh-CN/api-reference/rtc/unity/channel#api_irtcengine_renewtoken) 传入新的 Token,无需先离开频道。SDK 会通过 [OnRenewTokenResult](/zh-CN/api-reference/rtc/unity/channel#callback_irtcengineeventhandler_onrenewtokenresult) 回调报告更新结果。
- 如果你的 App 需要离开并重新加入频道,也可以调用 [LeaveChannel [2/2]](/zh-CN/api-reference/rtc/unity/channel#api_irtcengine_leavechannel2) 离开频道,然后在调用 [JoinChannel [2/2]](/zh-CN/api-reference/rtc/unity/channel#api_irtcengine_joinchannel2) 时传入新的 Token。
- 多频道场景:调用 [UpdateChannelMediaOptionsEx](/zh-CN/api-reference/rtc/unity/channel#api_irtcengineex_updatechannelmediaoptionsex) 传入新的 Token。
### 触发时机 [#触发时机-6]
在音视频互动过程中,SDK 会在 Token 过期前 30 秒触发该回调,提醒 App 更新 Token。
### 参数 [#参数-31]
Connection 信息。详见 [RtcConnection](/zh-CN/api-reference/rtc/unity/class-rtcconnection)。
即将过期的 Token。
### 所属接口类 [#所属接口类-31]
- [IRtcEngineEventHandler](/zh-CN/api-reference/rtc/unity/rtc-interface-class#class_irtcengineeventhandler)
## OnUserInfoUpdated [#onuserinfoupdated]
远端用户信息已更新回调。
```csharp
public virtual void OnUserInfoUpdated(uint uid, UserInfo info)
```
远端用户加入频道后,SDK 会获取到该远端用户的 UID 和 User Account,然后缓存一个包含了远端用户 UID 和 User Account 的 Mapping 表,并在本地触发该回调。
### 参数 [#参数-32]
远端用户 ID。
标识用户信息的 UserInfo 对象,包含用户 UID 和 User Account。详见 [UserInfo](/zh-CN/api-reference/rtc/unity/class-userinfo) 类。
### 所属接口类 [#所属接口类-32]
- [IRtcEngineEventHandler](/zh-CN/api-reference/rtc/unity/rtc-interface-class#class_irtcengineeventhandler)
## OnUserJoined [#onuserjoined]
远端用户(通信场景)/主播(直播场景)加入当前频道回调。
```csharp
public virtual void OnUserJoined(RtcConnection connection, uint remoteUid, int elapsed) {}
```
- 通信场景下,该回调提示有远端用户加入了频道。如果加入之前已经有其他用户在频道中,新加入的用户也会收到这些已有用户加入频道的回调。
- 直播场景下,该回调提示有主播加入了频道。如果加入之前,已经有主播在频道中了,新加入的用户也会收到已有主播加入频道的回调。建议连麦主播不超过 32 人(其中视频连麦主播不超过 17 人)。
### 触发时机 [#触发时机-7]
该回调在如下情况下会被触发:
- 远端用户/主播加入频道。
- 远端用户加入频道后将用户角色改变为主播。
- 远端用户/主播网络中断后重新加入频道。
### 参数 [#参数-33]
Connection 信息。详见 [RtcConnection](/zh-CN/api-reference/rtc/unity/class-rtcconnection)。
新加入频道的远端用户/主播 ID。
从本地用户调用 [JoinChannel [1/2]](/zh-CN/api-reference/rtc/unity/channel#api_irtcengine_joinchannel1) 或 [JoinChannel [2/2]](/zh-CN/api-reference/rtc/unity/channel#api_irtcengine_joinchannel2) 到该回调触发的延迟(毫秒)。
### 所属接口类 [#所属接口类-33]
- [IRtcEngineEventHandler](/zh-CN/api-reference/rtc/unity/rtc-interface-class#class_irtcengineeventhandler)
## OnUserOffline [#onuseroffline]
远端用户(通信场景)/主播(直播场景)离开当前频道回调。
```csharp
public virtual void OnUserOffline(RtcConnection connection, uint remoteUid, USER_OFFLINE_REASON_TYPE reason) {}
```
用户离开频道一般有以下两个原因:
- 正常离开:远端用户或主播会发送类似“再见”的消息然后主动离开频道。
- 超时掉线:在一定时间内(通信场景为 20 秒,直播场景稍有延时),用户没有收到对方的任何数据包,则判定为对方掉线。在网络较差的情况下,有可能会误报。建议使用 RTM SDK 来做可靠的掉线检测。
### 触发时机 [#触发时机-8]
在音视频互动过程中,当远端用户或主播离开当前频道时会触发该回调。
### 参数 [#参数-34]
Connection 信息。详见 [RtcConnection](/zh-CN/api-reference/rtc/unity/class-rtcconnection)。
离线的远端用户或主播的 ID。
远端用户(通信场景)或主播(直播场景)离线的原因,详见 [USER_OFFLINE_REASON_TYPE](/zh-CN/api-reference/rtc/unity/enum-userofflinereasontype)。
### 所属接口类 [#所属接口类-34]
- [IRtcEngineEventHandler](/zh-CN/api-reference/rtc/unity/rtc-interface-class#class_irtcengineeventhandler)