# 频道相关 (/zh-CN/api-reference/rtc/macos/channel) > For AI agents: see the complete documentation index at [llms.txt](/llms.txt). ## delegate [#delegate] 设置并获取 [AgoraRtcEngineDelegate](/zh-CN/api-reference/rtc/macos/rtc-interface-class#class_irtcengineeventhandler)。 ```objc @property(nonatomic, weak) id _Nullable delegate; ``` SDK 通过 [AgoraRtcEngineDelegate](/zh-CN/api-reference/rtc/macos/rtc-interface-class#class_irtcengineeventhandler) 类向 App 报告 SDK 运行时的各种事件。该类中定义的所有方法都是可选的实现方法。 ### 所属接口类 [#所属接口类] - [AgoraRtcEngineKit](/zh-CN/api-reference/rtc/macos/rtc-interface-class#class_irtcengine) ## getUserInfoByUid\:withError: [#getuserinfobyuidwitherror] 通过传入用户 ID 获取用户信息。 ```objc - (AgoraUserInfo* _Nullable)getUserInfoByUid:(NSUInteger)uid withError:(AgoraErrorCode* _Nullable)error NS_SWIFT_NAME(getUserInfo(byUid:withError:)); ``` 远端用户加入频道后,SDK 会获取该用户的用户 ID 和用户 User Account,并将其缓存在映射表对象中,同时在本地客户端触发 [rtcEngine\:didUserInfoUpdatedWithUserId\:userInfo:](/zh-CN/api-reference/rtc/macos/channel#callback_irtcengineeventhandler_onuserinfoupdated) 回调。收到该回调后,你可以调用 [getUserInfoByUid\:withError:](/zh-CN/api-reference/rtc/macos/channel#api_irtcengine_getuserinfobyuid) 方法并传入 `uid`,从 [AgoraUserInfo](/zh-CN/api-reference/rtc/macos/class-userinfo) 对象中获取指定用户的用户 User Account。 ### 调用时机 [#调用时机] 在收到 [rtcEngine\:didUserInfoUpdatedWithUserId\:userInfo:](/zh-CN/api-reference/rtc/macos/channel#callback_irtcengineeventhandler_onuserinfoupdated) 回调后调用该方法。 ### 参数 [#参数] 用户 ID。 错误码,详见 [AgoraErrorCode](/zh-CN/api-reference/rtc/macos/enum-errorcodetype)。 ### 返回值 [#返回值] - 方法调用成功,返回 [AgoraUserInfo](/zh-CN/api-reference/rtc/macos/class-userinfo) 对象,详见 [AgoraUserInfo](/zh-CN/api-reference/rtc/macos/class-userinfo)。 - 方法调用失败,返回 nil。 ### 所属接口类 [#所属接口类-1] - [AgoraRtcEngineKit](/zh-CN/api-reference/rtc/macos/rtc-interface-class#class_irtcengine) ## getUserInfoByUidEx\:connection\:withError: [#getuserinfobyuidexconnectionwitherror] 通过传入用户 ID 获取用户信息。 ```objc - (AgoraUserInfo* _Nullable)getUserInfoByUidEx:(NSUInteger)uid connection:(AgoraRtcConnection * _Nonnull)connection withError:(AgoraErrorCode* _Nullable)error NS_SWIFT_NAME(getUserInfo(byUidEx:connection:withError:)); ``` 远端用户加入频道后,SDK 会获取该远端用户的用户 ID 和用户 User Account,并将其缓存在映射表对象中,然后在本地客户端触发 [rtcEngine\:didUserInfoUpdatedWithUserId\:userInfo:](/zh-CN/api-reference/rtc/macos/channel#callback_irtcengineeventhandler_onuserinfoupdated) 回调。收到该回调后,你可以调用 [getUserInfoByUidEx\:connection\:withError:](/zh-CN/api-reference/rtc/macos/channel#api_irtcengineex_getuserinfobyuidex) 方法并传入 `uid`,从 [AgoraUserInfo](/zh-CN/api-reference/rtc/macos/class-userinfo) 对象中获取指定用户的用户 User Account。 ### 适用场景 [#适用场景] 适用于多频道场景。 ### 参数 [#参数-1] 用户 ID。 连接信息。详见 [AgoraRtcConnection](/zh-CN/api-reference/rtc/macos/class-rtcconnection)。 错误码。详见 [AgoraErrorCode](/zh-CN/api-reference/rtc/macos/enum-errorcodetype)。 ### 返回值 [#返回值-1] 方法调用成功,返回 [AgoraUserInfo](/zh-CN/api-reference/rtc/macos/class-userinfo) 对象。详见 [AgoraUserInfo](/zh-CN/api-reference/rtc/macos/class-userinfo)。 方法调用失败,返回 nil。 ### 所属接口类 [#所属接口类-2] - [AgoraRtcEngineKit(Ex)](/zh-CN/api-reference/rtc/macos/rtc-interface-class#class_irtcengineex) ## getUserInfoByUserAccount\:withError: [#getuserinfobyuseraccountwitherror] 通过传入用户 User Account 获取用户信息。 ```objc - (AgoraUserInfo* _Nullable)getUserInfoByUserAccount:(NSString* _Nonnull)userAccount withError:(AgoraErrorCode* _Nullable)error NS_SWIFT_NAME(getUserInfo(byUserAccount:withError:)); ``` 远端用户加入频道后,SDK 会获取该远端用户的用户 ID 和用户 User Account,并将其缓存在映射表对象中,然后在本地客户端触发 [rtcEngine\:didUserInfoUpdatedWithUserId\:userInfo:](/zh-CN/api-reference/rtc/macos/channel#callback_irtcengineeventhandler_onuserinfoupdated) 回调。你可以在收到该回调后调用 [getUserInfoByUserAccount\:withError:](/zh-CN/api-reference/rtc/macos/channel#api_irtcengine_getuserinfobyuseraccount) 方法,并传入用户 User Account,从 [AgoraUserInfo](/zh-CN/api-reference/rtc/macos/class-userinfo) 对象中获取远端用户的用户 ID,详见 [AgoraUserInfo](/zh-CN/api-reference/rtc/macos/class-userinfo)。 ### 调用时机 [#调用时机-1] 该方法应在收到 [rtcEngine\:didUserInfoUpdatedWithUserId\:userInfo:](/zh-CN/api-reference/rtc/macos/channel#callback_irtcengineeventhandler_onuserinfoupdated) 回调后调用。 ### 参数 [#参数-2] 用户 User Account。 错误码,详见 [AgoraErrorCode](/zh-CN/api-reference/rtc/macos/enum-errorcodetype)。 ### 返回值 [#返回值-2] - 方法调用成功,返回 [AgoraUserInfo](/zh-CN/api-reference/rtc/macos/class-userinfo) 对象,详见 [AgoraUserInfo](/zh-CN/api-reference/rtc/macos/class-userinfo)。 - 方法调用失败,返回 nil。 ### 所属接口类 [#所属接口类-3] - [AgoraRtcEngineKit](/zh-CN/api-reference/rtc/macos/rtc-interface-class#class_irtcengine) ## getUserInfoByUserAccountEx\:connection\:withError: [#getuserinfobyuseraccountexconnectionwitherror] 通过传入用户 User Account 获取用户信息。 ```objc - (AgoraUserInfo* _Nullable)getUserInfoByUserAccountEx:(NSString* _Nonnull)userAccount connection:(AgoraRtcConnection * _Nonnull)connection withError:(AgoraErrorCode* _Nullable)error NS_SWIFT_NAME(getUserInfo(byUserAccountEx:connection:withError:)); ``` 远端用户加入频道后,SDK 会获取该远端用户的用户 ID 和用户 User Account,并将其缓存在映射表对象中,然后在本地客户端触发 [rtcEngine\:didUserInfoUpdatedWithUserId\:userInfo:](/zh-CN/api-reference/rtc/macos/channel#callback_irtcengineeventhandler_onuserinfoupdated) 回调。收到该回调后,你可以调用该方法并传入用户 User Account,从 [AgoraUserInfo](/zh-CN/api-reference/rtc/macos/class-userinfo) 对象中获取指定用户的信息。 ### 适用场景 [#适用场景-1] 该方法适用于多频道场景。 ### 参数 [#参数-3] 用户 User Account。 连接信息。详见 [AgoraRtcConnection](/zh-CN/api-reference/rtc/macos/class-rtcconnection)。 错误码。详见 [AgoraErrorCode](/zh-CN/api-reference/rtc/macos/enum-errorcodetype)。 ### 返回值 [#返回值-3] 方法调用成功,返回指定用户的 [AgoraUserInfo](/zh-CN/api-reference/rtc/macos/class-userinfo) 对象。 ### 所属接口类 [#所属接口类-4] - [AgoraRtcEngineKit(Ex)](/zh-CN/api-reference/rtc/macos/rtc-interface-class#class_irtcengineex) ## joinChannelByToken\:channelId\:info\:uid\:joinSuccess: [#joinchannelbytokenchannelidinfouidjoinsuccess] 加入一个频道。 ```objc - (int)joinChannelByToken:(NSString * _Nullable)token channelId:(NSString * _Nonnull)channelId info:(NSString * _Nullable)info uid:(NSUInteger)uid joinSuccess:(void(^ _Nullable)(NSString * _Nonnull channel, NSUInteger uid, NSInteger elapsed))joinSuccessBlock NS_SWIFT_NAME(joinChannel(byToken:channelId:info:uid:joinSuccess:)); ``` 默认情况下,你会订阅频道中其他所有用户的音视频流,从而产生使用量和计费。如需停止订阅指定流或所有远端流,请调用 `muteRemoteAudio/VideoStream` 或 `muteAllRemoteAudio/VideoStreams`。请在调用 [sharedEngineWithConfig\:delegate:](/zh-CN/api-reference/rtc/macos/initialize#api_irtcengine_initialize) 方法后调用本方法。 :::note 注: 该方法每次仅支持加入一个频道。 不同 App ID 的用户无法互通。 加入频道前,请确保用于生成 Token 的 App ID 与传入 [sharedEngineWithConfig\:delegate:](/zh-CN/api-reference/rtc/macos/initialize#api_irtcengine_initialize) 方法中的 App ID 一致,否则可能导致加入频道失败。 ::: ### 调用时机 [#调用时机-2] 请在调用 [sharedEngineWithConfig\:delegate:](/zh-CN/api-reference/rtc/macos/initialize#api_irtcengine_initialize) 方法后调用本方法。 ### 相关回调 [#相关回调] 成功调用该方法后,SDK 会触发以下回调: - 本地客户端:[rtcEngine\:didJoinChannel\:withUid\:elapsed:](/zh-CN/api-reference/rtc/macos/channel#callback_irtcengineeventhandler_onjoinchannelsuccess) 和 [rtcEngine\:connectionChangedToState\:reason:](/zh-CN/api-reference/rtc/macos/network#callback_irtcengineeventhandler_onconnectionstatechanged)。 - 远端客户端:如果是 `COMMUNICATION` 频道场景中的用户加入,或 `LIVE_BROADCASTING` 频道场景中的主播加入频道,会触发 [rtcEngine\:didJoinedOfUid\:elapsed:](/zh-CN/api-reference/rtc/macos/channel#callback_irtcengineeventhandler_onuserjoined) 回调。 当本地客户端因网络状况不佳与声网服务器断开连接时,SDK 会尝试重连。当本地客户端成功重回频道时,SDK 会触发 [rtcEngine\:didRejoinChannel\:withUid\:elapsed:](/zh-CN/api-reference/rtc/macos/channel#callback_irtcengineeventhandler_onrejoinchannelsuccess) 回调。 ### 参数 [#参数-4] 在你的服务器上生成的用于鉴权的 Token。 :::note 注: (推荐)如果你的项目启用了安全模式(使用 App ID 和 Token 进行鉴权),该参数为必填。 如果你只启用了测试模式(使用 App ID 进行鉴权),该参数为可选。成功加入频道后,24 小时后会自动退出频道。 如果你需要同时加入多个频道或在频道之间切换,声网建议使用通配符 Token,这样你无需每次加入频道时都申请新的 Token。详见 `使用 Token 实现安全鉴权`。 ::: 频道名。该参数表示你进行实时音视频互动的频道。在相同 App ID 的前提下,填写相同频道名的用户会进入同一个频道进行音视频互动。字符串长度必须小于 64 字节。支持的字符(共 89 个): - 所有小写英文字母:a 到 z。 - 所有大写英文字母:A 到 Z。 - 所有数字字符:0 到 9。 - "!", "#", "$", "%", "&", "(", ")", "+", "-", ":", ";", "<", "=", ".", ">", "?", "@", "[", "]", "^", "_", "\{", "\}", "|", "~", ","。 (可选)预留参数 用户 ID。该参数用于标识频道内进行实时音视频互动的用户。你需要自行设置并管理用户 ID,确保同一频道内每个用户 ID 唯一。该参数为 32 位无符号整数,取值范围为 1 到 2³²-1。如果未指定用户 ID(或设置为 0),SDK 会自动分配一个随机用户 ID,并通过 [rtcEngine\:didJoinChannel\:withUid\:elapsed:](/zh-CN/api-reference/rtc/macos/channel#callback_irtcengineeventhandler_onjoinchannelsuccess) 回调返回。你必须记录并维护该返回的用户 ID,SDK 不会保存。 用户成功加入频道时触发。`joinSuccessBlock` 的优先级高于 [rtcEngine\:didJoinChannel\:withUid\:elapsed:](/zh-CN/api-reference/rtc/macos/channel#callback_irtcengineeventhandler_onjoinchannelsuccess)。当两者同时实现时,[rtcEngine\:didJoinChannel\:withUid\:elapsed:](/zh-CN/api-reference/rtc/macos/channel#callback_irtcengineeventhandler_onjoinchannelsuccess) 不生效。声网建议将 `joinSuccessBlock` 设置为 nil,以使用 [rtcEngine\:didJoinChannel\:withUid\:elapsed:](/zh-CN/api-reference/rtc/macos/channel#callback_irtcengineeventhandler_onjoinchannelsuccess)。 ### 返回值 [#返回值-4] - 0:方法调用成功。 - < 0:方法调用失败。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。 - -2:参数无效。例如,Token 无效,`uid` 参数未设置为整数,或 [AgoraRtcChannelMediaOptions](/zh-CN/api-reference/rtc/macos/class-channelmediaoptions) 中的成员值无效。请传入有效参数并重新加入频道。 - -3:初始化 [AgoraRtcEngineKit](/zh-CN/api-reference/rtc/macos/rtc-interface-class#class_irtcengine) 对象失败。请重新初始化该对象。 - -7:[AgoraRtcEngineKit](/zh-CN/api-reference/rtc/macos/rtc-interface-class#class_irtcengine) 对象尚未初始化。请先初始化该对象再调用本方法。 - -8:[AgoraRtcEngineKit](/zh-CN/api-reference/rtc/macos/rtc-interface-class#class_irtcengine) 对象的内部状态错误。常见原因是在调用 [startEchoTestWithConfig:](/zh-CN/api-reference/rtc/macos/network#api_irtcengine_startechotest3) 开始回声测试后,未调用 [stopEchoTest](/zh-CN/api-reference/rtc/macos/network#api_irtcengine_stopechotest) 停止测试就调用本方法加入频道。请先调用 [stopEchoTest](/zh-CN/api-reference/rtc/macos/network#api_irtcengine_stopechotest)。 - -17:加入频道请求被拒绝。常见原因是用户已在频道中。声网建议使用 [rtcEngine\:connectionChangedToState\:reason:](/zh-CN/api-reference/rtc/macos/network#callback_irtcengineeventhandler_onconnectionstatechanged) 回调判断用户是否在频道中。仅当收到 `AgoraConnectionStateDisconnected`(1)状态时再调用本方法。 - -102:频道名无效。请在 `channelId` 中传入有效频道名重新加入。 - -121:用户 ID 无效。请在 `uid` 中传入有效用户 ID 重新加入频道。 ### 所属接口类 [#所属接口类-5] - [AgoraRtcEngineKit](/zh-CN/api-reference/rtc/macos/rtc-interface-class#class_irtcengine) ## joinChannelByToken\:channelId\:uid\:mediaOptions\:joinSuccess: [#joinchannelbytokenchanneliduidmediaoptionsjoinsuccess] 加入频道并设置媒体选项。 ```objc - (int)joinChannelByToken:(NSString * _Nullable)token channelId:(NSString * _Nonnull)channelId uid:(NSUInteger)uid mediaOptions:(AgoraRtcChannelMediaOptions * _Nonnull)mediaOptions joinSuccess:(void(^ _Nullable)(NSString * _Nonnull channel, NSUInteger uid, NSInteger elapsed))joinSuccessBlock NS_SWIFT_NAME(joinChannel(byToken:channelId:uid:mediaOptions:joinSuccess:)); ``` 与 [joinChannelByToken\:channelId\:info\:uid\:joinSuccess:](/zh-CN/api-reference/rtc/macos/channel#api_irtcengine_joinchannel1) 方法相比,该方法新增了 `mediaOptions` 参数,用于设置媒体选项,例如是否在频道内发布音视频流,或在加入频道时是否自动订阅所有远端用户的音视频流。默认情况下,你会订阅频道中所有其他用户的音视频流,从而产生使用量和计费。如需停止订阅其他流,请设置 `mediaOptions` 参数或调用 `muteRemoteAudio/VideoStream` 或 `muteAllRemoteAudio/VideoStreams`。 :::note 注: - 该方法仅支持用户同时加入一个频道。 - 不同 App ID 的用户无法互通。 - 加入频道前,请确保用于生成 Token 的 App ID 与调用 [sharedEngineWithConfig\:delegate:](/zh-CN/api-reference/rtc/macos/initialize#api_irtcengine_initialize) 方法时传入的 App ID 一致,否则可能导致加入频道失败。 ::: ### 调用时机 [#调用时机-3] 请在调用 [sharedEngineWithConfig\:delegate:](/zh-CN/api-reference/rtc/macos/initialize#api_irtcengine_initialize) 之后调用该方法。 ### 相关回调 [#相关回调-1] 调用该方法成功后会触发以下回调: - 本地客户端:[rtcEngine\:didJoinChannel\:withUid\:elapsed:](/zh-CN/api-reference/rtc/macos/channel#callback_irtcengineeventhandler_onjoinchannelsuccess) 和 [rtcEngine\:connectionChangedToState\:reason:](/zh-CN/api-reference/rtc/macos/network#callback_irtcengineeventhandler_onconnectionstatechanged) 回调。 - 远端客户端:如果你在 `COMMUNICATION` 模式下加入频道,或作为主播在 `LIVE_BROADCASTING` 模式下加入频道,会触发 [rtcEngine\:didJoinedOfUid\:elapsed:](/zh-CN/api-reference/rtc/macos/channel#callback_irtcengineeventhandler_onuserjoined) 回调。 当由于网络状况不佳导致本地客户端与声网服务器的连接中断时,SDK 会尝试重新连接服务器。当本地客户端成功重回频道时,SDK 会在本地客户端触发 [rtcEngine\:didRejoinChannel\:withUid\:elapsed:](/zh-CN/api-reference/rtc/macos/channel#callback_irtcengineeventhandler_onrejoinchannelsuccess) 回调。 ### 参数 [#参数-5] 在你的服务器上生成的用于鉴权的 Token。 :::note 注: - (推荐)如果你的项目启用了安全模式(使用 App ID 和 Token 进行鉴权),该参数为必填。 - 如果你仅启用了测试模式(使用 App ID 进行鉴权),该参数为可选。成功加入频道后,你将在 24 小时后自动退出频道。 - 如果你需要同时加入不同频道或在频道间切换,声网建议使用通配符 Token,这样你无需每次加入频道时都申请新的 Token。 ::: 频道名。该参数表示你进行实时音视频互动的频道。在相同 App ID 的前提下,填写相同频道名的用户会进入同一个频道进行音视频互动。字符串长度必须小于 64 字节。支持的字符(共 89 个): - 所有小写英文字母:a 到 z。 - 所有大写英文字母:A 到 Z。 - 所有数字字符:0 到 9。 - "!", "#", "$", "%", "&", "(", ")", "+", "-", ":", ";", "<", "=", ".", ">", "?", "@", "[", "]", "^", "_", "\{", "\}", "|", "~", ","。 用户 ID。该参数用于标识频道内进行实时音视频互动的用户。你需要自行设置并管理用户 ID,确保同一频道内每个用户 ID 唯一。该参数为 32 位无符号整数,取值范围为 1 到 2³²-1。如果未指定用户 ID(或设置为 0),SDK 会自动分配一个随机用户 ID,并通过 [rtcEngine\:didJoinChannel\:withUid\:elapsed:](/zh-CN/api-reference/rtc/macos/channel#callback_irtcengineeventhandler_onjoinchannelsuccess) 回调返回。你必须记录并维护该返回的用户 ID,SDK 不会保存。 频道媒体选项。详见 [AgoraRtcChannelMediaOptions](/zh-CN/api-reference/rtc/macos/class-channelmediaoptions)。 用户加入频道成功时触发。`joinSuccessBlock` 的优先级高于 [rtcEngine\:didJoinChannel\:withUid\:elapsed:](/zh-CN/api-reference/rtc/macos/channel#callback_irtcengineeventhandler_onjoinchannelsuccess)。当两者同时实现时,[rtcEngine\:didJoinChannel\:withUid\:elapsed:](/zh-CN/api-reference/rtc/macos/channel#callback_irtcengineeventhandler_onjoinchannelsuccess) 不再生效。声网建议将 `joinSuccessBlock` 设置为 nil,以使用 [rtcEngine\:didJoinChannel\:withUid\:elapsed:](/zh-CN/api-reference/rtc/macos/channel#callback_irtcengineeventhandler_onjoinchannelsuccess)。 ### 返回值 [#返回值-5] 0:方法调用成功。 < 0:方法调用失败。 - -2:参数无效。例如,Token 无效,`uid` 参数未设置为整数,或 [AgoraRtcChannelMediaOptions](/zh-CN/api-reference/rtc/macos/class-channelmediaoptions) 中的成员值无效。你需要传入有效参数并重新加入频道。 - -3:初始化 [AgoraRtcEngineKit](/zh-CN/api-reference/rtc/macos/rtc-interface-class#class_irtcengine) 对象失败。你需要重新初始化该对象。 - -7:[AgoraRtcEngineKit](/zh-CN/api-reference/rtc/macos/rtc-interface-class#class_irtcengine) 对象尚未初始化。你需要先初始化该对象再调用该方法。 - -8:[AgoraRtcEngineKit](/zh-CN/api-reference/rtc/macos/rtc-interface-class#class_irtcengine) 对象的内部状态错误。典型原因是调用 [startEchoTestWithConfig:](/zh-CN/api-reference/rtc/macos/network#api_irtcengine_startechotest3) 开始通话回路测试后,未调用 [stopEchoTest](/zh-CN/api-reference/rtc/macos/network#api_irtcengine_stopechotest) 停止测试就调用该方法加入频道。你需要先调用 [stopEchoTest](/zh-CN/api-reference/rtc/macos/network#api_irtcengine_stopechotest) 再调用该方法。 - -17:加入频道请求被拒绝。典型原因是你已在频道中。声网建议你通过 [rtcEngine\:connectionChangedToState\:reason:](/zh-CN/api-reference/rtc/macos/network#callback_irtcengineeventhandler_onconnectionstatechanged) 回调判断是否在频道中。只有在收到 `AgoraConnectionStateDisconnected`(1)状态时才调用该方法加入频道。 - -102:频道名无效。你需要在 `channelId` 中传入有效的频道名重新加入频道。 - -121:用户 ID 无效。你需要在 `uid` 中传入有效的用户 ID 重新加入频道。 ### 所属接口类 [#所属接口类-6] - [AgoraRtcEngineKit](/zh-CN/api-reference/rtc/macos/rtc-interface-class#class_irtcengine) ## joinChannelExByToken\:connection\:delegate\:mediaOptions\:joinSuccess: [#joinchannelexbytokenconnectiondelegatemediaoptionsjoinsuccess] 使用 token 加入频道并设置媒体选项。 ```objc - (int)joinChannelExByToken:(NSString* _Nullable)token connection:(AgoraRtcConnection * _Nonnull)connection delegate:(id _Nullable)delegate mediaOptions:(AgoraRtcChannelMediaOptions* _Nonnull)mediaOptions joinSuccess:(void(^ _Nullable)(NSString* _Nonnull channel, NSUInteger uid, NSInteger elapsed))joinSuccessBlock NS_SWIFT_NAME(joinChannelEx(byToken:connection:delegate:mediaOptions:joinSuccess:)); ``` 在调用该方法之前,如果你尚未调用 `registerLocalUserAccountWithAppID:userAccount:` 注册用户 User Account,当你调用该方法加入频道时,SDK 会自动为你创建一个用户 User Account。先调用 `registerLocalUserAccountWithAppID:userAccount:` 注册用户 User Account,再调用该方法加入频道,可以缩短进入频道所需的时间。 一旦用户加入频道,默认会订阅频道中其他所有用户的音视频流,从而产生用量和计费。如果你希望停止订阅其他用户的媒体流,可以设置 `mediaOptions` 参数或调用 `muteRemoteAudio/VideoStream` 或 `muteAllRemoteAudio/VideoStreams`。 :::note 注: - 该方法仅支持用户同时加入一个频道。 - 不同 App ID 的用户无法互通。 - 加入频道前,请确保用于生成 token 的 App ID 与 [sharedEngineWithConfig\:delegate:](/zh-CN/api-reference/rtc/macos/initialize#api_irtcengine_initialize) 方法中传入的 App ID 一致,否则可能会导致使用该 token 加入频道失败。 - 为确保通信顺畅,请使用相同的参数类型标识用户。例如,如果某用户使用 UID 加入频道,则其他用户也应使用 UID。用户 User Account 同理。如果用户使用声网 Web SDK 加入频道,请确保用户 ID 的参数类型一致。 ::: ### 适用场景 [#适用场景-2] 该方法适用于多频道场景。 ### 调用时机 [#调用时机-4] 在调用 [sharedEngineWithConfig\:delegate:](/zh-CN/api-reference/rtc/macos/initialize#api_irtcengine_initialize) 之后调用该方法。 ### 相关回调 [#相关回调-2] - 本地客户端:[rtcEngine\:didLocalUserRegisteredWithUserId\:userAccount:](/zh-CN/api-reference/rtc/macos/channel#callback_irtcengineeventhandler_onlocaluserregistered)、[rtcEngine\:didJoinChannel\:withUid\:elapsed:](/zh-CN/api-reference/rtc/macos/channel#callback_irtcengineeventhandler_onjoinchannelsuccess) 和 [rtcEngine\:connectionChangedToState\:reason:](/zh-CN/api-reference/rtc/macos/network#callback_irtcengineeventhandler_onconnectionstatechanged) 回调。 - 远端客户端:当用户在 `COMMUNICATION` 频道场景中加入频道,或主播在 `LIVE_BROADCASTING` 频道场景中加入频道时,会触发 [rtcEngine\:didJoinedOfUid\:elapsed:](/zh-CN/api-reference/rtc/macos/channel#callback_irtcengineeventhandler_onuserjoined) 和 [rtcEngine\:didUserInfoUpdatedWithUserId\:userInfo:](/zh-CN/api-reference/rtc/macos/channel#callback_irtcengineeventhandler_onuserinfoupdated) 回调。 ### 参数 [#参数-6] 你在服务器上生成的用于鉴权的 token。 :::note 注: - (推荐)如果你的项目启用了安全模式(使用 App ID 和 token 进行鉴权),该参数为必填。 - 如果你只启用了测试模式(使用 App ID 进行鉴权),该参数为可选。成功加入频道后,你将在 24 小时后自动退出频道。 - 如果你需要同时加入多个频道或在频道之间切换,声网建议使用通配符 token,这样你无需每次加入频道时都申请新的 token。 ::: 连接信息。参见 [AgoraRtcConnection](/zh-CN/api-reference/rtc/macos/class-rtcconnection)。 `AgoraRtcEngine` 的回调类。参见 [AgoraRtcEngineDelegate](/zh-CN/api-reference/rtc/macos/rtc-interface-class#class_irtcengineeventhandler)。你可以通过该参数传入的 [delegate](/zh-CN/api-reference/rtc/macos/channel#api_irtcengine_delegate) 对象获取多个频道的回调事件。 频道媒体选项。参见 [AgoraRtcChannelMediaOptions](/zh-CN/api-reference/rtc/macos/class-channelmediaoptions)。 用户加入频道成功时触发。`joinSuccessBlock` 的优先级高于 [rtcEngine\:didJoinChannel\:withUid\:elapsed:](/zh-CN/api-reference/rtc/macos/channel#callback_irtcengineeventhandler_onjoinchannelsuccess)。当两者同时实现时,[rtcEngine\:didJoinChannel\:withUid\:elapsed:](/zh-CN/api-reference/rtc/macos/channel#callback_irtcengineeventhandler_onjoinchannelsuccess) 不生效。声网建议将 `joinSuccessBlock` 设置为 nil,以使用 [rtcEngine\:didJoinChannel\:withUid\:elapsed:](/zh-CN/api-reference/rtc/macos/channel#callback_irtcengineeventhandler_onjoinchannelsuccess)。 ### 返回值 [#返回值-6] 0:方法调用成功。 < 0:方法调用失败。 - -2:参数无效。例如,token 无效,`uid` 参数未设置为整数,或 [AgoraRtcChannelMediaOptions](/zh-CN/api-reference/rtc/macos/class-channelmediaoptions) 中某成员的值无效。请传入有效参数并重新加入频道。 - -3:初始化 [AgoraRtcEngineKit](/zh-CN/api-reference/rtc/macos/rtc-interface-class#class_irtcengine) 对象失败。请重新初始化该对象。 - -7:[AgoraRtcEngineKit](/zh-CN/api-reference/rtc/macos/rtc-interface-class#class_irtcengine) 对象尚未初始化。请在调用该方法前初始化该对象。 - -8:[AgoraRtcEngineKit](/zh-CN/api-reference/rtc/macos/rtc-interface-class#class_irtcengine) 对象的内部状态错误。常见原因是在调用 [startEchoTestWithConfig:](/zh-CN/api-reference/rtc/macos/network#api_irtcengine_startechotest3) 开始回声测试后,未调用 [stopEchoTest](/zh-CN/api-reference/rtc/macos/network#api_irtcengine_stopechotest) 停止测试就调用该方法加入频道。请先调用 [stopEchoTest](/zh-CN/api-reference/rtc/macos/network#api_irtcengine_stopechotest)。 - -17:加入频道请求被拒绝。常见原因是用户已在频道中。声网建议通过 [rtcEngine\:connectionChangedToState\:reason:](/zh-CN/api-reference/rtc/macos/network#callback_irtcengineeventhandler_onconnectionstatechanged) 回调判断用户是否在频道中。仅当收到 `AgoraConnectionStateDisconnected`(1)状态时再调用该方法。 - -102:频道名无效。请在 `channelId` 中传入有效的频道名重新加入频道。 - -121:用户 ID 无效。请在 `uid` 中传入有效的用户 ID 重新加入频道。 ### 所属接口类 [#所属接口类-7] - [AgoraRtcEngineKit(Ex)](/zh-CN/api-reference/rtc/macos/rtc-interface-class#class_irtcengineex) ## joinChannelByToken\:channelId\:userAccount\:joinSuccess: [#joinchannelbytokenchanneliduseraccountjoinsuccess] 使用用户 User Account 和 Token 加入频道。 ```objc - (int)joinChannelByToken:(NSString * _Nullable)token channelId:(NSString * _Nonnull)channelId userAccount:(NSString * _Nonnull)userAccount joinSuccess:(void(^ _Nullable)(NSString * _Nonnull channel, NSUInteger uid, NSInteger elapsed))joinSuccessBlock NS_SWIFT_NAME(joinChannel(byToken:channelId:userAccount:joinSuccess:)); ``` 在调用该方法之前,如果你尚未调用 `registerLocalUserAccountWithAppID:userAccount:` 注册用户 User Account,当你调用该方法加入频道时,SDK 会自动为你创建一个用户 User Account。先调用 `registerLocalUserAccountWithAppID:userAccount:` 注册用户 User Account,再调用该方法加入频道,可以缩短进入频道所需的时间。 一旦用户加入频道,默认会订阅频道中所有其他用户的音视频流,从而产生用量和计费。如需停止订阅指定或所有远端流,请调用 `muteRemoteAudio/VideoStream` 或 `muteAllRemoteAudio/VideoStreams`。 :::note 注: - 该方法仅支持用户同时加入一个频道。 - 不同 App ID 的用户无法互通。 - 加入频道前,请确保用于生成 Token 的 App ID 与调用 [sharedEngineWithConfig\:delegate:](/zh-CN/api-reference/rtc/macos/initialize#api_irtcengine_initialize) 时传入的 App ID 一致,否则可能导致使用该 Token 加入频道失败。 - 为确保通信顺畅,请统一使用相同的参数类型标识用户。例如,如果某用户使用用户 ID 加入频道,则其他用户也应使用用户 ID。用户 User Account 亦同理。如果用户使用声网 Web SDK 加入频道,请确保用户 ID 的参数类型一致。 ::: ### 调用时机 [#调用时机-5] 在调用 [sharedEngineWithConfig\:delegate:](/zh-CN/api-reference/rtc/macos/initialize#api_irtcengine_initialize) 之后调用该方法。 ### 相关回调 [#相关回调-3] 本地客户端:[rtcEngine\:didLocalUserRegisteredWithUserId\:userAccount:](/zh-CN/api-reference/rtc/macos/channel#callback_irtcengineeventhandler_onlocaluserregistered)、[rtcEngine\:didJoinChannel\:withUid\:elapsed:](/zh-CN/api-reference/rtc/macos/channel#callback_irtcengineeventhandler_onjoinchannelsuccess) 和 [rtcEngine\:connectionChangedToState\:reason:](/zh-CN/api-reference/rtc/macos/network#callback_irtcengineeventhandler_onconnectionstatechanged) 回调。 远端客户端:当用户在 `COMMUNICATION` 频道场景中加入频道,或主播在 `LIVE_BROADCASTING` 频道场景中加入频道时,会触发 [rtcEngine\:didJoinedOfUid\:elapsed:](/zh-CN/api-reference/rtc/macos/channel#callback_irtcengineeventhandler_onuserjoined) 和 [rtcEngine\:didUserInfoUpdatedWithUserId\:userInfo:](/zh-CN/api-reference/rtc/macos/channel#callback_irtcengineeventhandler_onuserinfoupdated) 回调。 ### 参数 [#参数-7] 在你的服务器上生成的用于鉴权的 Token。 :::note 注: - (推荐)如果你的项目启用了安全模式(使用 App ID 和 Token 进行鉴权),该参数为必填。 - 如果你仅启用了测试模式(使用 App ID 进行鉴权),该参数为可选。成功加入频道后,你将在 24 小时后自动退出频道。 - 如果你需要同时加入多个频道或在频道间切换,声网建议使用通配符 Token,这样你每次加入频道时无需重新申请 Token。 ::: 频道名。该参数表示用户进行实时音视频互动的频道。在相同 App ID 的前提下,填写相同频道名的用户会进入同一个频道进行音视频互动。字符串长度必须小于 64 字节。支持的字符(共 89 个): - 所有小写英文字母:a 到 z。 - 所有大写英文字母:A 到 Z。 - 所有数字字符:0 到 9。 - "!", "#", "$", "%", "&", "(", ")", "+", "-", ":", ";", "<", "=", ".", ">", "?", "@", "[", "]", "^", "_", "\{", "\}", "|", "~", ","。 用户 User Account。该参数用于标识频道中的用户以进行实时音视频互动。你需要自行设置和管理用户 User Account,并确保同一频道内的每个用户 User Account 唯一。该参数的最大长度为 255 字节。请确保设置了该参数,且不为 nil。支持的字符如下(共 89 个): - 26 个小写英文字母:a 到 z。 - 26 个大写英文字母:A 到 Z。 - 所有数字字符:0 到 9。 - 空格 - "!", "#", "$", "%", "&", "(", ")", "+", "-", ":", ";", "<", "=", ".", ">", "?", "@", "[", "]", "^", "_", "\{", "\}", "|", "~", ","。 用户成功加入频道回调。`joinSuccessBlock` 的优先级高于 [rtcEngine\:didJoinChannel\:withUid\:elapsed:](/zh-CN/api-reference/rtc/macos/channel#callback_irtcengineeventhandler_onjoinchannelsuccess)。当两者同时实现时,[rtcEngine\:didJoinChannel\:withUid\:elapsed:](/zh-CN/api-reference/rtc/macos/channel#callback_irtcengineeventhandler_onjoinchannelsuccess) 不生效。声网建议将 `joinSuccessBlock` 设置为 nil,以使用 [rtcEngine\:didJoinChannel\:withUid\:elapsed:](/zh-CN/api-reference/rtc/macos/channel#callback_irtcengineeventhandler_onjoinchannelsuccess)。 ### 返回值 [#返回值-7] - 0:方法调用成功。 - < 0:方法调用失败。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。 - -2:参数无效。例如,Token 无效,`uid` 参数未设置为整数,或 [AgoraRtcChannelMediaOptions](/zh-CN/api-reference/rtc/macos/class-channelmediaoptions) 中的成员值无效。你需要传入有效参数并重新加入频道。 - -3:初始化 [AgoraRtcEngineKit](/zh-CN/api-reference/rtc/macos/rtc-interface-class#class_irtcengine) 对象失败。你需要重新初始化该对象。 - -7:[AgoraRtcEngineKit](/zh-CN/api-reference/rtc/macos/rtc-interface-class#class_irtcengine) 对象尚未初始化。你需要先初始化该对象再调用该方法。 - -8:[AgoraRtcEngineKit](/zh-CN/api-reference/rtc/macos/rtc-interface-class#class_irtcengine) 对象的内部状态错误。典型原因是调用 [startEchoTestWithConfig:](/zh-CN/api-reference/rtc/macos/network#api_irtcengine_startechotest3) 开始回声测试后,未调用 [stopEchoTest](/zh-CN/api-reference/rtc/macos/network#api_irtcengine_stopechotest) 停止测试就调用该方法加入频道。你需要先调用 [stopEchoTest](/zh-CN/api-reference/rtc/macos/network#api_irtcengine_stopechotest) 再调用该方法。 - -17:加入频道请求被拒绝。典型原因是用户已在频道中。声网建议你通过 [rtcEngine\:connectionChangedToState\:reason:](/zh-CN/api-reference/rtc/macos/network#callback_irtcengineeventhandler_onconnectionstatechanged) 回调判断用户是否在频道中。只有在收到 `AgoraConnectionStateDisconnected`(1)状态时才调用该方法加入频道。 - -102:频道名无效。你需要在 `channelId` 中传入有效的频道名重新加入频道。 - -121:用户 ID 无效。你需要在 `uid` 中传入有效的用户 ID 重新加入频道。 ### 所属接口类 [#所属接口类-8] - [AgoraRtcEngineKit](/zh-CN/api-reference/rtc/macos/rtc-interface-class#class_irtcengine) ## joinChannelByToken\:channelId\:userAccount\:mediaOptions\:joinSuccess: [#joinchannelbytokenchanneliduseraccountmediaoptionsjoinsuccess] 使用用户 User Account 和 Token 加入频道,并设置媒体选项。 ```objc - (int)joinChannelByToken:(NSString * _Nullable)token channelId:(NSString * _Nonnull)channelId userAccount:(NSString * _Nonnull)userAccount mediaOptions:(AgoraRtcChannelMediaOptions * _Nonnull)mediaOptions joinSuccess:(void(^ _Nullable)(NSString * _Nonnull channel, NSUInteger uid, NSInteger elapsed))joinSuccessBlock NS_SWIFT_NAME(joinChannel(byToken:channelId:userAccount:mediaOptions:joinSuccess:)); ``` 在调用该方法之前,如果你尚未调用 `registerLocalUserAccountWithAppID:userAccount:` 注册用户 User Account,当你调用该方法加入频道时,SDK 会自动为你创建一个用户 User Account。先调用 `registerLocalUserAccountWithAppID:userAccount:` 注册用户 User Account,再调用该方法加入频道,可以缩短进入频道所需的时间。 与 [joinChannelByToken\:channelId\:userAccount\:joinSuccess:](/zh-CN/api-reference/rtc/macos/channel#api_irtcengine_joinchannelwithuseraccount1) 方法相比,该方法多了一个 `mediaOptions` 参数,用于设置媒体选项,例如是否在频道内发布音视频流。默认情况下,你会订阅频道内所有其他用户的音视频流,从而产生使用量和计费。若要停止订阅其他流,请设置 `mediaOptions` 参数或调用 `muteRemoteAudio/VideoStream` 或 `muteAllRemoteAudio/VideoStreams`。 :::note 注: - 该方法仅支持用户同时加入一个频道。 - 不同 App ID 的用户无法互通。 - 加入频道前,请确保用于生成 Token 的 App ID 与 [sharedEngineWithConfig\:delegate:](/zh-CN/api-reference/rtc/macos/initialize#api_irtcengine_initialize) 方法中传入的 App ID 一致,否则可能导致使用该 Token 加入频道失败。 - 为确保通信顺畅,请使用相同的参数类型标识用户。例如,如果某用户使用用户 ID 加入频道,则其他用户也应使用用户 ID。用户 User Account 同理。如果用户使用声网 Web SDK 加入频道,请确保用户 ID 的参数类型一致。 ::: ### 调用时机 [#调用时机-6] 请在调用 [sharedEngineWithConfig\:delegate:](/zh-CN/api-reference/rtc/macos/initialize#api_irtcengine_initialize) 之后调用该方法。 ### 相关回调 [#相关回调-4] 本地客户端:[rtcEngine\:didLocalUserRegisteredWithUserId\:userAccount:](/zh-CN/api-reference/rtc/macos/channel#callback_irtcengineeventhandler_onlocaluserregistered)、[rtcEngine\:didJoinChannel\:withUid\:elapsed:](/zh-CN/api-reference/rtc/macos/channel#callback_irtcengineeventhandler_onjoinchannelsuccess) 和 [rtcEngine\:connectionChangedToState\:reason:](/zh-CN/api-reference/rtc/macos/network#callback_irtcengineeventhandler_onconnectionstatechanged) 回调。 远端客户端:当用户在 `COMMUNICATION` 频道场景中加入频道,或主播在 `LIVE_BROADCASTING` 频道场景中加入频道时,会触发 [rtcEngine\:didJoinedOfUid\:elapsed:](/zh-CN/api-reference/rtc/macos/channel#callback_irtcengineeventhandler_onuserjoined) 和 [rtcEngine\:didUserInfoUpdatedWithUserId\:userInfo:](/zh-CN/api-reference/rtc/macos/channel#callback_irtcengineeventhandler_onuserinfoupdated) 回调。 ### 参数 [#参数-8] 在你的服务器上生成的用于鉴权的 Token。 :::note 注: - (推荐)如果你的项目启用了安全模式(使用 App ID 和 Token 进行鉴权),该参数为必填。 - 如果你只启用了测试模式(使用 App ID 进行鉴权),该参数为可选。成功加入频道后,你将在 24 小时后自动退出频道。 - 如果你需要同时加入多个频道或在频道间切换,声网建议使用通配符 Token,这样你无需每次加入频道时都申请新的 Token。 ::: 频道名。该参数表示你进行实时音视频互动的频道。在相同 App ID 的前提下,填写相同频道名的用户会进入同一个频道进行音视频互动。字符串长度必须小于 64 字节。支持的字符(共 89 个): - 所有小写英文字母:a 到 z。 - 所有大写英文字母:A 到 Z。 - 所有数字字符:0 到 9。 - "!", "#", "$", "%", "&", "(", ")", "+", "-", ":", ";", "<", "=", ".", ">", "?", "@", "[", "]", "^", "_", "\{", "\}", "|", "~", ","。 用户 User Account。该参数用于标识频道中的用户以进行实时音视频互动。你需要自行设置和管理用户 User Account,并确保同一频道内的每个用户 User Account 唯一。该参数的最大长度为 255 字节。支持的字符如下(共 89 个): - 26 个小写英文字母:a 到 z。 - 26 个大写英文字母:A 到 Z。 - 所有数字字符:0 到 9。 - 空格 - "!", "#", "$", "%", "&", "(", ")", "+", "-", ":", ";", "<", "=", ".", ">", "?", "@", "[", "]", "^", "_", "\{", "\}", "|", "~", ","。 频道媒体选项。详见 [AgoraRtcChannelMediaOptions](/zh-CN/api-reference/rtc/macos/class-channelmediaoptions)。 用户加入频道成功时触发。`joinSuccessBlock` 的优先级高于 [rtcEngine\:didJoinChannel\:withUid\:elapsed:](/zh-CN/api-reference/rtc/macos/channel#callback_irtcengineeventhandler_onjoinchannelsuccess)。当两者同时实现时,[rtcEngine\:didJoinChannel\:withUid\:elapsed:](/zh-CN/api-reference/rtc/macos/channel#callback_irtcengineeventhandler_onjoinchannelsuccess) 不生效。声网建议将 `joinSuccessBlock` 设置为 nil,以使用 [rtcEngine\:didJoinChannel\:withUid\:elapsed:](/zh-CN/api-reference/rtc/macos/channel#callback_irtcengineeventhandler_onjoinchannelsuccess)。 ### 返回值 [#返回值-8] 0:方法调用成功。 < 0:方法调用失败。 - -2:参数无效。例如,Token 无效,`uid` 参数未设置为整数,或 [AgoraRtcChannelMediaOptions](/zh-CN/api-reference/rtc/macos/class-channelmediaoptions) 中某成员的值无效。你需要传入有效参数并重新加入频道。 - -3:初始化 [AgoraRtcEngineKit](/zh-CN/api-reference/rtc/macos/rtc-interface-class#class_irtcengine) 对象失败。你需要重新初始化该对象。 - -7:[AgoraRtcEngineKit](/zh-CN/api-reference/rtc/macos/rtc-interface-class#class_irtcengine) 对象尚未初始化。你需要先初始化该对象再调用该方法。 - -8:[AgoraRtcEngineKit](/zh-CN/api-reference/rtc/macos/rtc-interface-class#class_irtcengine) 对象的内部状态错误。典型原因是调用 [startEchoTestWithConfig:](/zh-CN/api-reference/rtc/macos/network#api_irtcengine_startechotest3) 开始回声测试后,未调用 [stopEchoTest](/zh-CN/api-reference/rtc/macos/network#api_irtcengine_stopechotest) 停止测试就调用该方法加入频道。你需要先调用 [stopEchoTest](/zh-CN/api-reference/rtc/macos/network#api_irtcengine_stopechotest)。 - -17:加入频道请求被拒绝。典型原因是用户已在频道中。声网建议使用 [rtcEngine\:connectionChangedToState\:reason:](/zh-CN/api-reference/rtc/macos/network#callback_irtcengineeventhandler_onconnectionstatechanged) 回调判断用户是否在频道中。只有在收到 `AgoraConnectionStateDisconnected`(1)状态时才调用该方法。 - -102:频道名无效。你需要传入有效的 `channelId` 重新加入频道。 - -121:用户 ID 无效。你需要传入有效的 `uid` 重新加入频道。 ### 所属接口类 [#所属接口类-9] - [AgoraRtcEngineKit](/zh-CN/api-reference/rtc/macos/rtc-interface-class#class_irtcengine) ## joinChannelExByToken\:channelId\:userAccount\:delegate\:mediaOptions\:joinSuccess: [#joinchannelexbytokenchanneliduseraccountdelegatemediaoptionsjoinsuccess] 使用用户 User Account 和 Token 加入频道,并设置媒体选项。 ```objc - (int)joinChannelExByToken:(NSString* _Nullable)token channelId:(NSString* _Nonnull)channelId userAccount:(NSString* _Nonnull)userAccount delegate:(id _Nullable)delegate mediaOptions:(AgoraRtcChannelMediaOptions* _Nonnull)mediaOptions joinSuccess:(void(^ _Nullable)(NSString* _Nonnull channel, NSUInteger uid, NSInteger elapsed))joinSuccessBlock NS_SWIFT_NAME(joinChannelEx(byToken:channelId:userAccount:delegate:mediaOptions:joinSuccess:)); ``` 在调用该方法之前,如果你尚未调用 `registerLocalUserAccountWithAppID:userAccount:` 注册用户 User Account,当你调用该方法加入频道时,SDK 会自动为你创建一个用户 User Account。先调用 `registerLocalUserAccountWithAppID:userAccount:` 注册用户 User Account,再调用该方法加入频道,可以缩短进入频道所需的时间。 一旦你加入频道,默认会订阅频道中所有其他用户的音视频流,从而产生使用量和计费。如果你希望停止订阅其他用户的媒体流,可以设置 `mediaOptions` 参数或调用 `muteRemoteAudio/VideoStream` 或 `muteAllRemoteAudio/VideoStreams`。 :::note 注: - 该方法仅支持用户同时加入一个频道。 - 不同 App ID 的用户无法互通。 - 加入频道前,请确保用于生成 Token 的 App ID 与 [sharedEngineWithConfig\:delegate:](/zh-CN/api-reference/rtc/macos/initialize#api_irtcengine_initialize) 方法中传入的 App ID 一致,否则可能会导致使用该 Token 加入频道失败。 - 为确保通信顺畅,请使用相同的参数类型标识用户。例如,如果某用户使用 `uid` 加入频道,则其他用户也应使用 `uid`。用户 User Account 同理。如果用户使用声网 Web SDK 加入频道,请确保用户 ID 的参数类型一致。 ::: ### 适用场景 [#适用场景-3] 该方法适用于多频道场景。 ### 调用时机 [#调用时机-7] 在调用 [sharedEngineWithConfig\:delegate:](/zh-CN/api-reference/rtc/macos/initialize#api_irtcengine_initialize) 之后调用该方法。 ### 相关回调 [#相关回调-5] - 本地客户端:[rtcEngine\:didLocalUserRegisteredWithUserId\:userAccount:](/zh-CN/api-reference/rtc/macos/channel#callback_irtcengineeventhandler_onlocaluserregistered)、[rtcEngine\:didJoinChannel\:withUid\:elapsed:](/zh-CN/api-reference/rtc/macos/channel#callback_irtcengineeventhandler_onjoinchannelsuccess) 和 [rtcEngine\:connectionChangedToState\:reason:](/zh-CN/api-reference/rtc/macos/network#callback_irtcengineeventhandler_onconnectionstatechanged) 回调。 - 远端客户端:当用户在 `COMMUNICATION` 频道场景中加入频道,或主播在 `LIVE_BROADCASTING` 频道场景中加入频道时,会触发 [rtcEngine\:didJoinedOfUid\:elapsed:](/zh-CN/api-reference/rtc/macos/channel#callback_irtcengineeventhandler_onuserjoined) 和 [rtcEngine\:didUserInfoUpdatedWithUserId\:userInfo:](/zh-CN/api-reference/rtc/macos/channel#callback_irtcengineeventhandler_onuserinfoupdated) 回调。 ### 参数 [#参数-9] 在你的服务器上生成的用于鉴权的 Token。 :::note 注: - (推荐)如果你的项目启用了安全模式(使用 App ID 和 Token 进行鉴权),该参数为必填。 - 如果你只启用了测试模式(使用 App ID 进行鉴权),该参数为可选。成功加入频道后,24 小时后会自动退出频道。 - 如果你需要同时加入多个频道或在频道间切换,声网建议使用通配符 Token,这样每次加入频道时无需重新申请 Token。 ::: 频道名。该参数表示你进行实时音视频互动的频道。在相同 App ID 的前提下,填写相同频道名的用户会进入同一个频道进行音视频互动。字符串长度必须小于 64 字节。支持的字符(共 89 个): - 所有小写英文字母:a 到 z。 - 所有大写英文字母:A 到 Z。 - 所有数字字符:0 到 9。 - "!", "#", "$", "%", "&", "(", ")", "+", "-", ":", ";", "<", "=", ".", ">", "?", "@", "[", "]", "^", "_", "\{", "\}", "|", "~", ","。 用户 User Account。该参数用于标识频道中的用户以进行实时音视频互动。你需要自行设置和管理用户 User Account,并确保同一频道中的每个用户 User Account 唯一。该参数的最大长度为 255 字节。支持的字符如下(共 89 个): - 26 个小写英文字母:a 到 z。 - 26 个大写英文字母:A 到 Z。 - 所有数字字符:0 到 9。 - 空格 - "!", "#", "$", "%", "&", "(", ")", "+", "-", ":", ";", "<", "=", ".", ">", "?", "@", "[", "]", "^", "_", "\{", "\}", "|", "~", ","。 `AgoraRtcEngine` 的回调类。参见 [AgoraRtcEngineDelegate](/zh-CN/api-reference/rtc/macos/rtc-interface-class#class_irtcengineeventhandler)。你可以通过该参数传入的 [delegate](/zh-CN/api-reference/rtc/macos/channel#api_irtcengine_delegate) 对象获取多个频道的回调事件。 频道媒体选项。参见 [AgoraRtcChannelMediaOptions](/zh-CN/api-reference/rtc/macos/class-channelmediaoptions)。 用户加入频道成功时触发。`joinSuccessBlock` 的优先级高于 [rtcEngine\:didJoinChannel\:withUid\:elapsed:](/zh-CN/api-reference/rtc/macos/channel#callback_irtcengineeventhandler_onjoinchannelsuccess)。当两者同时实现时,[rtcEngine\:didJoinChannel\:withUid\:elapsed:](/zh-CN/api-reference/rtc/macos/channel#callback_irtcengineeventhandler_onjoinchannelsuccess) 不生效。声网建议将 `joinSuccessBlock` 设置为 nil,以使用 [rtcEngine\:didJoinChannel\:withUid\:elapsed:](/zh-CN/api-reference/rtc/macos/channel#callback_irtcengineeventhandler_onjoinchannelsuccess)。 ### 返回值 [#返回值-9] 0:方法调用成功。 < 0:方法调用失败。 - -2:参数无效。例如,Token 无效,`uid` 参数未设置为整数,或 [AgoraRtcChannelMediaOptions](/zh-CN/api-reference/rtc/macos/class-channelmediaoptions) 中某成员的值无效。请传入有效参数后重新加入频道。 - -3:初始化 [AgoraRtcEngineKit](/zh-CN/api-reference/rtc/macos/rtc-interface-class#class_irtcengine) 对象失败。请重新初始化该对象。 - -7:[AgoraRtcEngineKit](/zh-CN/api-reference/rtc/macos/rtc-interface-class#class_irtcengine) 对象尚未初始化。请先初始化该对象再调用该方法。 - -8:[AgoraRtcEngineKit](/zh-CN/api-reference/rtc/macos/rtc-interface-class#class_irtcengine) 对象的内部状态错误。典型原因是调用 [startEchoTestWithConfig:](/zh-CN/api-reference/rtc/macos/network#api_irtcengine_startechotest3) 开始回声测试后,未调用 [stopEchoTest](/zh-CN/api-reference/rtc/macos/network#api_irtcengine_stopechotest) 停止测试就调用该方法加入频道。请先调用 [stopEchoTest](/zh-CN/api-reference/rtc/macos/network#api_irtcengine_stopechotest) 再调用该方法。 - -17:加入频道请求被拒绝。典型原因是用户已在频道中。声网建议通过 [rtcEngine\:connectionChangedToState\:reason:](/zh-CN/api-reference/rtc/macos/network#callback_irtcengineeventhandler_onconnectionstatechanged) 回调判断用户是否在频道中。只有在收到 `AgoraConnectionStateDisconnected`(1)状态时才调用该方法加入频道。 - -102:频道名无效。请在 `channelId` 中传入有效的频道名后重新加入频道。 - -121:用户 ID 无效。请在 `uid` 中传入有效的用户 ID 后重新加入频道。 ### 所属接口类 [#所属接口类-10] - [AgoraRtcEngineKit(Ex)](/zh-CN/api-reference/rtc/macos/rtc-interface-class#class_irtcengineex) ## leaveChannel: [#leavechannel] 离开频道并释放资源。 ```objc - (int)leaveChannel:(void(^ _Nullable)(AgoraChannelStats * _Nonnull stat))leaveChannelBlock NS_SWIFT_NAME(leaveChannel(_:)); ``` 调用该方法后,SDK 会终止音视频互动,离开当前频道,并释放与会话相关的所有资源。加入频道后,必须调用该方法结束通话,否则无法开始下一次通话。 :::note 注: 如果在调用该方法后立即调用 [destroy](/zh-CN/api-reference/rtc/macos/initialize#api_irtcengine_release),SDK 不会触发 [rtcEngine\:didLeaveChannelWithStats:](/zh-CN/api-reference/rtc/macos/channel#callback_irtcengineeventhandler_onleavechannel) 回调。 - 该方法为异步调用。当该方法返回时,并不代表你已完全离开频道。 - 如果你调用了 `joinChannelExByToken` 加入了多个频道,调用该方法会离开你加入的所有频道。 ::: ### 调用时机 [#调用时机-8] 在加入频道后调用该方法。 ### 相关回调 [#相关回调-6] 调用该方法成功后会触发以下回调: - 本地客户端:会触发 [rtcEngine\:didLeaveChannelWithStats:](/zh-CN/api-reference/rtc/macos/channel#callback_irtcengineeventhandler_onleavechannel) 回调。 - 远端客户端:远端主播离开频道后会触发 [rtcEngine\:didOfflineOfUid\:reason:](/zh-CN/api-reference/rtc/macos/channel#callback_irtcengineeventhandler_onuseroffline) 回调。 ### 参数 [#参数-10] 该回调表示你离开频道,并在 [AgoraChannelStats](/zh-CN/api-reference/rtc/macos/class-rtcstats) 中提供通话统计信息。 ### 返回值 [#返回值-10] - 0:方法调用成功。 - < 0:方法调用失败。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。 - -1:发生一般性错误(无明确原因)。 - -2:参数无效。 - -7:SDK 未初始化。 ### 所属接口类 [#所属接口类-11] - [AgoraRtcEngineKit](/zh-CN/api-reference/rtc/macos/rtc-interface-class#class_irtcengine) ## leaveChannel\:leaveChannelBlock: [#leavechannelleavechannelblock] 设置频道选项并离开频道。 ```objc - (int)leaveChannel:(AgoraLeaveChannelOptions * _Nonnull)options leaveChannelBlock:(void (^ _Nullable)(AgoraChannelStats * _Nonnull))leaveChannelBlock NS_SWIFT_NAME(leaveChannel(_:leaveChannelBlock:)); ``` 调用该方法后,SDK 会终止音视频互动,离开当前频道,并释放与会话相关的所有资源。加入频道后,必须调用该方法或 [leaveChannel:](/zh-CN/api-reference/rtc/macos/channel#api_irtcengine_leavechannel) 来结束通话,否则无法开始下一次通话。如果你调用了 `joinChannelExByToken` 加入了多个频道,调用该方法会离开你加入的所有频道。 :::note 注: 如果在调用该方法后立即调用 [destroy](/zh-CN/api-reference/rtc/macos/initialize#api_irtcengine_release),SDK 不会触发 [rtcEngine\:didLeaveChannelWithStats:](/zh-CN/api-reference/rtc/macos/channel#callback_irtcengineeventhandler_onleavechannel) 回调。该方法为异步调用。当该方法返回时,并不意味着你已经离开频道。 ::: ### 调用时机 [#调用时机-9] 在加入频道后调用该方法。 ### 相关回调 [#相关回调-7] 调用该方法成功后会触发以下回调: - 本地客户端:会触发 [rtcEngine\:didLeaveChannelWithStats:](/zh-CN/api-reference/rtc/macos/channel#callback_irtcengineeventhandler_onleavechannel) 回调。 - 远端客户端:远端主播离开频道后会触发 [rtcEngine\:didOfflineOfUid\:reason:](/zh-CN/api-reference/rtc/macos/channel#callback_irtcengineeventhandler_onuseroffline) 回调。 ### 参数 [#参数-11] 离开频道的选项。详见 [AgoraLeaveChannelOptions](/zh-CN/api-reference/rtc/macos/class-leavechanneloptions)。 该回调表示你离开频道,并在 [AgoraChannelStats](/zh-CN/api-reference/rtc/macos/class-rtcstats) 中提供通话统计信息。 ### 返回值 [#返回值-11] - 0:方法调用成功。 - < 0:方法调用失败。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。 ### 所属接口类 [#所属接口类-12] - [AgoraRtcEngineKit](/zh-CN/api-reference/rtc/macos/rtc-interface-class#class_irtcengine) ## leaveChannelEx\:leaveChannelBlock: [#leavechannelexleavechannelblock] 离开频道并释放与会话相关的所有资源。 ```objc - (int)leaveChannelEx:(AgoraRtcConnection * _Nonnull)connection leaveChannelBlock:(void(^ _Nullable)(AgoraChannelStats* _Nonnull stat))leaveChannelBlock NS_SWIFT_NAME(leaveChannelEx(_:leaveChannelBlock:)); ``` 调用该方法后,SDK 会终止音视频互动,离开当前频道,并释放与会话相关的所有资源。调用 `joinChannelExByToken` 加入频道后,必须调用该方法或 [leaveChannelEx\:options\:leaveChannelBlock:](/zh-CN/api-reference/rtc/macos/channel#api_irtcengineex_leavechannelex2) 结束通话,否则无法开始下一次通话。 :::note 注: 如果在调用该方法后立即调用 [destroy](/zh-CN/api-reference/rtc/macos/initialize#api_irtcengine_release),SDK 不会触发 [rtcEngine\:didLeaveChannelWithStats:](/zh-CN/api-reference/rtc/macos/channel#callback_irtcengineeventhandler_onleavechannel) 回调。 - 此方法为异步调用。当该方法返回时,并不代表你已离开频道。 - 如果调用 [leaveChannel:](/zh-CN/api-reference/rtc/macos/channel#api_irtcengine_leavechannel) 或 [leaveChannel\:leaveChannelBlock:](/zh-CN/api-reference/rtc/macos/channel#api_irtcengine_leavechannel2),你将离开通过 `joinChannelByToken`、`joinChannelByToken` 或 `joinChannelExByToken` 加入的所有频道。 ::: ### 适用场景 [#适用场景-4] 该方法适用于多频道场景。 ### 调用时机 [#调用时机-10] 在调用 `joinChannelExByToken` 之后调用该方法。 ### 相关回调 [#相关回调-8] 调用该方法成功后会触发以下回调: - 本地客户端:触发 [rtcEngine\:didLeaveChannelWithStats:](/zh-CN/api-reference/rtc/macos/channel#callback_irtcengineeventhandler_onleavechannel) 回调。 - 远端客户端:远端主播离开频道后触发 [rtcEngine\:didOfflineOfUid\:reason:](/zh-CN/api-reference/rtc/macos/channel#callback_irtcengineeventhandler_onuseroffline) 回调。 ### 参数 [#参数-12] 连接信息。详见 [AgoraRtcConnection](/zh-CN/api-reference/rtc/macos/class-rtcconnection)。 离开频道回调。在 [AgoraChannelStats](/zh-CN/api-reference/rtc/macos/class-rtcstats) 中提供通话统计信息。 ### 返回值 [#返回值-12] - 0:方法调用成功。 - < 0:方法调用失败。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。 ### 所属接口类 [#所属接口类-13] - [AgoraRtcEngineKit(Ex)](/zh-CN/api-reference/rtc/macos/rtc-interface-class#class_irtcengineex) ## leaveChannelEx\:options\:leaveChannelBlock: [#leavechannelexoptionsleavechannelblock] 设置频道选项并离开频道。 ```objc - (int)leaveChannelEx:(AgoraRtcConnection * _Nonnull)connection options:(AgoraLeaveChannelOptions * _Nonnull)options leaveChannelBlock:(void(^ _Nullable)(AgoraChannelStats* _Nonnull stat))leaveChannelBlock; ``` :::info[自从] 自 v4.1.0 版本新增。 ::: 调用该方法后,SDK 会终止音视频互动,离开当前频道,并释放与会话相关的所有资源。调用 `joinChannelExByToken` 加入频道后,必须调用该方法或 [leaveChannelEx\:leaveChannelBlock:](/zh-CN/api-reference/rtc/macos/channel#api_irtcengineex_leavechannelex) 结束通话,否则无法开始下一次通话。 :::note 注: 如果在调用该方法后立即调用 [destroy](/zh-CN/api-reference/rtc/macos/initialize#api_irtcengine_release),SDK 不会触发 [rtcEngine\:didLeaveChannelWithStats:](/zh-CN/api-reference/rtc/macos/channel#callback_irtcengineeventhandler_onleavechannel) 回调。 - 此方法为异步调用。当该方法返回时,并不代表你已离开频道。 - 如果调用 [leaveChannel:](/zh-CN/api-reference/rtc/macos/channel#api_irtcengine_leavechannel) 或 [leaveChannel\:leaveChannelBlock:](/zh-CN/api-reference/rtc/macos/channel#api_irtcengine_leavechannel2),你将离开通过 `joinChannelByToken`、`joinChannelByToken` 或 `joinChannelExByToken` 加入的所有频道。 ::: ### 适用场景 [#适用场景-5] 该方法适用于多频道场景。 ### 调用时机 [#调用时机-11] 请在调用 `joinChannelExByToken` 之后调用该方法。 ### 参数 [#参数-13] 连接信息。详见 [AgoraRtcConnection](/zh-CN/api-reference/rtc/macos/class-rtcconnection)。 离开频道的选项。仅支持设置 [AgoraLeaveChannelOptions](/zh-CN/api-reference/rtc/macos/class-leavechanneloptions) 中的 `stopMicrophoneRecording` 成员,设置其他成员无效。详见 [AgoraLeaveChannelOptions](/zh-CN/api-reference/rtc/macos/class-leavechanneloptions)。 该回调表示你离开频道,并在 [AgoraChannelStats](/zh-CN/api-reference/rtc/macos/class-rtcstats) 中提供通话统计信息。详见 [AgoraChannelStats](/zh-CN/api-reference/rtc/macos/class-rtcstats)。 ### 返回值 [#返回值-13] 0:方法调用成功。 < 0:方法调用失败。 ### 所属接口类 [#所属接口类-14] - [AgoraRtcEngineKit(Ex)](/zh-CN/api-reference/rtc/macos/rtc-interface-class#class_irtcengineex) ## preloadChannelByToken\:channelId\:uid: [#preloadchannelbytokenchanneliduid] 预加载指定频道。 ```objc - (int)preloadChannelByToken:(NSString * _Nullable)token channelId:(NSString * _Nonnull)channelId uid:(NSUInteger)uid NS_SWIFT_NAME(preloadChannel(byToken:channelId:uid:)); ``` 该方法用于预加载指定频道。当你作为观众需要频繁切换频道时,调用该方法可以缩短加入频道的时间,从而减少你听到和看到主播的延迟。该方法需要在加入频道前调用。如果你加入了一个已预加载的频道,离开后想要重新加入该频道,除非用于预加载的 Token 过期,否则无需再次调用该方法。为提升预加载频道的用户体验,声网建议你在确认频道名和用户信息后尽早调用该方法。 :::note 注: - 调用该方法时,请确保将用户角色设置为观众,且未将音频场景设置为 `AgoraAudioScenarioChorus`,否则该方法不生效。 - 你还需要确保用于预加载的频道名、用户 ID 和 Token 与加入频道时传入的值一致,否则该方法不生效。 - 一个 [AgoraRtcEngineKit](/zh-CN/api-reference/rtc/macos/rtc-interface-class#class_irtcengine) 实例最多支持预加载 20 个频道,超出限制时,仅最近的 20 个预加载频道生效。 - 预加载频道失败并不意味着无法加入频道,也不会增加加入频道所需的时间。 ::: ### 调用时机 [#调用时机-12] 该方法需要在加入频道前调用。 ### 参数 [#参数-14] 在你的服务器上生成的用于鉴权的 Token。当用于预加载频道的 Token 过期时,你可以根据预加载的频道数量更新 Token。 - 如果只预加载一个频道,调用该方法传入新的 Token。 - 如果预加载多个频道: - 如果你为所有预加载频道使用通配符 Token,调用 [updatePreloadChannelToken:](/zh-CN/api-reference/rtc/macos/channel#api_irtcengine_updatepreloadchanneltoken) 更新 Token。 注意:生成通配符 Token 时,确保用户 ID 不为 0。 - 如果你为不同频道使用不同的 Token,调用该方法传入用户 ID、频道名和新的 Token。 你想要预加载的频道名。该参数表示用户进行实时音视频互动的频道。在相同 App ID 的前提下,填写相同频道名的用户会进入同一个频道进行音视频互动。字符串长度必须小于 64 字节。支持的字符(共 89 个): - 所有小写英文字母:a 到 z。 - 所有大写英文字母:A 到 Z。 - 所有数字字符:0 到 9。 - "!", "#", "$", "%", "&", "(", ")", "+", "-", ":", ";", "<", "=", ".", ">", "?", "@", "[", "]", "^", "_", "\{", "\}", "|", "~", ","。 用户 ID。该参数用于标识频道中的用户以进行实时音视频互动。你需要自行设置和管理用户 ID,并确保同一频道中的每个用户 ID 唯一。该参数为 32 位无符号整数,取值范围为 1 到 2³² - 1。如果未指定用户 ID(或设置为 0),SDK 会分配一个随机用户 ID,并在 [rtcEngine\:didJoinChannel\:withUid\:elapsed:](/zh-CN/api-reference/rtc/macos/channel#callback_irtcengineeventhandler_onjoinchannelsuccess) 回调中返回。你的应用必须记录并维护返回的用户 ID,SDK 不会保存该信息。 ### 返回值 [#返回值-14] - 0:方法调用成功。 - < 0:方法调用失败。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。 - -7:[AgoraRtcEngineKit](/zh-CN/api-reference/rtc/macos/rtc-interface-class#class_irtcengine) 对象尚未初始化。你需要先初始化该对象再调用此方法。 - -102:频道名无效。你需要传入有效的频道名并重新加入频道。 ### 所属接口类 [#所属接口类-15] - [AgoraRtcEngineKit](/zh-CN/api-reference/rtc/macos/rtc-interface-class#class_irtcengine) ## preloadChannelByTokenWithUserAccount\:channelId\:userAccount: [#preloadchannelbytokenwithuseraccountchanneliduseraccount] 预加载指定的频道以缩短观众加入频道的时间。 ```objc - (int)preloadChannelByTokenWithUserAccount:(NSString * _Nullable)token channelId:(NSString * _Nonnull)channelId userAccount:(NSString * _Nonnull)userAccount NS_SWIFT_NAME(preloadChannelWithUserAccount(byToken:channelId:userAccount:)); ``` 当你需要频繁切换不同频道时,调用该方法可以缩短加入频道的时间,从而减少你听到和看到主播的延迟。如果你加入了一个已预加载的频道,离开后想重新加入同一个频道,除非用于预加载频道的 Token 过期,否则无需再次调用该方法。声网建议你在确认频道名和用户信息后尽早调用该方法,以提升预加载频道的用户体验。 :::note 注: - 调用该方法时,请确保将用户角色设置为观众,且未将音频场景设置为 `AgoraAudioScenarioChorus`,否则该方法不生效。 - 你还需要确保用于预加载的用户 User Account、频道名和 Token 与加入频道时传入的值一致,否则该方法不生效。 - 一个 [AgoraRtcEngineKit](/zh-CN/api-reference/rtc/macos/rtc-interface-class#class_irtcengine) 实例最多支持预加载 20 个频道。超过该限制时,仅最近的 20 个预加载频道生效。 - 预加载频道失败并不意味着你无法加入频道,也不会增加加入频道所需的时间。 ::: ### 调用时机 [#调用时机-13] 该方法需要在加入频道前调用。 ### 参数 [#参数-15] 在你的服务器上生成的用于鉴权的 Token。当用于预加载频道的 Token 过期时,你可以根据预加载的频道数量更新 Token。 - 如果只预加载一个频道,调用该方法传入新的 Token。 - 如果预加载多个频道: - 如果你为所有预加载频道使用通配符 Token,调用 [updatePreloadChannelToken:](/zh-CN/api-reference/rtc/macos/channel#api_irtcengine_updatepreloadchanneltoken) 更新 Token。注意:生成通配符 Token 时,确保用户 ID 不为 0。 - 如果你为不同频道使用不同的 Token,调用该方法传入你的用户 ID、频道名和新的 Token。 你想要预加载的频道名。该参数表示用户进行实时音视频互动的频道。在相同 App ID 的前提下,填写相同频道名的用户会进入同一个频道进行音视频互动。字符串长度必须小于 64 字节。支持的字符(共 89 个): - 所有小写英文字母:a 到 z。 - 所有大写英文字母:A 到 Z。 - 所有数字字符:0 到 9。 - "!", "#", "$", "%", "&", "(", ")", "+", "-", ":", ";", "<", "=", ".", ">", "?", "@", "[", "]", "^", "_", "\{", "\}", "|", "~", ","。 用户 User Account。该参数用于标识频道中的用户以进行实时音视频互动。你需要自行设置和管理用户 User Account,并确保同一频道中的每个用户 User Account 唯一。该参数的最大长度为 255 字节。请确保设置了该参数,且不为 nil。支持的字符如下(共 89 个): - 26 个小写英文字母:a 到 z。 - 26 个大写英文字母:A 到 Z。 - 所有数字字符:0 到 9。 - 空格 - "!", "#", "$", "%", "&", "(", ")", "+", "-", ":", ";", "<", "=", ".", ">", "?", "@", "[", "]", "^", "_", "\{", "\}", "|", "~", ","。 ### 返回值 [#返回值-15] - 0:方法调用成功。 - < 0:方法调用失败。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。 - -2:参数无效,例如用户 User Account 为空。你需要传入有效参数并重新加入频道。 - -7:[AgoraRtcEngineKit](/zh-CN/api-reference/rtc/macos/rtc-interface-class#class_irtcengine) 对象尚未初始化。你需要在调用该方法前初始化该对象。 - -102:频道名无效。你需要传入有效的频道名并重新加入频道。 ### 所属接口类 [#所属接口类-16] - [AgoraRtcEngineKit](/zh-CN/api-reference/rtc/macos/rtc-interface-class#class_irtcengine) ## registerLocalUserAccount\:appId: [#registerlocaluseraccountappid] 注册用户 User Account。 ```objc - (int)registerLocalUserAccount:(NSString* _Nonnull)userAccount appId:(NSString* _Nonnull)appId NS_SWIFT_NAME(registerLocalUserAccount(_:appId:)); ``` [registerLocalUserAccount\:appId:](/zh-CN/api-reference/rtc/macos/channel#api_irtcengine_registerlocaluseraccount) 方法用于注册一个 `userAccount`,注册成功后,该 `userAccount` 可用于在加入频道时标识本地用户身份。 该方法为可选方法。如果你希望使用 `userAccount` 加入频道,可以选择以下任一方式: - 先调用 [registerLocalUserAccount\:appId:](/zh-CN/api-reference/rtc/macos/channel#api_irtcengine_registerlocaluseraccount) 方法注册一个 `userAccount`,再调用 [joinChannelByToken\:channelId\:userAccount\:joinSuccess:](/zh-CN/api-reference/rtc/macos/channel#api_irtcengine_joinchannelwithuseraccount1) 或 [joinChannelByToken\:channelId\:userAccount\:mediaOptions\:joinSuccess:](/zh-CN/api-reference/rtc/macos/channel#api_irtcengine_joinchannelwithuseraccount2) 方法加入频道,可缩短进入频道所需时间。 - 直接调用 [joinChannelByToken\:channelId\:userAccount\:joinSuccess:](/zh-CN/api-reference/rtc/macos/channel#api_irtcengine_joinchannelwithuseraccount1) 或 [joinChannelByToken\:channelId\:userAccount\:mediaOptions\:joinSuccess:](/zh-CN/api-reference/rtc/macos/channel#api_irtcengine_joinchannelwithuseraccount2) 方法加入频道。 调用该方法成功后,本地会触发 [rtcEngine\:didLocalUserRegisteredWithUserId\:userAccount:](/zh-CN/api-reference/rtc/macos/channel#callback_irtcengineeventhandler_onlocaluserregistered) 回调,报告本地用户的用户 ID 和 `userAccount`。 :::note 注: - 从 v4.6.0 起,SDK 不再自动将 `int` 类型的用户 ID 映射为注册时使用的 `string` 类型 `userAccount`。如果你希望使用注册时的原始 `userAccount` 加入频道,请调用 [joinChannelByToken\:channelId\:userAccount\:mediaOptions\:joinSuccess:](/zh-CN/api-reference/rtc/macos/channel#api_irtcengine_joinchannelwithuseraccount2) 方法,而不要调用 [joinChannelByToken\:channelId\:uid\:mediaOptions\:joinSuccess:](/zh-CN/api-reference/rtc/macos/channel#api_irtcengine_joinchannel2) 并传入通过该方法获取的 `int` 类型用户 ID。 - 请确保 `userAccount` 在频道中唯一。 - 为确保通信顺畅,请统一使用相同的参数类型标识用户。例如,如果某用户使用用户 ID 加入频道,则其他用户也应使用用户 ID;若使用 `userAccount`,则其他用户也应使用 `userAccount`。如果用户使用声网 Web SDK 加入频道,请确保用户 ID 的参数类型一致。 ::: ### 相关回调 [#相关回调-9] 调用该方法成功后,本地会触发 [rtcEngine\:didLocalUserRegisteredWithUserId\:userAccount:](/zh-CN/api-reference/rtc/macos/channel#callback_irtcengineeventhandler_onlocaluserregistered) 回调,报告本地用户的用户 ID 和 `userAccount`。 ### 参数 [#参数-16] 用于在频道中标识用户身份,以实现实时音视频互动。你需要自行设置并管理 `userAccount`,并确保同一频道中每个 `userAccount` 唯一。该参数的最大长度为 255 字节,不能为空。支持的字符如下(共 89 个): - 26 个小写英文字母:a 到 z。 - 26 个大写英文字母:A 到 Z。 - 所有数字字符:0 到 9。 - 空格 - "!"、"#"、"$"、"%"、"&"、"("、")"、"+"、"-"、":"、";"、"<"、"="、"."、">"、"?"、"@"、"["、"]"、"^"、"_"、"\{"、"\}"、"|"、"~"、","。 你在声网控制台项目中的 `App ID`。 ### 返回值 [#返回值-16] - 0:方法调用成功。 - < 0:方法调用失败。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。 ### 所属接口类 [#所属接口类-17] - [AgoraRtcEngineKit](/zh-CN/api-reference/rtc/macos/rtc-interface-class#class_irtcengine) ## renewToken: [#renewtoken] 更新 Token。 ```objc - (int)renewToken:(NSString * _Nonnull)token NS_SWIFT_NAME(renewToken(_:)); ``` 该方法用于更新 Token。调用该方法成功后,SDK 会触发 [rtcEngine\:renewTokenResult\:code:](/zh-CN/api-reference/rtc/macos/channel#callback_irtcengineeventhandler_onrenewtokenresult) 回调。 在单频道场景下,你可以在以下情况下调用该方法更新 Token: - 收到 [rtcEngine\:tokenPrivilegeWillExpire:](/zh-CN/api-reference/rtc/macos/channel#callback_irtcengineeventhandler_ontokenprivilegewillexpire) 回调,提示 Token 即将过期。 - Token 已过期时,SDK 会触发 [rtcEngineRequestToken:](/zh-CN/api-reference/rtc/macos/channel#callback_irtcengineeventhandler_onrequesttoken) 回调,并在 [rtcEngine\:connectionChangedToState\:reason:](/zh-CN/api-reference/rtc/macos/network#callback_irtcengineeventhandler_onconnectionstatechanged) 回调中将 `reason` 报告为 `AgoraConnectionChangedReasonTokenExpired`(9)。 ### 参数 [#参数-17] 新的 Token。 ### 返回值 [#返回值-17] - 0:方法调用成功。 - < 0:方法调用失败。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。 - -2:参数无效。例如,`token` 为空。 - -7:[AgoraRtcEngineKit](/zh-CN/api-reference/rtc/macos/rtc-interface-class#class_irtcengine) 对象尚未初始化。请在调用该方法前先初始化 [AgoraRtcEngineKit](/zh-CN/api-reference/rtc/macos/rtc-interface-class#class_irtcengine) 对象。 - 110:`token` 无效。请确保以下几点: - 生成 `token` 时指定的用户 ID 与加入频道时使用的用户 ID 一致。 - 生成的 `token` 与加入频道时传入的 `token` 一致。 ### 所属接口类 [#所属接口类-18] - [AgoraRtcEngineKit](/zh-CN/api-reference/rtc/macos/rtc-interface-class#class_irtcengine) ## setChannelProfile: [#setchannelprofile] 设置频道场景。 ```objc - (int)setChannelProfile:(AgoraChannelProfile)profile NS_SWIFT_NAME(setChannelProfile(_:)); ``` 你可以调用该方法设置频道场景。SDK 会针对不同的频道场景采用不同的优化策略。例如,在直播场景中,SDK 会优先保证视频质量。初始化 SDK 后,默认频道场景为直播。 :::note 注: - 为保证实时通信质量,声网建议频道内所有用户使用相同的频道场景。 - 在 iOS 平台,不同频道场景下 SDK 的默认音频路由不同,详见 `setDefaultAudioRouteToSpeakerphone:`。 ::: ### 调用时机 [#调用时机-14] 该方法需要在加入频道前调用。 ### 参数 [#参数-18] 频道场景。详见 [AgoraChannelProfile](/zh-CN/api-reference/rtc/macos/enum-channelprofiletype)。 ### 返回值 [#返回值-18] 0:方法调用成功。 < 0:方法调用失败。 - -2:参数无效。 - -7:SDK 尚未初始化。 ### 所属接口类 [#所属接口类-19] - [AgoraRtcEngineKit](/zh-CN/api-reference/rtc/macos/rtc-interface-class#class_irtcengine) ## setClientRole: [#setclientrole] 设置用户角色。 ```objc - (int)setClientRole:(AgoraClientRole)role NS_SWIFT_NAME(setClientRole(_:)); ``` 你可以调用该方法设置用户角色。默认情况下,SDK 会将用户角色设置为观众。用户角色决定了你在 SDK 层级的权限,包括是否可以在频道中发布音视频流。 你可以在加入频道前或加入频道后调用该方法: - 如果你在加入频道前调用该方法将用户角色设置为主播,并通过 [setupLocalVideo:](/zh-CN/api-reference/rtc/macos/video/video-rendering#api_irtcengine_setuplocalvideo) 设置本地视频属性,则用户加入频道时会自动开启本地视频预览。 - 如果你在加入频道后调用该方法设置用户角色,SDK 会自动调用 [muteLocalAudioStream:](/zh-CN/api-reference/rtc/macos/publishnsubscribe#api_irtcengine_mutelocalaudiostream) 和 [muteLocalVideoStream:](/zh-CN/api-reference/rtc/macos/publishnsubscribe#api_irtcengine_mutelocalvideostream) 更改音视频流的发布状态。 如果你在加入频道后调用该方法切换用户角色,SDK 会触发以下回调: - 本地客户端触发 [rtcEngine\:didClientRoleChanged\:newRole\:newRoleOptions:](/zh-CN/api-reference/rtc/macos/channel#callback_irtcengineeventhandler_onclientrolechanged) 回调。 - 注意:在加入频道前调用该方法并将 `role` 设置为 `AUDIENCE` 也会触发该回调。 - 远端客户端触发 [rtcEngine\:didJoinedOfUid\:elapsed:](/zh-CN/api-reference/rtc/macos/channel#callback_irtcengineeventhandler_onuserjoined) 或 [rtcEngine\:didOfflineOfUid\:reason:](/zh-CN/api-reference/rtc/macos/channel#callback_irtcengineeventhandler_onuseroffline) 回调。 如果你在加入频道后调用该方法设置用户角色失败,SDK 会触发 [rtcEngine\:didClientRoleChangeFailed\:currentRole:](/zh-CN/api-reference/rtc/macos/channel#callback_irtcengineeventhandler_onclientrolechangefailed) 回调,报告失败原因和当前角色。 ### 调用时机 [#调用时机-15] 你可以在加入频道前或加入频道后调用此方法。 ### 参数 [#参数-19] 用户角色。详见 [AgoraClientRole](/zh-CN/api-reference/rtc/macos/enum-clientroletype)。 :::note 注: 如果你将用户角色设置为观众,则无法在频道中发布音视频流。如果你希望在直播中发布媒体流,请确保将用户角色设置为主播。 ::: ### 返回值 [#返回值-19] - 0:方法调用成功。 - < 0:方法调用失败。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。 - -1:发生通用错误(无明确原因)。 - -2:参数无效。 - -7:SDK 未初始化。 ### 所属接口类 [#所属接口类-20] - [AgoraRtcEngineKit](/zh-CN/api-reference/rtc/macos/rtc-interface-class#class_irtcengine) ## setClientRole\:options: [#setclientroleoptions] 设置直播场景中的用户角色和观众延迟等级。 ```objc - (int)setClientRole:(AgoraClientRole)role options:(AgoraClientRoleOptions * _Nullable)options NS_SWIFT_NAME(setClientRole(_:options:)); ``` 你可以调用该方法设置用户角色为主播或观众。用户角色(`role`)决定了你在 SDK 层的权限,例如是否可以在频道中发布音视频流。 该方法相比 [setClientRole:](/zh-CN/api-reference/rtc/macos/channel#api_irtcengine_setclientrole1),支持设置 `audienceLatencyLevel`。你需要将 `audienceLatencyLevel` 与 `role` 搭配使用,以决定你在权限范围内可享受的服务等级。例如,观众可以选择接收低延迟或超低延迟的远端流。 如果你在加入频道前调用该方法将用户角色设置为主播,并通过 [setupLocalVideo:](/zh-CN/api-reference/rtc/macos/video/video-rendering#api_irtcengine_setuplocalvideo) 方法设置本地视频属性,则加入频道时会自动开启本地视频预览。 如果你在加入频道后调用该方法设置用户角色,SDK 会自动调用 [muteLocalAudioStream:](/zh-CN/api-reference/rtc/macos/publishnsubscribe#api_irtcengine_mutelocalaudiostream) 和 [muteLocalVideoStream:](/zh-CN/api-reference/rtc/macos/publishnsubscribe#api_irtcengine_mutelocalvideostream) 方法来改变音视频流的发布状态。 :::note 注: 当用户角色设置为主播时,观众延迟等级只能设置为 `AgoraAudienceLatencyLevelUltraLowLatency`。 - 在加入频道前调用此方法并将 `role` 设置为 `BROADCASTER` 时,本地客户端不会触发 [rtcEngine\:didClientRoleChanged\:newRole\:newRoleOptions:](/zh-CN/api-reference/rtc/macos/channel#callback_irtcengineeventhandler_onclientrolechanged) 回调。 - 在加入频道前调用此方法并将 `role` 设置为 `AUDIENCE` 时,会触发该回调。 ::: ### 调用时机 [#调用时机-16] 你可以在加入频道前或加入频道后调用此方法。 ### 相关回调 [#相关回调-10] 如果你在加入频道后调用此方法切换用户角色,SDK 会触发以下回调: - 在本地客户端触发 [rtcEngine\:didClientRoleChanged\:newRole\:newRoleOptions:](/zh-CN/api-reference/rtc/macos/channel#callback_irtcengineeventhandler_onclientrolechanged) 回调。 - 在远端客户端触发 [rtcEngine\:didJoinedOfUid\:elapsed:](/zh-CN/api-reference/rtc/macos/channel#callback_irtcengineeventhandler_onuserjoined) 或 [rtcEngine\:didOfflineOfUid\:reason:](/zh-CN/api-reference/rtc/macos/channel#callback_irtcengineeventhandler_onuseroffline) 回调。 如果你在加入频道后调用此方法设置用户角色但失败,SDK 会触发 [rtcEngine\:didClientRoleChangeFailed\:currentRole:](/zh-CN/api-reference/rtc/macos/channel#callback_irtcengineeventhandler_onclientrolechangefailed) 回调,报告失败原因和当前用户角色。注意:在加入频道前调用此方法并将 `role` 设置为 `AUDIENCE` 也会触发 [rtcEngine\:didClientRoleChanged\:newRole\:newRoleOptions:](/zh-CN/api-reference/rtc/macos/channel#callback_irtcengineeventhandler_onclientrolechanged) 回调。 ### 参数 [#参数-20] 用户角色。详见 [AgoraClientRole](/zh-CN/api-reference/rtc/macos/enum-clientroletype)。 :::note 注: 如果你将用户角色设置为观众,则无法在频道中发布音视频流。如果你希望在直播过程中发布媒体流,请确保将用户角色设置为主播。 ::: 用户的详细选项,包括用户等级。详见 [AgoraClientRoleOptions](/zh-CN/api-reference/rtc/macos/class-clientroleoptions)。 ### 返回值 [#返回值-20] 0:方法调用成功。 < 0:方法调用失败。 - -1:发生通用错误(无明确原因)。 - -2:参数无效。 - -5:请求被拒绝。 - -7:SDK 未初始化。 ### 所属接口类 [#所属接口类-21] - [AgoraRtcEngineKit](/zh-CN/api-reference/rtc/macos/rtc-interface-class#class_irtcengine) ## updateChannelWithMediaOptions: [#updatechannelwithmediaoptions] 加入频道后更新频道媒体选项。 ```objc - (int)updateChannelWithMediaOptions:(AgoraRtcChannelMediaOptions* _Nonnull)mediaOptions NS_SWIFT_NAME(updateChannel(with:)); ``` 你可以在加入频道后调用该方法更新频道媒体选项。 ### 参数 [#参数-21] 频道媒体选项。详见 [AgoraRtcChannelMediaOptions](/zh-CN/api-reference/rtc/macos/class-channelmediaoptions)。 ### 返回值 [#返回值-21] - 0:方法调用成功。 - < 0:方法调用失败。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。 - -2:[AgoraRtcChannelMediaOptions](/zh-CN/api-reference/rtc/macos/class-channelmediaoptions) 中某个成员的值无效,例如 token 或用户 ID 无效。你需要填写有效的参数。 - -7:[AgoraRtcEngineKit](/zh-CN/api-reference/rtc/macos/rtc-interface-class#class_irtcengine) 对象尚未初始化。你需要先初始化 [AgoraRtcEngineKit](/zh-CN/api-reference/rtc/macos/rtc-interface-class#class_irtcengine) 对象再调用该方法。 - -8:[AgoraRtcEngineKit](/zh-CN/api-reference/rtc/macos/rtc-interface-class#class_irtcengine) 对象的内部状态错误。可能的原因是你尚未加入频道。声网建议你通过 [rtcEngine\:connectionChangedToState\:reason:](/zh-CN/api-reference/rtc/macos/network#callback_irtcengineeventhandler_onconnectionstatechanged) 回调判断是否已加入频道。如果你收到 `AgoraConnectionStateDisconnected`(1)或 `AgoraConnectionStateFailed`(5)状态,说明你未加入频道。你需要先调用 [joinChannelByToken\:channelId\:uid\:mediaOptions\:joinSuccess:](/zh-CN/api-reference/rtc/macos/channel#api_irtcengine_joinchannel2) 加入频道,再调用该方法。 ### 所属接口类 [#所属接口类-22] - [AgoraRtcEngineKit](/zh-CN/api-reference/rtc/macos/rtc-interface-class#class_irtcengine) ## updateChannelExWithMediaOptions\:connection: [#updatechannelexwithmediaoptionsconnection] 加入频道后更新频道媒体选项。 ```objc - (int)updateChannelExWithMediaOptions:(AgoraRtcChannelMediaOptions* _Nonnull)mediaOptions connection:(AgoraRtcConnection * _Nonnull)connection NS_SWIFT_NAME(updateChannelEx(with:connection:)); ``` ### 适用场景 [#适用场景-6] 该方法适用于多频道场景。 ### 参数 [#参数-22] 频道媒体选项。详见 [AgoraRtcChannelMediaOptions](/zh-CN/api-reference/rtc/macos/class-channelmediaoptions)。 连接信息。详见 [AgoraRtcConnection](/zh-CN/api-reference/rtc/macos/class-rtcconnection)。 ### 返回值 [#返回值-22] - 0:方法调用成功。 - < 0:方法调用失败。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。 - -2:[AgoraRtcChannelMediaOptions](/zh-CN/api-reference/rtc/macos/class-channelmediaoptions) 中的成员值无效,例如 `token` 或用户 ID 无效。你需要填写有效的参数。 - -7:[AgoraRtcEngineKit](/zh-CN/api-reference/rtc/macos/rtc-interface-class#class_irtcengine) 对象尚未初始化。你需要先初始化 [AgoraRtcEngineKit](/zh-CN/api-reference/rtc/macos/rtc-interface-class#class_irtcengine) 对象再调用该方法。 - -8:[AgoraRtcEngineKit](/zh-CN/api-reference/rtc/macos/rtc-interface-class#class_irtcengine) 对象的内部状态错误,可能的原因是你尚未加入频道。声网建议你通过 [rtcEngine\:connectionChangedToState\:reason:](/zh-CN/api-reference/rtc/macos/network#callback_irtcengineeventhandler_onconnectionstatechanged) 回调判断是否已加入频道。如果你收到 `AgoraConnectionStateDisconnected`(1)或 `AgoraConnectionStateFailed`(5)状态,说明你尚未加入频道。你需要先调用 [joinChannelByToken\:channelId\:uid\:mediaOptions\:joinSuccess:](/zh-CN/api-reference/rtc/macos/channel#api_irtcengine_joinchannel2) 加入频道,再调用该方法。 ### 所属接口类 [#所属接口类-23] - [AgoraRtcEngineKit(Ex)](/zh-CN/api-reference/rtc/macos/rtc-interface-class#class_irtcengineex) ## updatePreloadChannelToken: [#updatepreloadchanneltoken] 更新预加载频道的通配 Token。 ```objc - (int)updatePreloadChannelToken:(NSString * _Nonnull)token NS_SWIFT_NAME(updatePreloadChannelToken(_:)); ``` 你需要自行维护通配 Token 的生命周期。当该 Token 过期时,你需要生成一个新的通配 Token,并调用此方法传入新的 Token。 ### 适用场景 [#适用场景-7] 适用于涉及多个频道的场景,例如在不同频道之间切换时,使用通配 Token 可以避免用户每次加入新频道时都申请新的 Token,从而节省切换频道的时间,并减轻你的 Token 服务器的压力。 ### 参数 [#参数-23] 新的 Token。 ### 返回值 [#返回值-23] - 0:方法调用成功。 - < 0:方法调用失败。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。 - -2:参数无效,例如 Token 无效。你需要传入有效的参数并重新加入频道。 - -7:[AgoraRtcEngineKit](/zh-CN/api-reference/rtc/macos/rtc-interface-class#class_irtcengine) 对象尚未初始化。你需要先初始化 [AgoraRtcEngineKit](/zh-CN/api-reference/rtc/macos/rtc-interface-class#class_irtcengine) 对象再调用此方法。 ### 所属接口类 [#所属接口类-24] - [AgoraRtcEngineKit](/zh-CN/api-reference/rtc/macos/rtc-interface-class#class_irtcengine) ## rtcEngine\:didClientRoleChanged\:newRole\:newRoleOptions: [#rtcenginedidclientrolechangednewrolenewroleoptions] 用户角色或观众延迟等级发生变化时触发的回调。 ```objc - (void)rtcEngine:(AgoraRtcEngineKit * _Nonnull)engine didClientRoleChanged:(AgoraClientRole)oldRole newRole:(AgoraClientRole)newRole newRoleOptions:(AgoraClientRoleOptions * _Nullable)newRoleOptions NS_SWIFT_NAME(rtcEngine(_:didClientRoleChanged:newRole:newRoleOptions:)); ``` :::note 注: 加入频道前调用 [setClientRole:](/zh-CN/api-reference/rtc/macos/channel#api_irtcengine_setclientrole1) 或 [setClientRole\:options:](/zh-CN/api-reference/rtc/macos/channel#api_irtcengine_setclientrole2) 并将用户角色设置为 `BROADCASTER` 时不会触发该回调。 ::: ### 触发时机 [#触发时机] 该回调会在以下任一情况下触发: - 在加入频道后调用 [setClientRole:](/zh-CN/api-reference/rtc/macos/channel#api_irtcengine_setclientrole1) 或 [setClientRole\:options:](/zh-CN/api-reference/rtc/macos/channel#api_irtcengine_setclientrole2) 设置用户角色或观众延迟等级。 - 在加入频道前调用 [setClientRole:](/zh-CN/api-reference/rtc/macos/channel#api_irtcengine_setclientrole1) 或 [setClientRole\:options:](/zh-CN/api-reference/rtc/macos/channel#api_irtcengine_setclientrole2) 并将用户角色设置为 `AUDIENCE`。 ### 参数 [#参数-24] 引擎实例。详见 [AgoraRtcEngineKit](/zh-CN/api-reference/rtc/macos/rtc-interface-class#class_irtcengine)。 用户切换前的角色。详见 [AgoraClientRole](/zh-CN/api-reference/rtc/macos/enum-clientroletype)。 用户切换后的角色。详见 [AgoraClientRole](/zh-CN/api-reference/rtc/macos/enum-clientroletype)。 用户切换后的角色属性。详见 [AgoraClientRoleOptions](/zh-CN/api-reference/rtc/macos/class-clientroleoptions)。 ### 所属接口类 [#所属接口类-25] - [AgoraRtcEngineDelegate](/zh-CN/api-reference/rtc/macos/rtc-interface-class#class_irtcengineeventhandler) ## rtcEngine\:didClientRoleChangeFailed\:currentRole: [#rtcenginedidclientrolechangefailedcurrentrole] 当切换用户角色失败时触发的回调。 ```objc - (void)rtcEngine:(AgoraRtcEngineKit * _Nonnull)engine didClientRoleChangeFailed:(AgoraClientRoleChangeFailedReason)reason currentRole:(AgoraClientRole)currentRole NS_SWIFT_NAME(rtcEngine(_:didClientRoleChangeFailed:currentRole:)); ``` ### 触发时机 [#触发时机-1] 该回调在你加入频道后调用 [setClientRole:](/zh-CN/api-reference/rtc/macos/channel#api_irtcengine_setclientrole1) 或 [setClientRole\:options:](/zh-CN/api-reference/rtc/macos/channel#api_irtcengine_setclientrole2) 切换用户角色但切换失败时被触发。 ### 参数 [#参数-25] 用户角色切换失败的原因,详见 [AgoraClientRoleChangeFailedReason](/zh-CN/api-reference/rtc/macos/enum-clientrolechangefailedreason)。 当前的用户角色,详见 [AgoraClientRole](/zh-CN/api-reference/rtc/macos/enum-clientroletype)。 ### 所属接口类 [#所属接口类-26] - [AgoraRtcEngineDelegate](/zh-CN/api-reference/rtc/macos/rtc-interface-class#class_irtcengineeventhandler) ## rtcEngine\:didOccurError: [#rtcenginedidoccurerror] 报告 SDK 运行时发生的错误回调。 ```objc - (void)rtcEngine:(AgoraRtcEngineKit * _Nonnull)engine didOccurError:(AgoraErrorCode)errorCode NS_SWIFT_NAME(rtcEngine(_:didOccurError:)); ``` 该回调在 SDK 运行过程中发生错误时触发。 ### 触发时机 [#触发时机-2] 该回调在 SDK 运行过程中发生错误时触发。 ### 参数 [#参数-26] [AgoraRtcEngineKit](/zh-CN/api-reference/rtc/macos/rtc-interface-class#class_irtcengine) 对象。详见 [AgoraRtcEngineKit](/zh-CN/api-reference/rtc/macos/rtc-interface-class#class_irtcengine)。 错误码。详见 [AgoraErrorCode](/zh-CN/api-reference/rtc/macos/enum-errorcodetype)。 ### 所属接口类 [#所属接口类-27] - [AgoraRtcEngineDelegate](/zh-CN/api-reference/rtc/macos/rtc-interface-class#class_irtcengineeventhandler) ## rtcEngine\:didJoinChannel\:withUid\:elapsed: [#rtcenginedidjoinchannelwithuidelapsed] 本地用户成功加入频道回调。 ```objc - (void)rtcEngine:(AgoraRtcEngineKit * _Nonnull)engine didJoinChannel:(NSString * _Nonnull)channel withUid:(NSUInteger)uid elapsed:(NSInteger)elapsed NS_SWIFT_NAME(rtcEngine(_:didJoinChannel:withUid:elapsed:)); ``` 该回调在本地用户成功加入指定频道时触发。 ### 触发时机 [#触发时机-3] 该回调在调用 `joinChannelByToken`、`joinChannelExByToken` 等方法加入频道时被触发。 ### 参数 [#参数-27] [AgoraRtcEngineKit](/zh-CN/api-reference/rtc/macos/rtc-interface-class#class_irtcengine) 对象,详见 [AgoraRtcEngineKit](/zh-CN/api-reference/rtc/macos/rtc-interface-class#class_irtcengine)。 频道名。 本地用户加入频道的用户 ID。 从调用 `joinChannelByToken` 方法到 SDK 触发该回调的时间间隔(毫秒)。 ### 所属接口类 [#所属接口类-28] - [AgoraRtcEngineDelegate](/zh-CN/api-reference/rtc/macos/rtc-interface-class#class_irtcengineeventhandler) ## rtcEngine\:didLeaveChannelWithStats: [#rtcenginedidleavechannelwithstats] 用户离开频道时的回调。 ```objc - (void)rtcEngine:(AgoraRtcEngineKit * _Nonnull)engine didLeaveChannelWithStats:(AgoraChannelStats * _Nonnull)stats NS_SWIFT_NAME(rtcEngine(_:didLeaveChannelWith:)); ``` 你可以通过该回调获取通话的总时长以及 SDK 的收发数据量。 ### 触发时机 [#触发时机-4] 该回调在你调用 [leaveChannel:](/zh-CN/api-reference/rtc/macos/channel#api_irtcengine_leavechannel)、[leaveChannel\:leaveChannelBlock:](/zh-CN/api-reference/rtc/macos/channel#api_irtcengine_leavechannel2)、[leaveChannelEx\:leaveChannelBlock:](/zh-CN/api-reference/rtc/macos/channel#api_irtcengineex_leavechannelex) 或 [leaveChannelEx\:options\:leaveChannelBlock:](/zh-CN/api-reference/rtc/macos/channel#api_irtcengineex_leavechannelex2) 离开频道后被触发。 ### 参数 [#参数-28] [AgoraRtcEngineKit](/zh-CN/api-reference/rtc/macos/rtc-interface-class#class_irtcengine) 对象。 通话统计信息,详见 [AgoraChannelStats](/zh-CN/api-reference/rtc/macos/class-rtcstats)。 ### 所属接口类 [#所属接口类-29] - [AgoraRtcEngineDelegate](/zh-CN/api-reference/rtc/macos/rtc-interface-class#class_irtcengineeventhandler) ## rtcEngine\:didLocalUserRegisteredWithUserId\:userAccount: [#rtcenginedidlocaluserregisteredwithuseriduseraccount] 本地用户注册用户 User Account 回调。 ```objc - (void)rtcEngine:(AgoraRtcEngineKit * _Nonnull)engine didLocalUserRegisteredWithUserId:(NSUInteger)uid userAccount:(NSString * _Nonnull)userAccount NS_SWIFT_NAME(rtcEngine(_:didLocalUserRegisteredWithUserId:userAccount:)); ``` 当你成功调用 `registerLocalUserAccountWithAppID:userAccount:` 方法注册用户 User Account,或调用 [joinChannelByToken\:channelId\:userAccount\:mediaOptions\:joinSuccess:](/zh-CN/api-reference/rtc/macos/channel#api_irtcengine_joinchannelwithuseraccount2) 方法加入频道后,SDK 会触发该回调,并返回你的用户 ID 和用户 User Account。 ### 触发时机 [#触发时机-5] 该回调在你注册用户 User Account 或加入频道成功后被触发。 ### 参数 [#参数-29] [AgoraRtcEngineKit](/zh-CN/api-reference/rtc/macos/rtc-interface-class#class_irtcengine) 对象,详见 [AgoraRtcEngineKit](/zh-CN/api-reference/rtc/macos/rtc-interface-class#class_irtcengine)。 本地用户的用户 ID。 本地用户的用户 User Account。 ### 所属接口类 [#所属接口类-30] - [AgoraRtcEngineDelegate](/zh-CN/api-reference/rtc/macos/rtc-interface-class#class_irtcengineeventhandler) ## rtcEngine\:didRejoinChannel\:withUid\:elapsed: [#rtcenginedidrejoinchannelwithuidelapsed] [rtcEngine\:didRejoinChannel\:withUid\:elapsed:](/zh-CN/api-reference/rtc/macos/channel#callback_irtcengineeventhandler_onrejoinchannelsuccess) 回调。当用户重新加入频道时触发。 ```objc - (void)rtcEngine:(AgoraRtcEngineKit * _Nonnull)engine didRejoinChannel:(NSString * _Nonnull)channel withUid:(NSUInteger)uid elapsed:(NSInteger)elapsed NS_SWIFT_NAME(rtcEngine(_:didRejoinChannel:withUid:elapsed:)); ``` ### 触发时机 [#触发时机-6] 该回调在因网络问题与服务器断开连接后,SDK 自动尝试重连并在重新连接成功时触发。 ### 参数 [#参数-30] 声网引擎对象。详见 [AgoraRtcEngineKit](/zh-CN/api-reference/rtc/macos/rtc-interface-class#class_irtcengine)。 频道名。 重新加入频道的用户 ID。 从调用 [joinChannelByToken\:channelId\:uid\:mediaOptions\:joinSuccess:](/zh-CN/api-reference/rtc/macos/channel#api_irtcengine_joinchannel2) 到 SDK 触发该回调所经过的时间(毫秒)。 ### 所属接口类 [#所属接口类-31] - [AgoraRtcEngineDelegate](/zh-CN/api-reference/rtc/macos/rtc-interface-class#class_irtcengineeventhandler) ## rtcEngine\:renewTokenResult\:code: [#rtcenginerenewtokenresultcode] [renewToken:](/zh-CN/api-reference/rtc/macos/channel#api_irtcengine_renewtoken) 方法调用结果的回调。 ```objc - (void)rtcEngine:(AgoraRtcEngineKit * _Nonnull)engine renewTokenResult:(NSString *_Nonnull)token code:(AgoraRenewTokenErrorCode)code NS_SWIFT_NAME(rtcEngine(_:renewTokenResult:code:)); ``` :::info[自从] 自 v4.6.0 版本新增。 ::: ### 触发时机 [#触发时机-7] 该回调在你调用 [renewToken:](/zh-CN/api-reference/rtc/macos/channel#api_irtcengine_renewtoken) 方法更新 Token 后被触发。 ### 参数 [#参数-31] [AgoraRtcEngineKit](/zh-CN/api-reference/rtc/macos/rtc-interface-class#class_irtcengine) 实例。详见 [AgoraRtcEngineKit](/zh-CN/api-reference/rtc/macos/rtc-interface-class#class_irtcengine)。 Token。 错误码,详见 [AgoraRenewTokenErrorCode](/zh-CN/api-reference/rtc/macos/enum-renewtokenerrorcode)。 ### 所属接口类 [#所属接口类-32] - [AgoraRtcEngineDelegate](/zh-CN/api-reference/rtc/macos/rtc-interface-class#class_irtcengineeventhandler) ## rtcEngineRequestToken: [#rtcenginerequesttoken] 当 Token 过期时触发的回调。 ```objc - (void)rtcEngineRequestToken:(AgoraRtcEngineKit * _Nonnull)engine NS_SWIFT_NAME(rtcEngineRequestToken(_:)); ``` 当 Token 过期时,SDK 会触发该回调。收到该回调后,你需要在你的 Token 服务器上生成一个新的 Token,并可以通过以下方式之一更新 Token: - 单频道场景: - 调用 [renewToken:](/zh-CN/api-reference/rtc/macos/channel#api_irtcengine_renewtoken) 传入新的 Token。 - 或调用 [updateChannelWithMediaOptions:](/zh-CN/api-reference/rtc/macos/channel#api_irtcengine_updatechannelmediaoptions),并在 [AgoraRtcChannelMediaOptions](/zh-CN/api-reference/rtc/macos/class-channelmediaoptions) 的 `token` 中传入新的 Token。 - 多频道场景:调用 [updateChannelExWithMediaOptions\:connection:](/zh-CN/api-reference/rtc/macos/channel#api_irtcengineex_updatechannelmediaoptionsex) 传入新的 Token。 ### 触发时机 [#触发时机-8] 当 Token 过期时触发。 ### 参数 [#参数-32] [AgoraRtcEngineKit](/zh-CN/api-reference/rtc/macos/rtc-interface-class#class_irtcengine) 对象。详见 [AgoraRtcEngineKit](/zh-CN/api-reference/rtc/macos/rtc-interface-class#class_irtcengine)。 ### 所属接口类 [#所属接口类-33] - [AgoraRtcEngineDelegate](/zh-CN/api-reference/rtc/macos/rtc-interface-class#class_irtcengineeventhandler) ## rtcEngine\:reportRtcStats: [#rtcenginereportrtcstats] 报告当前通话的统计信息。 ```objc - (void)rtcEngine:(AgoraRtcEngineKit * _Nonnull)engine reportRtcStats:(AgoraChannelStats * _Nonnull)stats NS_SWIFT_NAME(rtcEngine(_:reportRtcStats:)); ``` ### 触发时机 [#触发时机-9] 该回调在你加入频道后每两秒触发一次。 ### 参数 [#参数-33] [AgoraRtcEngineKit](/zh-CN/api-reference/rtc/macos/rtc-interface-class#class_irtcengine) 对象,详见 [AgoraRtcEngineKit](/zh-CN/api-reference/rtc/macos/rtc-interface-class#class_irtcengine)。 通话统计信息,详见 [AgoraChannelStats](/zh-CN/api-reference/rtc/macos/class-rtcstats)。 ### 所属接口类 [#所属接口类-34] - [AgoraRtcEngineDelegate](/zh-CN/api-reference/rtc/macos/rtc-interface-class#class_irtcengineeventhandler) ## rtcEngine\:tokenPrivilegeWillExpire: [#rtcenginetokenprivilegewillexpire] 当 Token 在 30 秒后过期时触发的回调。 ```objc - (void)rtcEngine:(AgoraRtcEngineKit * _Nonnull)engine tokenPrivilegeWillExpire:(NSString *_Nonnull)token NS_SWIFT_NAME(rtcEngine(_:tokenPrivilegeWillExpire:)); ``` 收到该回调时,你需要在你的 Token 服务器上生成新的 Token,并根据场景更新 Token: - 单频道场景: - 调用 [renewToken:](/zh-CN/api-reference/rtc/macos/channel#api_irtcengine_renewtoken) 传入新的 Token,无需先离开频道。SDK 会通过 [rtcEngine\:renewTokenResult\:code:](/zh-CN/api-reference/rtc/macos/channel#callback_irtcengineeventhandler_onrenewtokenresult) 回调报告更新结果。 - 如果你的 App 需要离开并重新加入频道,也可以调用 [leaveChannel\:leaveChannelBlock:](/zh-CN/api-reference/rtc/macos/channel#api_irtcengine_leavechannel2) 离开频道,然后在调用 [joinChannelByToken\:channelId\:uid\:mediaOptions\:joinSuccess:](/zh-CN/api-reference/rtc/macos/channel#api_irtcengine_joinchannel2) 时传入新的 Token。 - 多频道场景:调用 [updateChannelExWithMediaOptions\:connection:](/zh-CN/api-reference/rtc/macos/channel#api_irtcengineex_updatechannelmediaoptionsex) 传入新的 Token。 SDK 会在 Token 过期前 30 秒触发该回调,提醒应用更新 Token。 ### 触发时机 [#触发时机-10] 该回调在 Token 过期前 30 秒被触发,提醒你更新 Token。 ### 参数 [#参数-34] [AgoraRtcEngineKit](/zh-CN/api-reference/rtc/macos/rtc-interface-class#class_irtcengine) 对象,详见 [AgoraRtcEngineKit](/zh-CN/api-reference/rtc/macos/rtc-interface-class#class_irtcengine)。 即将过期的 Token。 ### 所属接口类 [#所属接口类-35] - [AgoraRtcEngineDelegate](/zh-CN/api-reference/rtc/macos/rtc-interface-class#class_irtcengineeventhandler) ## rtcEngine\:didUserInfoUpdatedWithUserId\:userInfo: [#rtcenginediduserinfoupdatedwithuseriduserinfo] 当 SDK 获取到远端用户的用户 ID 和用户 User Account 时触发。 ```objc - (void)rtcEngine:(AgoraRtcEngineKit * _Nonnull)engine didUserInfoUpdatedWithUserId:(NSUInteger)uid userInfo:(AgoraUserInfo* _Nonnull)userInfo NS_SWIFT_NAME(rtcEngine(_:didUserInfoUpdatedWithUserId:userInfo:)); ``` 远端用户加入频道后,SDK 会获取该远端用户的用户 ID 和用户 User Account,并将其缓存在映射表对象中,然后在本地客户端触发该回调。 ### 触发时机 [#触发时机-11] 该回调在远端用户加入频道后,SDK 获取到其用户 ID 和用户 User Account 时被触发。 ### 参数 [#参数-35] [AgoraRtcEngineKit](/zh-CN/api-reference/rtc/macos/rtc-interface-class#class_irtcengine) 对象。详见 [AgoraRtcEngineKit](/zh-CN/api-reference/rtc/macos/rtc-interface-class#class_irtcengine)。 远端用户的用户 ID。 包含远端用户的用户 ID 和用户 User Account 的对象。详见 [AgoraUserInfo](/zh-CN/api-reference/rtc/macos/class-userinfo)。 ### 所属接口类 [#所属接口类-36] - [AgoraRtcEngineDelegate](/zh-CN/api-reference/rtc/macos/rtc-interface-class#class_irtcengineeventhandler) ## rtcEngine\:didJoinedOfUid\:elapsed: [#rtcenginedidjoinedofuidelapsed] 远端用户或主播加入频道回调。 ```objc - (void)rtcEngine:(AgoraRtcEngineKit * _Nonnull)engine didJoinedOfUid:(NSUInteger)uid elapsed:(NSInteger)elapsed NS_SWIFT_NAME(rtcEngine(_:didJoinedOfUid:elapsed:)); ``` 在通信频道中,该回调表示有远端用户加入频道。当你加入频道时,SDK 也会触发该回调报告频道中已有的用户。 在直播频道中,该回调表示有主播加入频道。声网建议将连麦主播数量限制为 32 人,最多支持 17 路视频主播。 ### 触发时机 [#触发时机-12] 该回调在以下任一情况下被触发: - 有远端用户或主播加入频道。 - 远端用户加入频道后将用户角色切换为主播。 - 远端用户或主播在网络中断后重新加入频道。 ### 参数 [#参数-36] [AgoraRtcEngineKit](/zh-CN/api-reference/rtc/macos/rtc-interface-class#class_irtcengine) 对象。详见 [AgoraRtcEngineKit](/zh-CN/api-reference/rtc/macos/rtc-interface-class#class_irtcengine)。 加入频道的用户或主播的 ID。 从你调用 [joinChannelByToken\:channelId\:info\:uid\:joinSuccess:](/zh-CN/api-reference/rtc/macos/channel#api_irtcengine_joinchannel1) 或 [joinChannelByToken\:channelId\:uid\:mediaOptions\:joinSuccess:](/zh-CN/api-reference/rtc/macos/channel#api_irtcengine_joinchannel2) 到该回调被触发的延迟时间(毫秒)。 ### 所属接口类 [#所属接口类-37] - [AgoraRtcEngineDelegate](/zh-CN/api-reference/rtc/macos/rtc-interface-class#class_irtcengineeventhandler) ## rtcEngine\:didOfflineOfUid\:reason: [#rtcenginedidofflineofuidreason] 远端用户或主播离开频道时的回调。 ```objc - (void)rtcEngine:(AgoraRtcEngineKit * _Nonnull)engine didOfflineOfUid:(NSUInteger)uid reason:(AgoraUserOfflineReason)reason NS_SWIFT_NAME(rtcEngine(_:didOfflineOfUid:reason:)); ``` 用户离线通常有两个原因: - 离开频道:当用户或主播离开频道时,会发送离开消息。 - 掉线:在一段时间内(通信场景为 20 秒,直播场景更长)未收到用户或主播的数据包时,SDK 会认为其掉线。网络连接不佳可能导致误判。建议使用声网 RTM SDK 进行可靠的离线检测。 ### 触发时机 [#触发时机-13] 该回调在远端用户(在通信场景中)或主播(在直播场景中)离开频道时触发。 ### 参数 [#参数-37] [AgoraRtcEngineKit](/zh-CN/api-reference/rtc/macos/rtc-interface-class#class_irtcengine) 对象,详见 [AgoraRtcEngineKit](/zh-CN/api-reference/rtc/macos/rtc-interface-class#class_irtcengine)。 离开频道或掉线的远端用户 ID。 远端用户(在通信场景中)或主播(在直播场景中)离线的原因,详见 [AgoraUserOfflineReason](/zh-CN/api-reference/rtc/macos/enum-userofflinereasontype)。 ### 所属接口类 [#所属接口类-38] - [AgoraRtcEngineDelegate](/zh-CN/api-reference/rtc/macos/rtc-interface-class#class_irtcengineeventhandler)