iOS

频道黑白名单

更新时间: 2024/03/14 17:08:38

频道黑白名单用于管控频道对服务器成员是否可见。圈组支持选择服务器成员加入黑名单或白名单,或者选择身份组将身份组所有成员批量加入黑名单或白名单。

被加入黑白名单的用户,即为黑白名单成员;被加入黑名单或白名单的身份组即为黑白名单身份组

功能介绍

频道可见性的管控属于圈组消息流转中的一环,管控方式根据频道的查看模式存在区分,具体如下:

频道查看模式
可见性管控
公开 通过频道黑名单进行管控,频道对黑名单中的服务器成员不可见,即这些成员无法访问该频道,其他服务器成员均可访问该频道
私密 通过频道白名单进行管控,频道对白名单中的服务器成员可见,即这些成员可访问该频道,其他服务器成员均无法访问该频道

前提条件

使用限制

频道黑白名单存在如下与黑白名单相关的限制:

  • 单个频道的黑白名单成员人数上限,默认为 1000。
  • 单个频道可设置的黑白名单身份组的数量上限,默认为 20。

若需要扩展上限,可在控制台配置圈组子功能项(公开私密频道的黑白名单成员数channel 公开私密频道的黑白名单身份组对象数),具体请参考开通和配置圈组功能

实现方法

管理黑白名单成员

更新频道黑白名单成员

用户可调用updateBlackWhiteMembers:completion:方法更新频道的黑白名单,将服务器成员加入或移出黑白名单,从而管控服务器成员是否可访问频道。

调用该方法需拥有管理黑白名单的权限(NIMQChatPermissionTypeManageBlackWhiteList)。


NIMQChatUpdateChannelBlackWhiteMembersParam为其入参结构,具体参数说明如下:

参数 类型 说明
serverId unsigned long long 服务器 ID
channelId unsigned long long 频道 ID
type NIMQChatChannelMemberRoleType 黑白名单类型
  • NIMQChatChannelMemberRoleTypeWhite:白名单
  • NIMQChatChannelMemberRoleTypeBlack:黑名单
opeType NIMQChatChannelMemberRoleOpeType 黑白名单操作类型:
  • NIMQChatChannelMemberRoleOpeTypeAdd:添加
  • NIMQChatChannelMemberRoleOpeTypeRemove:移除
accids NSArray< NSString * > * IM 账号(accid)列表:添加或者移除到黑白名单的accid列表

示例代码如下:

id<NIMQChatChannelManager> qchatChannelManager = [[NIMSDK sharedSDK] qchatChannelManager];
NIMQChatUpdateChannelBlackWhiteMembersParam * param = [[NIMQChatUpdateChannelBlackWhiteMembersParam alloc] init];
param.serverId = 123456;
param.channelId = 121212;
// 添加白名单成员
param.type = NIMQChatQChatChannelMemberRoleTypeWhite;
param.opeType = NIMQChatQChatChannelMemberRoleOpeTypeAdd;
param.accids = @[@"yunxin1", @"yunxin2", @"yunxin3"];
[qchatChannelManager updateBlackWhiteMembers:param
    completion:^(NSError *error) {
    // your code
}];

分页查询频道黑白名单成员

调用getBlackWhiteMembersByPage:completion方法,可分页查询频道黑白名单。调用时需要传入查询的 serverIdchannelId、黑白名单类型、查询锚点时间戳timeTag 和查询数量限制limit

调用该方法需要拥有管理频道黑白名单的权限(QChatRoleResource.MANAGE_BLACK_WHITE_LIST)。


示例代码如下:

id<NIMQChatChannelManager> qchatChannelManager = [[NIMSDK sharedSDK] qchatChannelManager];
NIMQChatGetChannelBlackWhiteMembersByPageParam * param = [[NIMQChatGetChannelBlackWhiteMembersByPageParam alloc] init];
param.serverId = 123456;
param.channelId = 121212;
param.timeTag = 0;
param.limit = 20;
// 查询白名单成员
param.type = NIMQChatQChatChannelMemberRoleTypeWhite;
[qchatChannelManager getBlackWhiteMembersByPage:param
    completion:^(NSError *__nullable error, NIMQChatGetChannelBlackWhiteMembersByPageResult *__nullable result) {
    // your code
}];

批量查询频道黑白名单成员

调用getExistingChannelBlackWhiteMembers:completion:方法可根据传入的用户账号(accid)列表查询其中已被加入的黑白名单的用户。

单次调用最多可传入 100 个 accid

示例代码如下:

id<NIMQChatChannelManager> qchatChannelManager = [[NIMSDK sharedSDK] qchatChannelManager];
NIMQChatGetExistingChannelBlackWhiteMembersParam * param = [[NIMQChatGetExistingChannelBlackWhiteMembersParam alloc] init];
param.serverId = 123456;
param.channelId = 121212;
// 添加白名单成员
param.type = NIMQChatQChatChannelMemberRoleTypeWhite;
param.accIds = @[@"yunxin1", @"yunxin2", @"yunxin3"];
[qchatChannelManager getExistingChannelBlackWhiteMembers:param
    completion:^(NSError *__nullable error, NIMQChatGetExistingChannelBlackWhiteMembersResult *__nullable memberArray) {
    // your code
}];

管理黑白名单身份组

更新频道黑白名单身份组

调用updateBlackWhiteRole:completion:方法可选择身份组,将所选身份组的成员批量加入或移出频道黑白名单,加入黑白名单的身份组即为黑白名单身份组。调用时需要传入服务器 ID(serverId)、频道 ID(channelId)、黑白名单类型、黑白名单操作类型和身份组 ID 列表。、

调用该方法需要拥有管理频道黑白名单的权限(NIMQChatPermissionTypeManageBlackWhiteList)。


示例代码如下:

id<NIMQChatChannelManager> qchatChannelManager = [[NIMSDK sharedSDK] qchatChannelManager];
NIMQChatUpdateChannelBlackWhiteRoleParam * param = [[NIMQChatUpdateChannelBlackWhiteRoleParam alloc] init];
param.serverId = 123456;
param.channelId = 121212;
// 修改白名单成员
param.type = NIMQChatQChatChannelMemberRoleTypeWhite;
param.opeType = NIMQChatQChatChannelMemberRoleOpeTypeAdd;
param.roleId = 111;
[qchatChannelManager updateBlackWhiteRole:param
    completion:^(NSError *error) {
    // your code
}];

分页查询黑白名单身份组列表

调用getBlackWhiteRolesByPage:completion:方法可分页查询频道的黑白名单身份组列表。 调用时需要传入服务器 ID、频道 ID、黑白名单类型、查询锚点时间戳 timeTag 和查询数量限制 limit

调用该方法需要拥有管理频道黑白名单的权限(NIMQChatPermissionTypeManageBlackWhiteList)。


示例代码如下:

id<NIMQChatChannelManager> qchatChannelManager = [[NIMSDK sharedSDK] qchatChannelManager];
NIMQChatGetChannelBlackWhiteRolesByPageParam * param = [[NIMQChatGetChannelBlackWhiteRolesByPageParam alloc] init];
param.serverId = 123456;
param.channelId = 121212;
param.timeTag = 0;
param.limit = 20;
// 查询白名单成员
param.type = NIMQChatQChatChannelMemberRoleTypeWhite;
[qchatChannelManager getBlackWhiteRolesByPage:param
    completion:^(NSError *__nullable error, NIMQChatGetChannelBlackWhiteRolesByPageResult *__nullable result) {
    // your code
}];

批量查询黑白名单身份组列表

调用getExistingChannelBlackWhiteRoles:completion:方法可根据传入的身份组 ID 列表批量查询其中被加入黑白名单的身份组。

单次调用最多可传入 100 个身份组的 ID。

示例代码如下:

id<NIMQChatChannelManager> qchatChannelManager = [[NIMSDK sharedSDK] qchatChannelManager];
NIMQChatGetExistingChannelBlackWhiteRolesParam * param = [[NIMQChatGetExistingChannelBlackWhiteRolesParam alloc] init];
param.serverId = 123456;
param.channelId = 121212;
// 白名单
param.type = NIMQChatQChatChannelMemberRoleTypeWhite;
param.roleIds = @[@"111", @"222", @"333"];
[qchatChannelManager getExistingChannelBlackWhiteRoles:param
    completion:^(NSError *__nullable error, NIMQChatGetExistingChannelBlackWhiteRolesResult *__nullable roleArray) {
    // your code
}];

相关系统通知

圈组系统通知的类型在NIMQChatSystemNotificationType枚举中定义,与频道黑白名单相关的内置系统通知类型如下:

枚举值 说明
NIMQChatSystemNotificationTypeChannelUpdateWhiteBlackMember 更新“频道黑白名单成员”
NIMQChatSystemNotificationTypeChannelUpdateWhiteBlackRole 更新“频道黑白名单身份组”

这两种系统通知的接收条件,请参见服务端文档的频道相关事件通知

此文档是否对你有帮助?
有帮助
去反馈
  • 功能介绍
  • 前提条件
  • 使用限制
  • 实现方法
  • 管理黑白名单成员
  • 更新频道黑白名单成员
  • 分页查询频道黑白名单成员
  • 批量查询频道黑白名单成员
  • 管理黑白名单身份组
  • 更新频道黑白名单身份组
  • 分页查询黑白名单身份组列表
  • 批量查询黑白名单身份组列表
  • 相关系统通知