群组管理
本文档旨在指导开发者如何使用融云即时通讯 iOS IMLib SDK 实现创建群组、群组资料设置、踢出群组、退出群组、解散群组、转让群组等功能。
提示
- 此功能从 5.12.0 版本开始支持。
- 针对已经通过原群组功能接口
/group/create.json创建的群组，默认不支持调用群托管的相关功能接口，需要调用“导入群托管数据”接口，设置群组所有者（群主）及群组的默认权限后才能使用。
开通服务
使用此功能前，您须在控制台开通信息托管服务。
群组事件
群事件定义在 RCGroupEventDelegate 中，包含群操作、群信息群成员信息变更、加群申请相关通知、群备注名多端同步、群特别关注多端同步等。
- 您可以调用
addGroupEventDelegate添加群组事件回调代理。 - 您可以调用
removeGroupEventDelegate方法移除群组事件回调代理。
提示
信息托管服务中，群组操作产生的 SDK 通知回调也是一种状态通知行为，不管应用中是否实现 SDK 的事件监听，服务端都会对 SDK 进行状态同步，确保本地为最新的数据信息，所以会计入消息的分发、下行数据统计中。
示例代码
objc
// 添加群组事件回调代理
[[RCCoreClient sharedCoreClient] addGroupEventDelegate:self];
// ------ 群组事件回调 ------
- (void)onGroupOperation:(NSString *)groupId
operatorInfo:(RCGroupMemberInfo *)operatorInfo
groupInfo:(RCGroupInfo *)groupInfo
operation:(RCGroupOperation)operation
memberInfos:(NSArray<RCGroupMemberInfo *> *)memberInfos
operationTime:(long long)operationTime {
// 群组操作回调
// 操作事件包括创建群、加入群、踢出、退出、解散、添加管理员、移除管理员、转让群主，详见 RCGroupOperation
}
- (void)onGroupInfoChanged:(RCGroupMemberInfo *)operatorInfo
groupInfo:(RCGroupInfo *)groupInfo
updateKeys:(NSArray<RCGroupInfoKeys> *)updateKeys
operationTime:(long long)operationTime __deprecated_msg("Use [RCGroupEventDelegate onGroupInfoChanged:fullGroupInfo:changedGroupInfo:operationTime:] instead") {
// 群组资料变更回调
// groupInfo 的属性除 groupId 以外，只有包含在 updateKeys 中的属性值有效（其他属性值均为初始化后的默认值）
}
- (void)onGroupInfoChanged:(RCGroupMemberInfo *)operatorInfo
fullGroupInfo:(RCGroupInfo *)fullGroupInfo
changedGroupInfo:(RCGroupInfo *)changedGroupInfo
operationTime:(long long)operationTime {
// 群组资料变更回调
// fullGroupInfo: 全量群组信息（变更后的全量信息）
// changedGroupInfo: 内容有变更的群组信息（只有发生变更的属性）
}
- (void)onGroupInfoChanged:(RCGroupMemberInfo *)operatorInfo
fullGroupInfo:(RCGroupInfo *)fullGroupInfo
changedGroupInfo:(RCGroupInfo *)changedGroupInfo
operationTime:(long long)operationTime {
// 群组资料变更回调
// fullGroupInfo 为群组完整信息
}
- (void)onGroupMemberInfoChanged:(NSString *)groupId
operatorInfo:(RCGroupMemberInfo *)operatorInfo
memberInfo:(RCGroupMemberInfo *)memberInfo
operationTime:(long long)operationTime {
// 群成员资料变更回调
}
- (void)onGroupApplicationEvent:(RCGroupApplicationInfo *)event {
// 群请求事件回调。包含以下事件：
// 1. 用户申请加入群组的 “申请” 或 “结果”
// 2. 邀请加入群组的 “申请” 或 “结果”
}
- (void)onGroupRemarkChangedSync:(NSString *)groupId
operationType:(RCGroupOperationType)operationType groupRemark:(NSString *)groupRemark
operationTime:(long long)operationTime {
// 群组备注名更新多端同步回调事件
}
- (void)onGroupFollowsChangedSync:(NSString *)groupId
operationType:(RCGroupOperationType)operationType
userIds:(NSArray<NSString *> *)userIds
operationTime:(long long)operationTime {
// 群成员特别关注变更多端同步回调事件
}
群组管理
群组管理包含：创建群组、群组资料设置、踢出群组、退出群组、解散群组、群组转让。
创建群组
您可以调用 createGroup 方法创建一个新群组。
接口原型
objc
- (void)createGroup:(RCGroupInfo *)groupInfo
inviteeUserIds:(nullable NSArray<NSString *> *)inviteeUserIds
successBlock:(void (^)(RCErrorCode processCode))successBlock
errorBlock:(void (^)(RCErrorCode errorCode, NSArray<NSString *> * _Nullable errorKeys))errorBlock;
参数说明
| 属性名 | 类型 | 必填 | 描述 |
|---|---|---|---|
| groupInfo | RCGroupInfo | 是 | 群组的相关信息。 |
| inviteeUserIds | NSArray | 否 | 创建群同时邀请的用户 userId 列表。 |
| successBlock | Block | 否 | 成功回调。 |
| errorBlock | Block | 否 | 失败回调，返回对应报错的 key 列表。 |
groupInfo 参数介绍
| 属性名 | 类型 | 必填 | 描述 |
|---|---|---|---|
| groupId | NSString | 是 | 群组 ID：最大长度 64 个字符。支持大小写英文字母与数字的组合。 |
| groupName | NSString | 是 | 群组名称：最大长度 64 个字符。 |
| portraitUri | NSString | 否 | 群头像地址：长度不超过 128 个字符 |
| introduction | NSString | 否 | 群简介：最大长度不超过 512 个字符 |
| notice | NSString | 否 | 群公告：最大长度不超过 1024 个字符 |
| extProfile | NSDictionary<NSString *, NSString *> | 否 | 扩展信息：在现在群信息基础上，开发者可根据自身业务需求添加自定义扩展属性（Key、Value），最多可设置 10 个扩展信息。 自定义属性需要通过融云控制台 群组自定义属性 设置后才能使用，否则返回设置失败 |
| joinPermission | RCGroupJoinPermission | 否 | 加入群的权限：不用验证、需要群主验证（默认）、群管理员及群主、不允许任何人加入，不设置按默认值处理 |
| removeMemberPermission | RCGroupOperationPermission | 否 | 将群成员移出群组的权限：群主（默认）、群主+群管理员、所有人，不设置按默认值处理 |
| invitePermission | RCGroupOperationPermission | 否 | 邀请他人 加入群的权限：群主（默认）、群主+群管理员、所有人，不设置按默认值处理 |
| inviteHandlePermission | RCGroupInviteHandlePermission | 否 | 被邀请加入群组处理的权限：不需要被邀请人同意（默认）、需要被邀请人同意，不设置按默认值处理 |
| groupInfoEditPermission | RCGroupOperationPermission | 否 | 修改群资料的权限：群主（默认）、群主+群管理员、所有人，不设置按默认值处理。该属性仅支持群主修改 |
| memberInfoEditPermission | RCGroupMemberInfoEditPermission | 否 | 设置群成员资料的权限：仅自已、群主+自已、群主+群管理员+自已（默认），不设置按默认值处理 |
inviteeUserIds 参数介绍
您可以选择在创建群的同时，邀请用户加入群组。一次最多允许 30 个用户加入。
邀请的结果受群组的 被邀请人处理权限 (inviteHandlePermission ) 参数影响：
- 需要被邀请人验证时 ( 值为
RCGroupInviteHandlePermissionInviteeVerify)- 创建群组成功后，成功回调的
processCode会返回RC_GROUP_NEED_INVITEE_ACCEPT( 25427 )，被邀请人会收到onGroupApplicationEvent事件，被邀请人需要调用acceptGroupInvite接口同意后才能加入群组。
- 创建群组成功后，成功回调的
- 无需被邀请人验证时 ( 值为
RCGroupInviteHandlePermissionFree)- 创建群组成功后，成功回调的
processCode会返回RC_SUCCESS( 0 )， 表示被邀请人已加入群组。
- 创建群组成功后，成功回调的
提示
- 群组创建的结果不受
processCode的影响，只要回调了success就表示群组创建成功。 - 群组创建成功后，群主会收到群组操作事件
onGroupOperation，操作类型为RCGroupOperationCreate。 - 默认情况下，设置的资料信息不支持审核。如需审核功能，请前往控制台，选择应用配置>安全&审核>IM & 音视频审核>IM 信息托管配置，开启并设置需要审核的内容。
示例代码
objc
RCGroupInfo *groupInfo = [[RCGroupInfo alloc] init];
// 必填项
groupInfo.groupId = @"groupId";
// 必填项
groupInfo.groupName = @"groupName";
// groupInfo 其余字段按需设置
// 邀请加入群组的用户 ID，非必填
NSArray *inviteeUserIds = @[@"user1", @"user2"];
// 创建群组
[[RCCoreClient sharedCoreClient] createGroup:groupInfo inviteeUserIds:inviteeUserIds success:^(RCErrorCode processCode) {
// 群组创建成功
if ( processCode == RC_GROUP_NEED_INVITEE_ACCEPT) {
// 需要被邀请人验证
} else {
// 无需被邀请人验证
}
} error:^(RCErrorCode errorCode, NSArray<NSString *> * _Nullable errorKeys) {
// 创建失败
// errorCode == RC_SERVICE_INFORMATION_AUDIT_FAILED 时，errorKeys 会返回审核未通过的属性名（如 groupName）
}];
修改群组资料
您可以调用 updateGroupInfo 方法修改群组名称、公告、权限等其他资料。修改群组资料时，只有 groupId 为必填项，其他字段可按需设置，接口只会更新有修改的项。
提示
- 群组信息更新成功后，群组内的所有成员会收到
onGroupInfoChanged事件。 - 只有群主可以修改群信息更新权限
groupInfoEditPermission。 - 默认情况下，设置的资料信息不支持审核。如需审核功能，请前往控制台，选择应用配置>安全&审核>IM & 音视频审核>IM 信息托管配置，开启并设置需要审核的内容。
接口原型
objc
- (void)updateGroupInfo:(RCGroupInfo *)groupInfo
successBlock:(void (^)(void))successBlock
errorBlock:(void (^)(RCErrorCode errorCode, NSArray<NSString *> * _Nullable errorKeys))errorBlock;
参数说明
| 属性名 | 类型 | 必填 | 描述 |
|---|---|---|---|
| groupInfo | RCGroupInfo | 是 | 群组的相关信 息。 |
| successBlock | Block | 否 | 成功回调。 |
| errorBlock | Block | 否 | 失败回调，返回对应报错的 key 列表。 |
示例代码
objc
RCGroupInfo *groupInfo = [[RCGroupInfo alloc] init];
groupInfo.groupId = @"groupId";
// 修改群名称
groupInfo.groupName = @"newGroupName";
// 修改群公告
groupInfo.notice = @"newNotice";
// 修改主动加入群权限为 “不用验证”，开发者按需设置
groupInfo.joinPermission = RCGroupJoinPermissionFree;
// 修改群组资料
[[RCCoreClient sharedCoreClient] updateGroupInfo:groupInfo success:^{
// 修改成功
} error:^(RCErrorCode errorCode, NSArray<NSString *> * _Nullable errorKeys) {
// 修改失败
// errorCode == RC_SERVICE_INFORMATION_AUDIT_FAILED 时，errorKeys 会返回审核未通过的属性名（如 groupName）
}];
踢出群组
您可以调用 kickGroupMembers 方法将用户从群组中移除。
踢出成功后，群组内的所有成员会收到 onGroupOperation 事件，操作类型为 RCGroupOperationKick。
接口原型
objc
- (void)kickGroupMembers:(NSString *)groupId
userIds:(NSArray<NSString *> *)userIds
config:(nullable RCQuitGroupConfig *)config
success:(void (^)(void))successBlock
error:(void (^)(RCErrorCode errorCode))errorBlock;
参数说明
| 属性名 | 类型 | 描述 |
|---|---|---|
| groupId | NSString | 群组的 targetId。 |
| userIds | NSArray | 需要踢出群组的用户 userId 列表，一次最多允许踢出 100 个用户。 |
| config | RCQuitGroupConfig | 踢出时可以设置 config 参数（类型 RCQuitGroupConfig），以控制是否移除特别关注的用户、白名单用户、群成员禁言状态。如果不设置，默认为都移除。 |
| successBlock | Block | 成功回调。 |
| errorBlock | Block | 失败 回调。 |
代码示例
objc
RCQuitGroupConfig *config = [[RCQuitGroupConfig alloc] init];
// 关闭移除群组特别关注的用户（默认为 YES）
config.removeFollow = NO;
// 关闭移除白名单（默认为 YES）
config.removeWhiteList = NO;
// 关闭移除群成员禁言状态 （默认为 YES）
config.removeMuteStatus = NO;
[[RCCoreClient sharedCoreClient] kickGroupMembers:@"groupId" userIds:@[@"user1", @"user2"] config:config success:^{
// 踢出成功
} error:^(RCErrorCode errorCode) {
// 踢出失败
}];
退出群组
您可以调用 quitGroup 方法主动退出群组。
退出成功后，群组内的所有成员会收到 onGroupOperation 事件，操作类型为 RCGroupOperationQuit。
接口原型
objc
- (void)quitGroup:(NSString *)groupId
config:(nullable RCQuitGroupConfig *)config
success:(void (^)(void))successBlock
error:(void (^)(RCErrorCode errorCode))errorBlock;
参数说明
| 属性名 | 类型 | 描述 |
|---|---|---|
| groupId | NSString | 群组的 targetId。 |
| config | RCQuitGroupConfig | 退出时可以设置 config 参数（类型 RCQuitGroupConfig），以控制是否移除特别关注的用户、白名单用户、群成员禁言状态。如果不设置，默认为都移除。 |
| successBlock | Block | 成功回调。 |
| errorBlock | Block | 失败回调。 |
示例代码
objc
// 按需配置，这里只是为了演示
RCQuitGroupConfig *config = [[RCQuitGroupConfig alloc] init];
// 关闭移除群组特别关注的用户（默认为 YES）
config.removeFollow = NO;
// 关闭移除白名单（默认为 YES）
config.removeWhiteList = NO;
// 关闭移除群成员禁言状态 （默认为 YES）
config.removeMuteStatus = NO;
[[RCCoreClient sharedCoreClient] quitGroup:@"groupId" config:config success:^{
// 退出成功
} error:^(RCErrorCode errorCode) {
// 退出失败
}];
解散群组
您可以调用 dismissGroup 方法解散群组。
解散群组成功后，群会话消息仍然保留，本地历史消息不做删除处理。
解散成功后，群组内的所有成员会收到 onGroupOperation 事件，操作类型为 RCGroupOperationDismiss。
提示
只有群主有权解散群组。
接口原型
objc
- (void)dismissGroup:(NSString *)groupId
success:(void (^)(void))successBlock
error:(void (^)(RCErrorCode errorCode))errorBlock;
参数说明
| 属性名 | 类型 | 描述 |
|---|---|---|
| groupId | NSString | 群组的 targetId。 |
| successBlock | Block | 成功回调。 |
| errorBlock | Block | 失败回调。 |
示例代码
objc
[[RCCoreClient sharedCoreClient] dismissGroup:@"groupId" success:^{
// 解散成功
} error:^(RCErrorCode errorCode) {
// 解散失败
}];
转让群组
您可以调用 transferGroupOwner 方法将群组转让给其他用户。
- 转让成功后，群组内的所有成员会收到
onGroupOperation事件，操作类型为RCGroupOperationTransfer。 - 若在转让时选择了退出群组，转让成功后，群组内的所有成员除了会收到
onGroupOperation操作类型为RCGroupOperationTransfer的转让事件，还会收到操作类型为RCGroupOperationQuit的退出事件。
提示
只有群主有权转让群组。
接口原型
objc
- (void)transferGroupOwner:(NSString *)groupId
newOwnerId:(NSString *)newOwnerId
quitGroup:(BOOL)quitGroup
config:(nullable RCQuitGroupConfig *)config
success:(void (^)(void))successBlock
error:(void (^)(RCErrorCode errorCode))errorBlock;
参数说明
您可以选择在转让成功后是否退出群组（quitGroup），若设置 YES 退出群组，还可以通过 config 参数（类型为 RCQuitGroupConfig），以控制是否移除特别关注的用户、白名单用户、群成员禁言状态。若未设置 config，默认在退出群组时会全部移除。
| 属性名 | 类型 | 描述 |
|---|---|---|
| groupId | NSString | 群组的 targetId。 |
| newOwnerId | NSString | 新群主用户 userId。 |
| quitGroup | BOOL | 是否退出群组。 |
| config | RCQuitGroupConfig | 退出时可以设置 config 参数（类型 RCQuitGroupConfig），以控制是否移除特别关注的用户、白名单用户、群成员禁言状态。如果不设置，默认为都移除。 |
| successBlock | Block | 成功回调。 |
| errorBlock | Block | 失败回调。 |
示例代码
objc
// 群组 ID
NSString *groupId = @"groupId";
// 新群主 ID
NSString *newOwnerId = @"newOwnerId";
// 转让后退出群组
BOOL quitGroup = YES;
// 按需配置，这里只是为了演示
RCQuitGroupConfig *config = [[RCQuitGroupConfig alloc] init];
// 关闭移除群组特别关注的用户（默认为 YES）
config.removeFollow = NO;
// 关闭移除白名单（默认为 YES）
config.removeWhiteList = NO;
// 关闭移除群成员禁言状态 （默认为 YES）
config.removeMuteStatus = NO;
// 转让群主
[[RCCoreClient sharedCoreClient] transferGroupOwner:groupId newOwnerId:newOwnerId quitGroup:quitGroup config:nil success:^{
// 转让成功
} error:^(RCErrorCode errorCode) {
// 转让失败
}];
群组备注名
功能介绍
- 群组备注名只对用户本人生效。当群组中有新消息产生且该用户不在线时，推送标题将优先显示设置的群备注名。若用户未对该群设置备注名，则默认显示群名称。
- 设置或移除成功后，其他终端会收到群备注名变更多端回调 onGroupRemarkChangedSync。
设置群组备注名
您可以调用 setGroupRemark 方法设置群组备注名。
当需要移除群组备注名时，remark 参数传 nil 或 @""。
接口原型
objc
- (void)setGroupRemark:(NSString *)groupId
remark:(nullable NSString *)remark
success:(void (^)(void))successBlock
error:(void (^)(RCErrorCode errorCode))errorBlock;
参数说明
| 属性名 | 类型 | 描述 |
|---|---|---|
| groupId | NSString | 群组的 targetId。 |
| remark | NSString | 群组备注名。 |
| successBlock | Block | 成功回调。 |
| errorBlock | Block | 失败回调。 |
示例代码
objc
// 设置群组备注名
[[RCCoreClient sharedCoreClient] setGroupRemark:@"groupId" remark:@"remark" success:^{
// 设置成功
} error:^(RCErrorCode errorCode) {
// 设置失败
}];
// 移除群组备注名
// remark 传 nil 或 @""
[[RCCoreClient sharedCoreClient] setGroupRemark:@"groupId" remark:nil success:^{
// 移除成功
} error:^(RCErrorCode errorCode) {
// 移除失败
}];
查询群组备注名
您可以使用 getGroupsInfo 方法获取群组资料，其中包含有关 remark 信息。
接口原型
objc
- (void)getGroupsInfo:(NSArray<NSString *> *)groupIds
success:(void (^)(NSArray<RCGroupInfo *> *groupInfos))successBlock
error:(void (^)(RCErrorCode errorCode))errorBlock;
参数说明
| 属性名 | 类型 | 描述 |
|---|---|---|
| groupIds | NSArray | 群组的 targetId 的列表。 |
| successBlock | Block | 成功回调，返回查询的群组的相关信息 RCGroupInfo 列表。 |
| errorBlock | Block | 失败回调。 |
示例代码
objc
[[RCCoreClient sharedCoreClient] getGroupsInfo:@[@"groupId"] success:^(NSArray<RCGroupInfo *> * _Nonnull groupInfos) {
RCGroupInfo *groupInfo = groupInfos.firstObject;
NSString *remark = groupInfo.remark;
// 获取成功
} error:^(RCErrorCode errorCode) {
// 获取失败
}];
RCGroupInfo