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

频道相关

  • macOS

更新时间不可用

delegate

设置并获取 AgoraRtcEngineDelegate。

Objective-C
@property(nonatomic, weak) id<AgoraRtcEngineDelegate> _Nullable delegate;

SDK 通过 AgoraRtcEngineDelegate 类向 App 报告 SDK 运行时的各种事件。该类中定义的所有方法都是可选的实现方法。

所属接口类

getUserInfoByUid:withError:

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

Objective-C
- (AgoraUserInfo* _Nullable)getUserInfoByUid:(NSUInteger)uid withError:(AgoraErrorCode* _Nullable)error NS_SWIFT_NAME(getUserInfo(byUid:withError:));

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

调用时机

在收到 rtcEngine:didUserInfoUpdatedWithUserId:userInfo: 回调后调用该方法。

参数

参数名描述
uid

用户 ID。

error

错误码，详见 AgoraErrorCode。

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

返回值

所属接口类

getUserInfoByUidEx:connection:withError:

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

Objective-C
- (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: 回调。收到该回调后，你可以调用 getUserInfoByUidEx:connection:withError: 方法并传入 uid，从 AgoraUserInfo 对象中获取指定用户的用户 User Account。

适用场景

适用于多频道场景。

参数

参数名描述
uid

用户 ID。

connection

连接信息。详见 AgoraRtcConnection。

error

错误码。详见 AgoraErrorCode。

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

返回值

方法调用成功，返回 AgoraUserInfo 对象。详见 AgoraUserInfo。 方法调用失败，返回 nil。

所属接口类

getUserInfoByUserAccount:withError:

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

Objective-C
- (AgoraUserInfo* _Nullable)getUserInfoByUserAccount:(NSString* _Nonnull)userAccount withError:(AgoraErrorCode* _Nullable)error NS_SWIFT_NAME(getUserInfo(byUserAccount:withError:));

远端用户加入频道后，SDK 会获取该远端用户的用户 ID 和用户 User Account，并将其缓存在映射表对象中，然后在本地客户端触发 rtcEngine:didUserInfoUpdatedWithUserId:userInfo: 回调。你可以在收到该回调后调用 getUserInfoByUserAccount:withError: 方法，并传入用户 User Account，从 AgoraUserInfo 对象中获取远端用户的用户 ID，详见 AgoraUserInfo。

调用时机

该方法应在收到 rtcEngine:didUserInfoUpdatedWithUserId:userInfo: 回调后调用。

参数

参数名描述
userAccount

用户 User Account。

error

错误码，详见 AgoraErrorCode。

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

返回值

所属接口类

getUserInfoByUserAccountEx:connection:withError:

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

Objective-C
- (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: 回调。收到该回调后，你可以调用该方法并传入用户 User Account，从 AgoraUserInfo 对象中获取指定用户的信息。

适用场景

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

参数

参数名描述
userAccount

用户 User Account。

connection

连接信息。详见 AgoraRtcConnection。

error

错误码。详见 AgoraErrorCode。

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

返回值

方法调用成功，返回指定用户的 AgoraUserInfo 对象。

所属接口类

joinChannelByToken:channelId:info:uid:joinSuccess:

加入一个频道。

Objective-C
- (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: 方法后调用本方法。

注： 该方法每次仅支持加入一个频道。 不同 App ID 的用户无法互通。 加入频道前，请确保用于生成 Token 的 App ID 与传入 sharedEngineWithConfig:delegate: 方法中的 App ID 一致，否则可能导致加入频道失败。

调用时机

请在调用 sharedEngineWithConfig:delegate: 方法后调用本方法。

相关回调

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

当本地客户端因网络状况不佳与声网服务器断开连接时，SDK 会尝试重连。当本地客户端成功重回频道时，SDK 会触发 rtcEngine:didRejoinChannel:withUid:elapsed: 回调。

参数

参数名描述
token

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

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

channelId

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

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

（可选）预留参数

uid

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

joinSuccessBlock

用户成功加入频道时触发。joinSuccessBlock 的优先级高于 rtcEngine:didJoinChannel:withUid:elapsed:。当两者同时实现时，rtcEngine:didJoinChannel:withUid:elapsed: 不生效。声网建议将 joinSuccessBlock 设置为 nil，以使用 rtcEngine:didJoinChannel:withUid:elapsed:。

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

返回值

  • 0：方法调用成功。

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

    • -2：参数无效。例如，Token 无效，uid 参数未设置为整数，或 AgoraRtcChannelMediaOptions 中的成员值无效。请传入有效参数并重新加入频道。
    • -3：初始化 AgoraRtcEngineKit 对象失败。请重新初始化该对象。
    • -7：AgoraRtcEngineKit 对象尚未初始化。请先初始化该对象再调用本方法。
    • -8：AgoraRtcEngineKit 对象的内部状态错误。常见原因是在调用 startEchoTestWithConfig: 开始回声测试后，未调用 stopEchoTest 停止测试就调用本方法加入频道。请先调用 stopEchoTest。
    • -17：加入频道请求被拒绝。常见原因是用户已在频道中。声网建议使用 rtcEngine:connectionChangedToState:reason: 回调判断用户是否在频道中。仅当收到 AgoraConnectionStateDisconnected（1）状态时再调用本方法。
    • -102：频道名无效。请在 channelId 中传入有效频道名重新加入。
    • -121：用户 ID 无效。请在 uid 中传入有效用户 ID 重新加入频道。

所属接口类

joinChannelByToken:channelId:uid:mediaOptions:joinSuccess:

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

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

注：

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

调用时机

请在调用 sharedEngineWithConfig:delegate: 之后调用该方法。

相关回调

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

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

参数

参数名描述
token

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

注：

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

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

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

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

mediaOptions

频道媒体选项。详见 AgoraRtcChannelMediaOptions。

joinSuccessBlock

用户加入频道成功时触发。joinSuccessBlock 的优先级高于 rtcEngine:didJoinChannel:withUid:elapsed:。当两者同时实现时，rtcEngine:didJoinChannel:withUid:elapsed: 不再生效。声网建议将 joinSuccessBlock 设置为 nil，以使用 rtcEngine:didJoinChannel:withUid:elapsed:。

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

返回值

0：方法调用成功。 < 0：方法调用失败。

  • -2：参数无效。例如，Token 无效，uid 参数未设置为整数，或 AgoraRtcChannelMediaOptions 中的成员值无效。你需要传入有效参数并重新加入频道。
  • -3：初始化 AgoraRtcEngineKit 对象失败。你需要重新初始化该对象。
  • -7：AgoraRtcEngineKit 对象尚未初始化。你需要先初始化该对象再调用该方法。
  • -8：AgoraRtcEngineKit 对象的内部状态错误。典型原因是调用 startEchoTestWithConfig: 开始通话回路测试后，未调用 stopEchoTest 停止测试就调用该方法加入频道。你需要先调用 stopEchoTest 再调用该方法。
  • -17：加入频道请求被拒绝。典型原因是你已在频道中。声网建议你通过 rtcEngine:connectionChangedToState:reason: 回调判断是否在频道中。只有在收到 AgoraConnectionStateDisconnected（1）状态时才调用该方法加入频道。
  • -102：频道名无效。你需要在 channelId 中传入有效的频道名重新加入频道。
  • -121：用户 ID 无效。你需要在 uid 中传入有效的用户 ID 重新加入频道。

所属接口类

joinChannelExByToken:connection:delegate:mediaOptions:joinSuccess:

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

Objective-C
- (int)joinChannelExByToken:(NSString* _Nullable)token
                 connection:(AgoraRtcConnection * _Nonnull)connection
                   delegate:(id<AgoraRtcEngineDelegate> _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。

注：

  • 该方法仅支持用户同时加入一个频道。
  • 不同 App ID 的用户无法互通。
  • 加入频道前，请确保用于生成 token 的 App ID 与 sharedEngineWithConfig:delegate: 方法中传入的 App ID 一致，否则可能会导致使用该 token 加入频道失败。
  • 为确保通信顺畅，请使用相同的参数类型标识用户。例如，如果某用户使用 UID 加入频道，则其他用户也应使用 UID。用户 User Account 同理。如果用户使用声网 Web SDK 加入频道，请确保用户 ID 的参数类型一致。

适用场景

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

调用时机

在调用 sharedEngineWithConfig:delegate: 之后调用该方法。

相关回调

参数

参数名描述
token

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

注：

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

连接信息。参见 AgoraRtcConnection。

delegate

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

mediaOptions

频道媒体选项。参见 AgoraRtcChannelMediaOptions。

joinSuccessBlock

用户加入频道成功时触发。joinSuccessBlock 的优先级高于 rtcEngine:didJoinChannel:withUid:elapsed:。当两者同时实现时，rtcEngine:didJoinChannel:withUid:elapsed: 不生效。声网建议将 joinSuccessBlock 设置为 nil，以使用 rtcEngine:didJoinChannel:withUid:elapsed:。

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

返回值

0：方法调用成功。 < 0：方法调用失败。

  • -2：参数无效。例如，token 无效，uid 参数未设置为整数，或 AgoraRtcChannelMediaOptions 中某成员的值无效。请传入有效参数并重新加入频道。
  • -3：初始化 AgoraRtcEngineKit 对象失败。请重新初始化该对象。
  • -7：AgoraRtcEngineKit 对象尚未初始化。请在调用该方法前初始化该对象。
  • -8：AgoraRtcEngineKit 对象的内部状态错误。常见原因是在调用 startEchoTestWithConfig: 开始回声测试后，未调用 stopEchoTest 停止测试就调用该方法加入频道。请先调用 stopEchoTest。
  • -17：加入频道请求被拒绝。常见原因是用户已在频道中。声网建议通过 rtcEngine:connectionChangedToState:reason: 回调判断用户是否在频道中。仅当收到 AgoraConnectionStateDisconnected（1）状态时再调用该方法。
  • -102：频道名无效。请在 channelId 中传入有效的频道名重新加入频道。
  • -121：用户 ID 无效。请在 uid 中传入有效的用户 ID 重新加入频道。

所属接口类

joinChannelByToken:channelId:userAccount:joinSuccess:

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

Objective-C
- (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。

注：

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

调用时机

在调用 sharedEngineWithConfig:delegate: 之后调用该方法。

相关回调

本地客户端：rtcEngine:didLocalUserRegisteredWithUserId:userAccount:、rtcEngine:didJoinChannel:withUid:elapsed: 和 rtcEngine:connectionChangedToState:reason: 回调。 远端客户端：当用户在 COMMUNICATION 频道场景中加入频道，或主播在 LIVE_BROADCASTING 频道场景中加入频道时，会触发 rtcEngine:didJoinedOfUid:elapsed: 和 rtcEngine:didUserInfoUpdatedWithUserId:userInfo: 回调。

参数

参数名描述
token

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

注：

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

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

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

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

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

用户成功加入频道回调。joinSuccessBlock 的优先级高于 rtcEngine:didJoinChannel:withUid:elapsed:。当两者同时实现时，rtcEngine:didJoinChannel:withUid:elapsed: 不生效。声网建议将 joinSuccessBlock 设置为 nil，以使用 rtcEngine:didJoinChannel:withUid:elapsed:。

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

返回值

  • 0：方法调用成功。

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

    • -2：参数无效。例如，Token 无效，uid 参数未设置为整数，或 AgoraRtcChannelMediaOptions 中的成员值无效。你需要传入有效参数并重新加入频道。
    • -3：初始化 AgoraRtcEngineKit 对象失败。你需要重新初始化该对象。
    • -7：AgoraRtcEngineKit 对象尚未初始化。你需要先初始化该对象再调用该方法。
    • -8：AgoraRtcEngineKit 对象的内部状态错误。典型原因是调用 startEchoTestWithConfig: 开始回声测试后，未调用 stopEchoTest 停止测试就调用该方法加入频道。你需要先调用 stopEchoTest 再调用该方法。
    • -17：加入频道请求被拒绝。典型原因是用户已在频道中。声网建议你通过 rtcEngine:connectionChangedToState:reason: 回调判断用户是否在频道中。只有在收到 AgoraConnectionStateDisconnected（1）状态时才调用该方法加入频道。
    • -102：频道名无效。你需要在 channelId 中传入有效的频道名重新加入频道。
    • -121：用户 ID 无效。你需要在 uid 中传入有效的用户 ID 重新加入频道。

所属接口类

joinChannelByToken:channelId:userAccount:mediaOptions:joinSuccess:

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

Objective-C
- (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: 方法相比，该方法多了一个 mediaOptions 参数，用于设置媒体选项，例如是否在频道内发布音视频流。默认情况下，你会订阅频道内所有其他用户的音视频流，从而产生使用量和计费。若要停止订阅其他流，请设置 mediaOptions 参数或调用 muteRemoteAudio/VideoStream 或 muteAllRemoteAudio/VideoStreams。

注：

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

调用时机

请在调用 sharedEngineWithConfig:delegate: 之后调用该方法。

相关回调

本地客户端：rtcEngine:didLocalUserRegisteredWithUserId:userAccount:、rtcEngine:didJoinChannel:withUid:elapsed: 和 rtcEngine:connectionChangedToState:reason: 回调。 远端客户端：当用户在 COMMUNICATION 频道场景中加入频道，或主播在 LIVE_BROADCASTING 频道场景中加入频道时，会触发 rtcEngine:didJoinedOfUid:elapsed: 和 rtcEngine:didUserInfoUpdatedWithUserId:userInfo: 回调。

参数

参数名描述
token

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

注：

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

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

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

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

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

频道媒体选项。详见 AgoraRtcChannelMediaOptions。

joinSuccessBlock

用户加入频道成功时触发。joinSuccessBlock 的优先级高于 rtcEngine:didJoinChannel:withUid:elapsed:。当两者同时实现时，rtcEngine:didJoinChannel:withUid:elapsed: 不生效。声网建议将 joinSuccessBlock 设置为 nil，以使用 rtcEngine:didJoinChannel:withUid:elapsed:。

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

返回值

0：方法调用成功。 < 0：方法调用失败。

  • -2：参数无效。例如，Token 无效，uid 参数未设置为整数，或 AgoraRtcChannelMediaOptions 中某成员的值无效。你需要传入有效参数并重新加入频道。
  • -3：初始化 AgoraRtcEngineKit 对象失败。你需要重新初始化该对象。
  • -7：AgoraRtcEngineKit 对象尚未初始化。你需要先初始化该对象再调用该方法。
  • -8：AgoraRtcEngineKit 对象的内部状态错误。典型原因是调用 startEchoTestWithConfig: 开始回声测试后，未调用 stopEchoTest 停止测试就调用该方法加入频道。你需要先调用 stopEchoTest。
  • -17：加入频道请求被拒绝。典型原因是用户已在频道中。声网建议使用 rtcEngine:connectionChangedToState:reason: 回调判断用户是否在频道中。只有在收到 AgoraConnectionStateDisconnected（1）状态时才调用该方法。
  • -102：频道名无效。你需要传入有效的 channelId 重新加入频道。
  • -121：用户 ID 无效。你需要传入有效的 uid 重新加入频道。

所属接口类

joinChannelExByToken:channelId:userAccount:delegate:mediaOptions:joinSuccess:

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

Objective-C
- (int)joinChannelExByToken:(NSString* _Nullable)token
                  channelId:(NSString* _Nonnull)channelId
                userAccount:(NSString* _Nonnull)userAccount
                   delegate:(id<AgoraRtcEngineDelegate> _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。

注：

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

适用场景

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

调用时机

在调用 sharedEngineWithConfig:delegate: 之后调用该方法。

相关回调

参数

参数名描述
token

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

注：

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

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

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

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

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

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

mediaOptions

频道媒体选项。参见 AgoraRtcChannelMediaOptions。

joinSuccessBlock

用户加入频道成功时触发。joinSuccessBlock 的优先级高于 rtcEngine:didJoinChannel:withUid:elapsed:。当两者同时实现时，rtcEngine:didJoinChannel:withUid:elapsed: 不生效。声网建议将 joinSuccessBlock 设置为 nil，以使用 rtcEngine:didJoinChannel:withUid:elapsed:。

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

返回值

0：方法调用成功。 < 0：方法调用失败。

  • -2：参数无效。例如，Token 无效，uid 参数未设置为整数，或 AgoraRtcChannelMediaOptions 中某成员的值无效。请传入有效参数后重新加入频道。
  • -3：初始化 AgoraRtcEngineKit 对象失败。请重新初始化该对象。
  • -7：AgoraRtcEngineKit 对象尚未初始化。请先初始化该对象再调用该方法。
  • -8：AgoraRtcEngineKit 对象的内部状态错误。典型原因是调用 startEchoTestWithConfig: 开始回声测试后，未调用 stopEchoTest 停止测试就调用该方法加入频道。请先调用 stopEchoTest 再调用该方法。
  • -17：加入频道请求被拒绝。典型原因是用户已在频道中。声网建议通过 rtcEngine:connectionChangedToState:reason: 回调判断用户是否在频道中。只有在收到 AgoraConnectionStateDisconnected（1）状态时才调用该方法加入频道。
  • -102：频道名无效。请在 channelId 中传入有效的频道名后重新加入频道。
  • -121：用户 ID 无效。请在 uid 中传入有效的用户 ID 后重新加入频道。

所属接口类

leaveChannel:

离开频道并释放资源。

Objective-C
- (int)leaveChannel:(void(^ _Nullable)(AgoraChannelStats * _Nonnull stat))leaveChannelBlock NS_SWIFT_NAME(leaveChannel(_:));

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

注： 如果在调用该方法后立即调用 destroy，SDK 不会触发 rtcEngine:didLeaveChannelWithStats: 回调。

  • 该方法为异步调用。当该方法返回时，并不代表你已完全离开频道。
  • 如果你调用了 joinChannelExByToken 加入了多个频道，调用该方法会离开你加入的所有频道。

调用时机

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

相关回调

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

参数

参数名描述
leaveChannelBlock

该回调表示你离开频道，并在 AgoraChannelStats 中提供通话统计信息。

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

返回值

  • 0：方法调用成功。

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

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

所属接口类

leaveChannel:leaveChannelBlock:

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

Objective-C
- (int)leaveChannel:(AgoraLeaveChannelOptions * _Nonnull)options
leaveChannelBlock:(void (^ _Nullable)(AgoraChannelStats * _Nonnull))leaveChannelBlock NS_SWIFT_NAME(leaveChannel(_:leaveChannelBlock:));

调用该方法后，SDK 会终止音视频互动，离开当前频道，并释放与会话相关的所有资源。加入频道后，必须调用该方法或 leaveChannel: 来结束通话，否则无法开始下一次通话。如果你调用了 joinChannelExByToken 加入了多个频道，调用该方法会离开你加入的所有频道。

注： 如果在调用该方法后立即调用 destroy，SDK 不会触发 rtcEngine:didLeaveChannelWithStats: 回调。该方法为异步调用。当该方法返回时，并不意味着你已经离开频道。

调用时机

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

相关回调

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

参数

参数名描述
options

离开频道的选项。详见 AgoraLeaveChannelOptions。

leaveChannelBlock

该回调表示你离开频道，并在 AgoraChannelStats 中提供通话统计信息。

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

返回值

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

所属接口类

leaveChannelEx:leaveChannelBlock:

离开频道并释放与会话相关的所有资源。

Objective-C
- (int)leaveChannelEx:(AgoraRtcConnection * _Nonnull)connection
    leaveChannelBlock:(void(^ _Nullable)(AgoraChannelStats* _Nonnull stat))leaveChannelBlock NS_SWIFT_NAME(leaveChannelEx(_:leaveChannelBlock:));

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

注： 如果在调用该方法后立即调用 destroy，SDK 不会触发 rtcEngine:didLeaveChannelWithStats: 回调。

  • 此方法为异步调用。当该方法返回时，并不代表你已离开频道。
  • 如果调用 leaveChannel: 或 leaveChannel:leaveChannelBlock:，你将离开通过 joinChannelByToken、joinChannelByToken 或 joinChannelExByToken 加入的所有频道。

适用场景

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

调用时机

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

相关回调

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

参数

参数名描述
connection

连接信息。详见 AgoraRtcConnection。

leaveChannelBlock

离开频道回调。在 AgoraChannelStats 中提供通话统计信息。

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

返回值

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

所属接口类

leaveChannelEx:options:leaveChannelBlock:

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

Objective-C
- (int)leaveChannelEx:(AgoraRtcConnection * _Nonnull)connection
              options:(AgoraLeaveChannelOptions * _Nonnull)options
    leaveChannelBlock:(void(^ _Nullable)(AgoraChannelStats* _Nonnull stat))leaveChannelBlock;

自从

自 v4.1.0 版本新增。

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

注： 如果在调用该方法后立即调用 destroy，SDK 不会触发 rtcEngine:didLeaveChannelWithStats: 回调。

  • 此方法为异步调用。当该方法返回时，并不代表你已离开频道。
  • 如果调用 leaveChannel: 或 leaveChannel:leaveChannelBlock:，你将离开通过 joinChannelByToken、joinChannelByToken 或 joinChannelExByToken 加入的所有频道。

适用场景

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

调用时机

请在调用 joinChannelExByToken 之后调用该方法。

参数

参数名描述
connection

连接信息。详见 AgoraRtcConnection。

options

离开频道的选项。仅支持设置 AgoraLeaveChannelOptions 中的 stopMicrophoneRecording 成员，设置其他成员无效。详见 AgoraLeaveChannelOptions。

leaveChannelBlock

该回调表示你离开频道，并在 AgoraChannelStats 中提供通话统计信息。详见 AgoraChannelStats。

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

返回值

0：方法调用成功。 < 0：方法调用失败。

所属接口类

preloadChannelByToken:channelId:uid:

预加载指定频道。

Objective-C
- (int)preloadChannelByToken:(NSString * _Nullable)token
                   channelId:(NSString * _Nonnull)channelId
                         uid:(NSUInteger)uid NS_SWIFT_NAME(preloadChannel(byToken:channelId:uid:));

该方法用于预加载指定频道。当你作为观众需要频繁切换频道时，调用该方法可以缩短加入频道的时间，从而减少你听到和看到主播的延迟。该方法需要在加入频道前调用。如果你加入了一个已预加载的频道，离开后想要重新加入该频道，除非用于预加载的 Token 过期，否则无需再次调用该方法。为提升预加载频道的用户体验，声网建议你在确认频道名和用户信息后尽早调用该方法。

注：

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

调用时机

该方法需要在加入频道前调用。

参数

参数名描述
token

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

  • 如果只预加载一个频道，调用该方法传入新的 Token。

  • 如果预加载多个频道：

注意：生成通配符 Token 时，确保用户 ID 不为 0。

  • 如果你为不同频道使用不同的 Token，调用该方法传入用户 ID、频道名和新的 Token。
channelId

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

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

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

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

返回值

  • 0：方法调用成功。

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

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

所属接口类

preloadChannelByTokenWithUserAccount:channelId:userAccount:

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

Objective-C
- (int)preloadChannelByTokenWithUserAccount:(NSString * _Nullable)token
                   channelId:(NSString * _Nonnull)channelId
                 userAccount:(NSString * _Nonnull)userAccount NS_SWIFT_NAME(preloadChannelWithUserAccount(byToken:channelId:userAccount:));

当你需要频繁切换不同频道时，调用该方法可以缩短加入频道的时间，从而减少你听到和看到主播的延迟。如果你加入了一个已预加载的频道，离开后想重新加入同一个频道，除非用于预加载频道的 Token 过期，否则无需再次调用该方法。声网建议你在确认频道名和用户信息后尽早调用该方法，以提升预加载频道的用户体验。

注：

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

调用时机

该方法需要在加入频道前调用。

参数

参数名描述
token

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

  • 如果只预加载一个频道，调用该方法传入新的 Token。

  • 如果预加载多个频道：

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

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

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

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

  • 26 个小写英文字母：a 到 z。
  • 26 个大写英文字母：A 到 Z。
  • 所有数字字符：0 到 9。
  • 空格
  • "!", "#", "$", "%", "&", "(", ")", "+", "-", ":", ";", "<", "=", ".", ">", "?", "@", "[", "]", "^", "_", "{", "}", "|", "~", ","。
表格内容超出当前宽度，可横向滚动查看更多列。

返回值

  • 0：方法调用成功。

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

    • -2：参数无效，例如用户 User Account 为空。你需要传入有效参数并重新加入频道。
    • -7：AgoraRtcEngineKit 对象尚未初始化。你需要在调用该方法前初始化该对象。
    • -102：频道名无效。你需要传入有效的频道名并重新加入频道。

所属接口类

registerLocalUserAccount:appId:

注册用户 User Account。

Objective-C
- (int)registerLocalUserAccount:(NSString* _Nonnull)userAccount appId:(NSString* _Nonnull)appId  NS_SWIFT_NAME(registerLocalUserAccount(_:appId:));

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

调用该方法成功后，本地会触发 rtcEngine:didLocalUserRegisteredWithUserId:userAccount: 回调，报告本地用户的用户 ID 和 userAccount。

注：

  • 从 v4.6.0 起，SDK 不再自动将 int 类型的用户 ID 映射为注册时使用的 string 类型 userAccount。如果你希望使用注册时的原始 userAccount 加入频道，请调用 joinChannelByToken:channelId:userAccount:mediaOptions:joinSuccess: 方法，而不要调用 joinChannelByToken:channelId:uid:mediaOptions:joinSuccess: 并传入通过该方法获取的 int 类型用户 ID。
  • 请确保 userAccount 在频道中唯一。
  • 为确保通信顺畅，请统一使用相同的参数类型标识用户。例如，如果某用户使用用户 ID 加入频道，则其他用户也应使用用户 ID；若使用 userAccount，则其他用户也应使用 userAccount。如果用户使用声网 Web SDK 加入频道，请确保用户 ID 的参数类型一致。

相关回调

调用该方法成功后，本地会触发 rtcEngine:didLocalUserRegisteredWithUserId:userAccount: 回调，报告本地用户的用户 ID 和 userAccount。

参数

参数名描述
userAccount

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

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

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

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

返回值

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

所属接口类

renewToken:

更新 Token。

Objective-C
- (int)renewToken:(NSString * _Nonnull)token NS_SWIFT_NAME(renewToken(_:));

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

参数

参数名描述
token

新的 Token。

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

返回值

  • 0：方法调用成功。

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

    • -2：参数无效。例如，token 为空。

    • -7：AgoraRtcEngineKit 对象尚未初始化。请在调用该方法前先初始化 AgoraRtcEngineKit 对象。

    • 110：token 无效。请确保以下几点：

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

所属接口类

setChannelProfile:

设置频道场景。

Objective-C
- (int)setChannelProfile:(AgoraChannelProfile)profile NS_SWIFT_NAME(setChannelProfile(_:));

你可以调用该方法设置频道场景。SDK 会针对不同的频道场景采用不同的优化策略。例如，在直播场景中，SDK 会优先保证视频质量。初始化 SDK 后，默认频道场景为直播。

注：

  • 为保证实时通信质量，声网建议频道内所有用户使用相同的频道场景。
  • 在 iOS 平台，不同频道场景下 SDK 的默认音频路由不同，详见 setDefaultAudioRouteToSpeakerphone:。

调用时机

该方法需要在加入频道前调用。

参数

参数名描述
profile

频道场景。详见 AgoraChannelProfile。

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

返回值

0：方法调用成功。 < 0：方法调用失败。

  • -2：参数无效。
  • -7：SDK 尚未初始化。

所属接口类

setClientRole:

设置用户角色。

Objective-C
- (int)setClientRole:(AgoraClientRole)role NS_SWIFT_NAME(setClientRole(_:));

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

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

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

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

调用时机

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

参数

参数名描述
role

用户角色。详见 AgoraClientRole。

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

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

返回值

  • 0：方法调用成功。

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

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

所属接口类

setClientRole:options:

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

Objective-C
- (int)setClientRole:(AgoraClientRole)role options:(AgoraClientRoleOptions * _Nullable)options NS_SWIFT_NAME(setClientRole(_:options:));

你可以调用该方法设置用户角色为主播或观众。用户角色（role）决定了你在 SDK 层的权限，例如是否可以在频道中发布音视频流。

该方法相比 setClientRole:，支持设置 audienceLatencyLevel。你需要将 audienceLatencyLevel 与 role 搭配使用，以决定你在权限范围内可享受的服务等级。例如，观众可以选择接收低延迟或超低延迟的远端流。

如果你在加入频道前调用该方法将用户角色设置为主播，并通过 setupLocalVideo: 方法设置本地视频属性，则加入频道时会自动开启本地视频预览。

如果你在加入频道后调用该方法设置用户角色，SDK 会自动调用 muteLocalAudioStream: 和 muteLocalVideoStream: 方法来改变音视频流的发布状态。

注： 当用户角色设置为主播时，观众延迟等级只能设置为 AgoraAudienceLatencyLevelUltraLowLatency。

调用时机

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

相关回调

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

如果你在加入频道后调用此方法设置用户角色但失败，SDK 会触发 rtcEngine:didClientRoleChangeFailed:currentRole: 回调，报告失败原因和当前用户角色。注意：在加入频道前调用此方法并将 role 设置为 AUDIENCE 也会触发 rtcEngine:didClientRoleChanged:newRole:newRoleOptions: 回调。

参数

参数名描述
role

用户角色。详见 AgoraClientRole。

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

options

用户的详细选项，包括用户等级。详见 AgoraClientRoleOptions。

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

返回值

0：方法调用成功。 < 0：方法调用失败。

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

所属接口类

updateChannelWithMediaOptions:

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

Objective-C
- (int)updateChannelWithMediaOptions:(AgoraRtcChannelMediaOptions* _Nonnull)mediaOptions NS_SWIFT_NAME(updateChannel(with:));

你可以在加入频道后调用该方法更新频道媒体选项。

参数

参数名描述
mediaOptions

频道媒体选项。详见 AgoraRtcChannelMediaOptions。

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

返回值

所属接口类

updateChannelExWithMediaOptions:connection:

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

Objective-C
- (int)updateChannelExWithMediaOptions:(AgoraRtcChannelMediaOptions* _Nonnull)mediaOptions
                            connection:(AgoraRtcConnection * _Nonnull)connection NS_SWIFT_NAME(updateChannelEx(with:connection:));

适用场景

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

参数

参数名描述
mediaOptions

频道媒体选项。详见 AgoraRtcChannelMediaOptions。

connection

连接信息。详见 AgoraRtcConnection。

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

返回值

所属接口类

updatePreloadChannelToken:

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

Objective-C
- (int)updatePreloadChannelToken:(NSString * _Nonnull)token NS_SWIFT_NAME(updatePreloadChannelToken(_:));

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

适用场景

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

参数

参数名描述
token

新的 Token。

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

返回值

  • 0：方法调用成功。

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

    • -2：参数无效，例如 Token 无效。你需要传入有效的参数并重新加入频道。
    • -7：AgoraRtcEngineKit 对象尚未初始化。你需要先初始化 AgoraRtcEngineKit 对象再调用此方法。

所属接口类

rtcEngine:didClientRoleChanged:newRole:newRoleOptions:

用户角色或观众延迟等级发生变化时触发的回调。

Objective-C
- (void)rtcEngine:(AgoraRtcEngineKit * _Nonnull)engine didClientRoleChanged:(AgoraClientRole)oldRole newRole:(AgoraClientRole)newRole newRoleOptions:(AgoraClientRoleOptions * _Nullable)newRoleOptions NS_SWIFT_NAME(rtcEngine(_:didClientRoleChanged:newRole:newRoleOptions:));

注： 加入频道前调用 setClientRole: 或 setClientRole:options: 并将用户角色设置为 BROADCASTER 时不会触发该回调。

触发时机

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

参数

参数名描述
engine

引擎实例。详见 AgoraRtcEngineKit。

oldRole

用户切换前的角色。详见 AgoraClientRole。

newRole

用户切换后的角色。详见 AgoraClientRole。

newRoleOptions

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

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

所属接口类

rtcEngine:didClientRoleChangeFailed:currentRole:

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

Objective-C
- (void)rtcEngine:(AgoraRtcEngineKit * _Nonnull)engine didClientRoleChangeFailed:(AgoraClientRoleChangeFailedReason)reason currentRole:(AgoraClientRole)currentRole NS_SWIFT_NAME(rtcEngine(_:didClientRoleChangeFailed:currentRole:));

触发时机

该回调在你加入频道后调用 setClientRole: 或 setClientRole:options: 切换用户角色但切换失败时被触发。

参数

参数名描述
reason

用户角色切换失败的原因，详见 AgoraClientRoleChangeFailedReason。

currentRole

当前的用户角色，详见 AgoraClientRole。

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

所属接口类

rtcEngine:didOccurError:

报告 SDK 运行时发生的错误回调。

Objective-C
- (void)rtcEngine:(AgoraRtcEngineKit * _Nonnull)engine didOccurError:(AgoraErrorCode)errorCode NS_SWIFT_NAME(rtcEngine(_:didOccurError:));

该回调在 SDK 运行过程中发生错误时触发。

触发时机

该回调在 SDK 运行过程中发生错误时触发。

参数

参数名描述
engine

AgoraRtcEngineKit 对象。详见 AgoraRtcEngineKit。

errorCode

错误码。详见 AgoraErrorCode。

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

所属接口类

rtcEngine:didJoinChannel:withUid:elapsed:

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

Objective-C
- (void)rtcEngine:(AgoraRtcEngineKit * _Nonnull)engine didJoinChannel:(NSString * _Nonnull)channel withUid:(NSUInteger)uid elapsed:(NSInteger)elapsed NS_SWIFT_NAME(rtcEngine(_:didJoinChannel:withUid:elapsed:));

该回调在本地用户成功加入指定频道时触发。

触发时机

该回调在调用 joinChannelByToken、joinChannelExByToken 等方法加入频道时被触发。

参数

参数名描述
engine

AgoraRtcEngineKit 对象，详见 AgoraRtcEngineKit。

channel

频道名。

uid

本地用户加入频道的用户 ID。

elapsed

从调用 joinChannelByToken 方法到 SDK 触发该回调的时间间隔（毫秒）。

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

所属接口类

rtcEngine:didLeaveChannelWithStats:

用户离开频道时的回调。

Objective-C
- (void)rtcEngine:(AgoraRtcEngineKit * _Nonnull)engine didLeaveChannelWithStats:(AgoraChannelStats * _Nonnull)stats NS_SWIFT_NAME(rtcEngine(_:didLeaveChannelWith:));

你可以通过该回调获取通话的总时长以及 SDK 的收发数据量。

触发时机

该回调在你调用 leaveChannel:、leaveChannel:leaveChannelBlock:、leaveChannelEx:leaveChannelBlock: 或 leaveChannelEx:options:leaveChannelBlock: 离开频道后被触发。

参数

参数名描述
engine

AgoraRtcEngineKit 对象。

stats

通话统计信息，详见 AgoraChannelStats。

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

所属接口类

rtcEngine:didLocalUserRegisteredWithUserId:userAccount:

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

Objective-C
- (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: 方法加入频道后，SDK 会触发该回调，并返回你的用户 ID 和用户 User Account。

触发时机

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

参数

参数名描述
engine

AgoraRtcEngineKit 对象，详见 AgoraRtcEngineKit。

uid

本地用户的用户 ID。

userAccount

本地用户的用户 User Account。

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

所属接口类

rtcEngine:didRejoinChannel:withUid:elapsed:

rtcEngine:didRejoinChannel:withUid:elapsed: 回调。当用户重新加入频道时触发。

Objective-C
- (void)rtcEngine:(AgoraRtcEngineKit * _Nonnull)engine didRejoinChannel:(NSString * _Nonnull)channel withUid:(NSUInteger)uid elapsed:(NSInteger)elapsed NS_SWIFT_NAME(rtcEngine(_:didRejoinChannel:withUid:elapsed:));

触发时机

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

参数

参数名描述
engine

声网引擎对象。详见 AgoraRtcEngineKit。

channel

频道名。

uid

重新加入频道的用户 ID。

elapsed

从调用 joinChannelByToken:channelId:uid:mediaOptions:joinSuccess: 到 SDK 触发该回调所经过的时间（毫秒）。

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

所属接口类

rtcEngine:renewTokenResult:code:

renewToken: 方法调用结果的回调。

Objective-C
- (void)rtcEngine:(AgoraRtcEngineKit * _Nonnull)engine renewTokenResult:(NSString *_Nonnull)token code:(AgoraRenewTokenErrorCode)code NS_SWIFT_NAME(rtcEngine(_:renewTokenResult:code:));

自从

自 v4.6.0 版本新增。

触发时机

该回调在你调用 renewToken: 方法更新 Token 后被触发。

参数

参数名描述
engine

AgoraRtcEngineKit 实例。详见 AgoraRtcEngineKit。

token

Token。

code

错误码，详见 AgoraRenewTokenErrorCode。

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

所属接口类

rtcEngineRequestToken:

当 Token 过期时触发的回调。

Objective-C
- (void)rtcEngineRequestToken:(AgoraRtcEngineKit * _Nonnull)engine NS_SWIFT_NAME(rtcEngineRequestToken(_:));

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

触发时机

当 Token 过期时触发。

参数

参数名描述
engine

AgoraRtcEngineKit 对象。详见 AgoraRtcEngineKit。

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

所属接口类

rtcEngine:reportRtcStats:

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

Objective-C
- (void)rtcEngine:(AgoraRtcEngineKit * _Nonnull)engine reportRtcStats:(AgoraChannelStats * _Nonnull)stats NS_SWIFT_NAME(rtcEngine(_:reportRtcStats:));

触发时机

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

参数

参数名描述
engine

AgoraRtcEngineKit 对象，详见 AgoraRtcEngineKit。

stats

通话统计信息，详见 AgoraChannelStats。

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

所属接口类

rtcEngine:tokenPrivilegeWillExpire:

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

Objective-C
- (void)rtcEngine:(AgoraRtcEngineKit * _Nonnull)engine tokenPrivilegeWillExpire:(NSString *_Nonnull)token NS_SWIFT_NAME(rtcEngine(_:tokenPrivilegeWillExpire:));

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

SDK 会在 Token 过期前 30 秒触发该回调，提醒应用更新 Token。

触发时机

该回调在 Token 过期前 30 秒被触发，提醒你更新 Token。

参数

参数名描述
engine

AgoraRtcEngineKit 对象，详见 AgoraRtcEngineKit。

token

即将过期的 Token。

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

所属接口类

rtcEngine:didUserInfoUpdatedWithUserId:userInfo:

当 SDK 获取到远端用户的用户 ID 和用户 User Account 时触发。

Objective-C
- (void)rtcEngine:(AgoraRtcEngineKit * _Nonnull)engine didUserInfoUpdatedWithUserId:(NSUInteger)uid userInfo:(AgoraUserInfo* _Nonnull)userInfo NS_SWIFT_NAME(rtcEngine(_:didUserInfoUpdatedWithUserId:userInfo:));

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

触发时机

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

参数

参数名描述
engine

AgoraRtcEngineKit 对象。详见 AgoraRtcEngineKit。

uid

远端用户的用户 ID。

userInfo

包含远端用户的用户 ID 和用户 User Account 的对象。详见 AgoraUserInfo。

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

所属接口类

rtcEngine:didJoinedOfUid:elapsed:

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

Objective-C
- (void)rtcEngine:(AgoraRtcEngineKit * _Nonnull)engine didJoinedOfUid:(NSUInteger)uid elapsed:(NSInteger)elapsed NS_SWIFT_NAME(rtcEngine(_:didJoinedOfUid:elapsed:));

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

触发时机

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

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

参数

参数名描述
engine

AgoraRtcEngineKit 对象。详见 AgoraRtcEngineKit。

uid

加入频道的用户或主播的 ID。

elapsed

从你调用 joinChannelByToken:channelId:info:uid:joinSuccess: 或 joinChannelByToken:channelId:uid:mediaOptions:joinSuccess: 到该回调被触发的延迟时间（毫秒）。

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

所属接口类

rtcEngine:didOfflineOfUid:reason:

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

Objective-C
- (void)rtcEngine:(AgoraRtcEngineKit * _Nonnull)engine didOfflineOfUid:(NSUInteger)uid reason:(AgoraUserOfflineReason)reason NS_SWIFT_NAME(rtcEngine(_:didOfflineOfUid:reason:));

用户离线通常有两个原因：

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

触发时机

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

参数

参数名描述
engine

AgoraRtcEngineKit 对象，详见 AgoraRtcEngineKit。

uid

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

reason

远端用户（在通信场景中）或主播（在直播场景中）离线的原因，详见 AgoraUserOfflineReason。

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

所属接口类

咨询电话

400 632 6626

上海声网科技有限公司

Copyright © 2026 声网保留所有权利