子区是群组成员的子集,是支持多人沟通的即时通讯系统。本文介绍如何使用即时通讯 IM iOS SDK 在实时互动 app 中创建和管理子区,并实现子区相关功能。
下图展示了创建子区、子区中的会话以及可以在子区中执行的操作。
即时通讯 IM iOS SDK 提供 AgoraChatThreadManager
、AgoraChatThread
、AgoraChatThreadManagerDelegate
和 AgoraChatThreadEvent
类用于子区管理,可以实现以下功能:
开始前,请确保满足以下条件:
每个版本的套餐包都支持子区功能。在声网控制台中启用即时通讯服务后默认开启子区功能。
本节介绍如何使用即时通讯 IM SDK 提供的 API 实现上述功能。
所有群成员均可以调用 createChatThread
方法基于一条群组消息新建子区。
单设备登录时,子区所属群组的所有成员均会收到 AgoraChatThreadManagerDelegate#onChatThreadCreated
回调;多设备登录时,其他设备会同时收 AgoraChatMultiDevicesDelegate#multiDevicesThreadEventDidReceive
回调,回调事件为 AgoraChatMultiDevicesEventThreadCreate
。
示例代码如下:
// threadName:子区名称,长度不超过 64 个字符
// messageId:子区的父消息 ID,即基于该消息创建子区
// parentId:群组 ID
[[AgoraChatClient sharedClient].threadManager createChatThread:self.threadName messageId:self.message.messageId parentId:self.message.to completion:^(AgoraChatThread *thread, AgoraChatError *aError) {
if (!aError) {
} else {
}
}];
仅子区所在群组的群主和群管理员可以调用 destroyChatThread
方法解散子区。
单设备登录时,子区所属群组的所有成员均会收到 AgoraChatThreadManagerDelegate#onChatThreadDestroyed
回调;多设备登录时,其他设备会同时收到 AgoraChatMultiDevicesDelegate#multiDevicesThreadEventDidReceive
回调,回调事件为 AgoraChatMultiDevicesEventThreadDestroy
。
示例代码如下:
[AgoraChatClient.sharedClient.threadManager destroyChatThread:self.conversationId completion:^(AgoraChatError *aError) {
if (!aError) {
} else {
}
}];
子区所在群组的所有成员均可以调用 joinChatThread
方法加入群组。
getChatThreadsFromServer
获取群组中的子区列表,获得你想加入的子区 ID。AgoraChatThreadManagerDelegate#onChatThreadCreated
或 AgoraChatThreadManagerDelegate#onChatThreadUpdated
回调时获取子区 ID。joinChatThread
传入子区 ID,加入对应子区。多设备登录时,其他设备会同时收到 AgoraChatMultiDevicesDelegate#multiDevicesThreadEventDidReceive
回调,回调事件为 AgoraChatMultiDevicesEventThreadJoin
。
示例代码如下:
[AgoraChatClient.sharedClient.threadManager joinChatThread:model.message.threadOverView.threadId completion:^(AgoraChatThread *thread,AgoraChatError *aError) {
if (!aError || aError.code == AgoraChatErrorUserAlreadyExist) {
}
}];
子区成员均可以主动调用 leaveChatThread
方法退出子区。退出子区后,该成员将不会再收到子区消息。
多设备登录时,其他设备会同时收到 AgoraChatMultiDevicesDelegate#multiDevicesThreadEventDidReceive
回调,回调事件为 AgoraChatMultiDevicesEventThreadLeave
。
示例代码如下:
[AgoraChatClient.sharedClient.threadManager leaveChatThread:self.conversationId completion:^(AgoraChatError *aError) {
if (!aError) {
} else {
}
}];
仅群主和群管理员可以调用 removeMemberFromChatThread
方法将指定成员 (群管理员或普通成员) 踢出子区,被踢出子区的成员将不再接收到子区消息。
被踢出子区的成员会收到 AgoraChatThreadManagerDelegate#onUserKickOutOfChatThread
回调。多设备登录时,执行踢人操作的成员的其他设备会同时收到 AgoraChatMultiDevicesDelegate#multiDevicesThreadEventDidReceive
回调,回调事件为 AgoraChatMultiDevicesEventChatThreadKick
。
示例代码如下:
// chatThreadId:子区 ID
// member:子区成员的用户 ID
[AgoraChatClient.sharedClient.threadManager removeMemberFromChatThread:member threadId:self.threadId completion:^(AgoraChatError *aError) {
if (!aError) {
} else {
}
}];
仅群主和群管理员以及子区的创建者可以调用 updateChatThreadName
方法修改子区名称。
单设备登录时,子区所属群组的所有成员会收到 AgoraChatThreadManagerDelegate#onChatThreadUpdated
回调;多设备登录时,其他设备会同时收到 AgoraChatMultiDevicesDelegate#multiDevicesThreadEventDidReceive
回调,回调事件为 AgoraChatMultiDevicesEventThreadUpdate
。
示例代码如下:
// threadId:子区 ID
// ThreadName:修改后的子区名称,长度不超过 64 个字符
[AgoraChatClient.sharedClient.threadManager updateChatThreadThreadName:self.threadNameField.text threadId:self.threadId completion:^(AgoraChatError *aError) {
if (!aError) {
} else {
}
}];
子区所属群组的所有成员均可以调用 getChatThreadDetail
方法从服务器获取子区详情。
示例代码如下:
// threadId:子区 ID
[AgoraChatClient.sharedClient.threadManager getChatThreadDetail:self.currentConversation.conversationId completion:^(AgoraChatThread *thread, AgoraChatError *aError) {
if (!aError) {
} else {
}
}];
子区所属群组的所有成员均可以调用 getChatThreadMemberListFromServerWithId
方法从服务器分页获取子区成员列表。
// threadId:子区 ID
// pageSize:每次获取的成员数,取值范围为 [1,50]
// cursor:数据查询的起始位置,首次调用方法时传 `nil` 或空字符串
[[AgoraChatClient sharedClient].threadManager getChatThreadMemberListFromServerWithId:self.threadId cursor:aCursor pageSize:pageSize completion:^(AgoraChatCursorResult *aResult, AgoraChatError *aError) {
if !aError { self.cursor = aResult; }
}];
getJoinedChatThreadsFromServer
方法从服务器分页获取自己加入和创建的子区列表:// limit:每次获取的子区数,取值范围为 [1,50]
// cursor:数据查询的起始位置,首次调用方法时传 `nil` 或空字符串
[AgoraChatClient.sharedClient.threadManager getJoinedChatThreadsFromServerWithCursor:@"" pageSize:20 completion:^(AgoraChatCursorResult * _Nonnull result, AgoraChatError * _Nonnull aError) {
}];
getJoinedChatThreadsFromServer
方法从服务器分页获取指定群组中自己加入和创建的子区列表:// parentId:群组 ID
// pageSize:每次获取的子区数,取值范围为 [1, 50]
// cursor:数据查询的起始位置,首次调用方法时传 `nil` 或空字符串
[AgoraChatClient.sharedClient.threadManager getJoinedChatThreadsFromServerWithParentId:self.group.groupId cursor:self.cursor ? self.cursor.cursor:@"" pageSize:20 completion:^(AgoraChatCursorResult * _Nonnull result, AgoraChatError * _Nonnull aError) {
if (!aError) {
}
}];
getChatThreadsFromServer
方法从服务器分页获取指定群组的子区列表:// parentId: 群组 ID
// pageSize: 每次获取的子区数,取值范围为 [1,50]
// cursor: 数据查询的起始位置,首次调用方法时传 `nil` 或空字符串
[[AgoraChatClient sharedClient].threadManager getChatThreadsFromServerWithParentId:self.group.groupId cursor:self.cursor ? self.cursor.cursor:@"" pageSize:20 completion:^(AgoraChatCursorResult *result, AgoraChatError *aError) {
if (!aError) {
}
}];
用户可以调用 getLastMessageFromSeverWithChatThreads
方法从服务器批量获取子区中的最新一条消息。
示例代码如下:
// threadIds:要查询的子区 ID 列表,每次最多可传入 20 个子区 ID
[[AgoraChatClient sharedClient].threadManager getLastMessageFromSeverWithChatThreads:ids completion:^(NSDictionary<NSString *,AgoraChatMessage *> * _Nonnull messageMap, AgoraChatError * _Nonnull aError) {
if (!aError) {
}
}];
AgoraChatThreadManager
类中提供子区事件的监听接口。开发者可以通过设置此监听,获取子区中的事件,并做出相应处理。如果不再使用该监听,需要移除,防止出现内存泄漏。
示例代码如下:
AgoraChatThreadManagerDelegate
// 子区创建
- (void)onChatThreadCreate:(AgoraChatThreadEvent *)event;
// 子区名称修改、子区中新增或撤回消息
- (void)onChatThreadUpdate:(AgoraChatThreadEvent *)event;
// 子区解散
- (void)onChatThreadDestroy:(AgoraChatThreadEvent *)event;
// 子区成员被移除
- (void)onUserKickOutOfChatThread:(AgoraChatThreadEvent *)event;
// 注册监听
[[AgoraChatClient sharedClient].threadManager addDelegate:self delegateQueue:nil];
// 移除监听
[[AgoraChatClient sharedClient].threadManager removeDelegate:self];