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

被加入黑白名单的用户，即为黑白名单成员；被加入黑名单或白名单的身份组即为黑白名单身份组。

功能介绍

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

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

前提条件

• 已注册onRecvSystemNotification:监听圈组的系统通知。示例代码参见圈组系统通知收发。

  具体与频道黑白名单相关的系统通知类型，见本文末尾的相关系统通知。

• 已创建频道。

实现方法

管理黑白名单成员

更新频道黑白名单成员

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

• 调用该方法需拥有管理黑白名单的权限（NIMQChatPermissionTypeManageBlackWhiteList）。
• 单个频道的黑白名单成员人数上限，默认为 1000。 可在云信控制台配置该数量上限，配置路径：在云信控制台选择应用，进入IM 专业版 > 功能权限开通 > 拓展配置 > 圈组 > 高级配置 > 公开私密频道的黑白名单成员数。

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方法，可分页查询频道黑白名单。调用时需要传入查询的 serverId、channelId、黑白名单类型、查询锚点时间戳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）。

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

  可在云信控制台配置该数量上限

  在云信控制台选择应用，进入IM 免费版/专业版 > 功能权限开通 > 拓展配置 > 圈组 > 高级配置 > channel公开私密频道的黑白名单身份组对象数即可配置。
  

示例代码如下：

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	更新“频道黑白名单身份组”

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