聊天室
更新时间： 2024/11/25 10:11:32
本文已废弃，请前往聊天室概述等聊天室功能文档查看相关说明。
功能概述
云信提供聊天室功能，人数无上限，用户可自由进出聊天室。聊天室的创建与关闭需要通过服务端API来完成。
聊天室原型：
objc@interface NIMChatroom : NSObject
/**
* 聊天室Id
*/
@property (nullable,nonatomic,copy) NSString *roomId;
/**
* 聊天室名
*/
@property (nullable,nonatomic,copy) NSString *name;
/**
* 公告
*/
@property (nullable,nonatomic,copy) NSString *announcement;
/**
* 创建者
*/
@property (nullable,nonatomic,copy) NSString *creator;
/**
* 第三方扩展字段，长度限制4K
*/
@property (nullable,nonatomic,copy) NSString *ext;
/**
* 当前在线用户数量
*/
@property (nonatomic,assign) NSInteger onlineUserCount;
/**
* 直播地址。当与直播业务搭配时，可以将直播推拉流地址设置于此。
*/
@property (nullable,nonatomic,copy) NSString *broadcastUrl;
/**
* 聊天室队列修改权限等级
*/
@property (nonatomic,assign) NIMChatroomQueueModificationLevel queueModificationLevel;
/**
* 聊天室是否正在全员禁言标记，禁言后只有管理员可以发言
*/
- (BOOL)inAllMuteMode;
@end
进入聊天室
用户要在聊天室收发消息之前，必须先调用接口进入聊天室。聊天室只允许用户手动进入，无法进行邀请。支持同时进入10个聊天室。
进入聊天室可以有两种方式：以独立模式进入聊天室和非独立模式进入聊天室。
-
独立模式是指在IM处于未登录的情况下，进入聊天室的方式，针对只需要聊天室功能的业务场景。
-
非独立模式是指先完成IM登录，再进入聊天室的方式，针对需要IM和聊天室功能的业务场景。
-
由进入聊天室方法中的
NIMChatroomIndependentMode参数设置聊天室的模式，默认为 非独立模式。
objc@protocol NIMChatroomManager <NSObject>
/**
* 进入聊天室
*
* @param request 进入聊天室请求
* @param completion 进入完成后的回调
*/
- (void)enterChatroom:(NIMChatroomEnterRequest *)request
completion:(NIMChatroomEnterHandler)completion;
@end
NIMChatroomEnterRequest 参数列表
参数 |
类型 |
说明 |
|---|---|---|
| roomId | NSString | 聊天室 ID |
| roomNickname | NSString | 聊天室昵称 |
| roomAvatar | NSString | 聊天室头像，上层可以自主设置在聊天室内的头像，没有设置则使用用户本身的信息 |
| roomExt | NSString | 本人的聊天室成员信息拓展字段，仅对当次进入有效 |
| roomNotifyExt | NSString | 聊天室事件通知拓展字段 |
| tags | NSString | 登录标签，可以设置多个，json_array格式，例子：["tag1", "tag2"] |
| notifyTargetTags | NSString | 登录登出通知的目标标签，是一个标签表达式，见TagCalculator和TagPattern |
| retryCount | NSInteger | 聊天室重连次数,默认为三次，设置成 0 后一旦一次连接失败后，SDK 将不在重试。 APP 可以根据自己的需求进行设置 |
| mode | NIMChatroomIndependentMode | 聊天室独立模式. 默认为 nil。 |
| loginAuthType | NIMChatroomLoginAuthType | 鉴权方式 |
| dynamicTokenHandler | NIMProvideChatroomDynamicTokenHandler | 动态token回调 |
| loginExt | NSString | 扩展字段 |
| locationX | NSDecimalNumber | 坐标x |
| locationY | NSDecimalNumber | 坐标y |
| locationZ | NSDecimalNumber | 坐标z |
| distance | NSDecimalNumber | 订阅的消息的距离 |
| antispamBusinessId | NSString | 对某些资料内容另外的反垃圾的业务ID |
其中：
-
进入聊天室时设置。每次消息中都会带上的扩展
roomExt，这个字段可以放入用户在聊天室的自定义信息，如权限，头衔等等。当本方发出消息或者进行聊天室操作引发聊天室通知，这个扩展信息会置入消息的NIMMessage - messageExt - roomExt(messageExt需要转换成NIMMessageChatroomExtension)。 -
进入聊天室时设置。其他聊天室在线成员会收到该用户进入聊天室的通知消息，这个扩展信息会置入聊天室通知消息的
NIMChatroomNotificationContent - notifyExt里。
鉴权方式
聊天室通过loginAuthType字段支持三种鉴权方式。
objctypedef NS_ENUM(NSInteger, NIMChatroomLoginAuthType) {
NIMChatroomLoginAuthTypeDefault = 0,
NIMChatroomLoginAuthTypeDynamicToken = 1,
NIMChatroomLoginAuthTypeThirdPart = 2,
};
-
默认鉴权方式（静态 token 鉴权）
-
动态token鉴权
如果配置为动态token鉴权方式，则需要实现动态token回调。进入聊天室时，SDK通过此回调实时获取token。
-
NIMChatroomLoginAuthType原型
-
NIMProvideChatroomDynamicTokenHandler原型
objc/**
* 聊天室动态token block
*/
typedef NSString*(^NIMProvideChatroomDynamicTokenHandler)(NSString * __nullable roomId, NSString * __nullable account);
- 第三方回调鉴权
非独立模式
非独立模式较为简单，在IM处于登录状态时，无需设置NIMChatroomIndependentMode，直接调用进入聊天室方法即可。
独立模式
当选择以独立模式进入聊天室时，必须设置NIMChatroomIndependentMode的各项属性。
NIMChatroomIndependentMode 参数列表：
参数 |
类型 |
说明 |
|---|---|---|
| username | NSString | 独立模式下的用户名，若设置为 nil ，SDK 将使用自动生成的匿名账号进行登录。在匿名模式下，NIMChatroomEnterRequest 必须设置昵称和头像信息 |
| token | NSString | 独立模式下的 Token。 当用户名为空时，token 无效。 |
| chatroomAppKey | NSString | 聊天室 AppKey, 可选填, 如果不填则使用云信IM AppKey。 |
进入聊天室后，可以通过如下接口获取进入该聊天室时所设置的模式：
objc@protocol NIMChatroomManager <NSObject>
/**
* 获取聊天室登录使用的模式
*/
- (NSInteger)chatroomAuthMode:(NSString *)roomId;
- 匿名模式与非匿名模式
独立模式下又可分为匿名模式与非匿名模式。匿名模式只能收消息，不能发消息。
当NIMChatroomIndependentMode - username设置为nil时，则为匿名模式。SDK 将使用自动生成的匿名账号进行登录。在匿名模式下，NIMChatroomEnterRequest中必须设置昵称和头像信息。
- 获取聊天室地址
独立模式由于不依赖IM连接，SDK无法自动获取聊天室服务器的地址，需要客户端向开发者应用服务器请求该地址，而应用服务器需要向网易云信服务器请求，然后将请求结果原路返回给客户端，即请求路径为：客户端 <-> 开发者应用服务器 <-> 网易云信服务器(API：请求聊天室地址)。
首先需要注册获取聊天室地址的回调方法：
objc@interface NIMChatroomIndependentMode : NSObject
/**
* 注册获取聊天室地址的回调方法
*
* @param handler 获取聊天室地址信息的方法
* @discussion 在进入聊天室和刷新聊天室 IP 时，SDK 都会主动调用这个回调方法，并传入相应的两个参数 `roomId` 和 `callback`。当前回调接口要求上层使用 `roomId` 走自己的网络请求获取对应聊天室地址并通过 callback 回调给 SDK。需要注意的时候无论请求成功，都需要通过 callback 进行回调，否则进入聊天室请求将会一直等待。同时此接口只需注册一次即可，多次注册将使用后者覆盖前者。
*/
+ (void)registerRequestChatroomAddressesHandler:(NIMRequestChatroomAddressesHandler)handler
@end
代码示例
objc [NIMChatroomIndependentMode registerRequestChatroomAddressesHandler:^(NSString * _Nonnull roomId, NIMRequestChatroomAddressesCallback _Nonnull callback) {
[YourHTTPService request:roomId completion:^(NSError *error,NSArray *addresses)
{
//无论请求是否成功，都需要进行回调
if(callback)
{
callback(error,addresses);
}
}];
}];
其中 YourHTTPService 为 App 的应用服务器接口，应用服务器可以调用云信服务端的请求聊天室地址 API 来获取具体的聊天室地址。
即针对独立模式进入聊天室，需要进行以下步骤：
- 设置
NIMChatroomIndependentMode，特别注意获取聊天室地址的回调方法。 - 初始化
NIMChatroomEnterRequest，并完成赋值。 - 调用进入聊天室的方法。
聊天室多端登录
支持设置聊天室多端登录策略，即当同账号在不同客户端登录时，是否可以同时进入同一个聊天室。可以进入云信控制台选择应用 > IM专业版 > 功能配置 > 聊天室配置 > 聊天室多端登录配置进行设置。
- 只允许一端登录，Windows、Web、Android、iOS 彼此互踢。同一账号仅允许在一台设备上登录。当该账号在另一台设备上成功登录时，新设备会将旧设备踢下线。
- 各端均可以同时登录在线。最多可支持10个设备同时在线，在设备数上限内，所有的新设备再次登录，均不会将在线的旧设备踢下线。
控制台修改多端互踢的逻辑之后，下次新的设备登录时才会基于新的多端互踢策略进行校验，已经建立连接的设备不会因为策略的修改被强制踢出。
如果某台设备重复登录同一个聊天室，后登录的会将前面的长连接断开，此时会再触发一次进入聊天室的抄送，但是不会触发退出聊天室的抄送。关于进出聊天室（eventType=9）的抄送请参见聊天室事件抄送。
监听聊天室连接变化
进入聊天室会建立新的连接，不同的聊天室对应着不同的连接，开发者可以监听连接状态做一些业务处理。
objc@protocol NIMChatroomManagerDelegate <NSObject>
/**
* 监听聊天室连接状态变化
*
* @param roomId 聊天室Id
* @param state 当前状态
*/
- (void)chatroom:(NSString *)roomId
connectionStateChanged:(NIMChatroomConnectionState)state;
@end
NIMChatroomConnectionState 枚举列表
参数 |
值 | 说明 |
|---|---|---|
| NIMChatroomConnectionStateEntering | 0 | 正在进入聊天室 |
| NIMChatroomConnectionStateEnterOK | 1 | 进入聊天室成功 |
| NIMChatroomConnectionStateEnterFailed | 2 | 进入聊天室失败 |
| NIMChatroomConnectionStateLoseConnection | 3 | 和聊天室失去连接 |
当成功进入聊天室后，若再发生掉线问题时，SDK 将进行自动重连，无需开发者再次调用进入房间接口。
在重连时，可能遇到一些特殊网络错误（如聊天室用户被封禁，聊天室状态异常），会触发以下回调，开发者应该在这个回调中退出聊天室界面。
objc@protocol NIMChatroomManagerDelegate <NSObject>
/**
* 聊天室自动登录出错
*
* @param roomId 聊天室Id
* @param error 自动登录出错原因
*/
- (void)chatroom:(NSString *)roomId
autoLoginFailed:(NSError *)error;
@end
监听被踢出
当用户被踢出聊天室或者聊天室关闭时，会触发被踢回调：
objc@protocol NIMChatroomManagerDelegate <NSObject>
/**
* 被踢回调
*
* @param roomId 被踢的聊天室Id
* @param result 被踢的结果详情
*/
- (void)chatroomBeKicked:(NIMChatroomBeKickedResult *)result;
@end
被踢详情 NIMChatroomBeKickedResult
objc/**
* 聊天室被踢结果
*/
@interface NIMChatroomBeKickedResult : NSObject
/**
* 被踢的聊天室 Id
*/
@property (nonatomic, copy) NSString *roomId;
/**
* 被踢的原因
*/
@property (nonatomic, assign) NIMChatroomKickReason reason;
/**
* 被踢的扩展字段
*/
@property (nonatomic, copy) NSString *ext;
@end
NIMChatroomKickReason 枚举列表
参数 |
值 | 说明 |
|---|---|---|
| NIMChatroomKickReasonInvalidRoom | 1 | 聊天室已经解散 |
| NIMChatroomKickReasonByManager | 2 | 被聊天室管理员踢出 |
| NIMChatroomKickReasonByConflictLogin | 3 | 多端被踢 |
| NIMChatroomKickReasonBlacklist | 5 | 被拉黑 |
离开聊天室
离开聊天室时，会断开聊天室对应的连接，并不再收到关于此聊天室的任何消息。
objc@protocol NIMChatroomManager <NSObject>
/**
* 离开聊天室
*
* @param roomId 聊天室ID
* @param completion 离开聊天室的回调
*/
- (void)exitChatroom:(NSString *)roomId
completion:(NIMChatroomHandler)completion;
@end
参数列表
参数 |
类型 |
说明 |
|---|---|---|
| roomId | NSString | 聊天室 ID |
| completion | NIMChatroomHandler | 离开聊天室的回调 |
聊天室消息收发
聊天室消息收发接口与 IM 的消息收发接口统一，在发送消息时指定会话类型为聊天室即可。会话 id 即为聊天室 id。值得注意的是：针对聊天室消息，SDK不会持久化在本地。
部分重要参数如下：
参数 |
类型 |
说明 |
|---|---|---|
messageType |
NIMMessageType |
消息类型 messageObject字段 |
session |
NIMSessionType |
会话类型，包括单聊、群聊和聊天室等 |
notifyTargetTags |
NSString * | 聊天室消息的目标表达式。目标表达式相关说明参见目标表达式 |
locationX |
NSNumber | X坐标，用于聊天室空间消息 |
locationY |
NSNumber | Y坐标，用于聊天室空间消息 |
locationZ |
NSNumber | Z坐标，用于聊天室空间消息 |
toAccIds |
NSArray<NSString*> | 消息接收者列表，用于聊天室定向消息，最多 100 个用户 |
- 为保证用户体验（如避免服务器过载），目前针对消息接收，有两套流控机制。第一套针对普通消息，聊天室用户每秒至多可接收20条，超过部分会因为流控随机丢弃。第二套针对高优先级消息，每秒至多接收10条，超过部分无法保证不丢失。
- 为避免丢失重要消息（通常为服务端消息），可将发送聊天室消息的 HighPriority 参数设置为 true 实现高优先级接收服务端消息，进而保证高优先级消息流控上限内（每秒10条）的重要消息不丢失。详情请参见发送聊天室消息中的 HighPriority 参数说明。
更新坐标
objc/**
* 更新坐标
* @param location 当前坐标和有效距离
* @param completion 请求完成回调
*/
-(void)updateLocation:(nonnull NIMChatroomLocation *)location
completion:(nullable NIMChatroomHandler)completion;
- NIMChatroomLocation 参数列表
| 参数 | 类型 | 说明 |
|---|---|---|
| roomId | NSString | 聊天室ID |
| locationX | NSNumber | X坐标 |
| locationY | NSNumber | Y坐标 |
| locationZ | NSNumber | Z坐标 |
| distance | NSNumber | 距离 |
聊天室通知消息
在聊天室中进行部分操作会产生聊天室通知消息。目前当出现以下事件，会产生通知消息：
NIMChatroomEventType |
说明 |
|---|---|
| NIMChatroomEventTypeEnter = 301 | 成员进入聊天室 |
| NIMChatroomEventTypeExit = 302 | 成员离开聊天室 |
| NIMChatroomEventTypeAddBlack = 303 | 成员被拉黑 |
| NIMChatroomEventTypeRemoveBlack = 304 | 成员被取消拉黑 |
| NIMChatroomEventTypeAddMute = 305 | 成员被设置禁言 |
| NIMChatroomEventTypeRemoveMute = 306 | 成员被取消禁言 |
| NIMChatroomEventTypeAddManager = 307 | 设置为管理员 |
| NIMChatroomEventTypeRemoveManager = 308 | 移除管理员 |
| NIMChatroomEventTypeAddCommon = 309 | 设置为固定成员 |
| NIMChatroomEventTypeRemoveCommon = 310 | 取消固定成员 |
| NIMChatroomEventTypeClosed = 311 | 聊天室被关闭 |
| NIMChatroomEventTypeInfoUpdated = 312 | 聊天室信息更新 |
| NIMChatroomEventTypeKicked = 313 | 聊天室成员被踢 |
| NIMChatroomEventTypeAddMuteTemporarily = 314 | 聊天室成员被临时禁言 |
| NIMChatroomEventTypeRemoveMuteTemporarily = 315 | 聊天室成员被解除临时禁言 |
| NIMChatroomEventTypeMemberUpdateInfo = 316 | 聊天室成员主动更新了聊天室的角色信息 |
| NIMChatroomEventTypeQueueChange = 317 | 聊天室通用队列变更的通知 |
| NIMChatroomEventTypeRoomMuted = 318 | 聊天室被禁言了，只有管理员可以发言,其他人都处于禁言状态 |
| NIMChatroomEventTypeRoomUnMuted = 319 | 聊天室解除禁言状态 |
| NIMChatroomEventTypeQueueBatchChange = 320 | 聊天室通用队列批量变更的通知 |
| NIMChatroomEventTypeRecall = 323 | 聊天室消息撤回 |
| NIMChatroomEventTypeQueueBatchAdd = 324 | 批量添加聊天室队列元素 |
特别地，支持设置成员进出聊天室通知是否下发：
- 应用级别：网易云信控制台 > 选择应用 > 聊天室用户进出消息系统下发 > 开启/关闭。
- 单个聊天室：调用服务端API「关闭指定聊天室进出通知」。
- 如果希望查询聊天室消息历史时，也不要包含聊天室用户进出消息，请联系商务顾问申请关闭「聊天室用户进出消息历史存储」。
所有的聊天室通知都以消息 NIMMessage 的形式封装。聊天室通知的解析如下：
-
判断消息是否为通知消息。
- 判断
NIMMessage - messageType字段是否为NIMMessageTypeNotification。
- 判断
-
再判断是否为聊天室通知消息。
- 将
NIMMessage - messageObject强类型转换为NIMNotificationObject。 - 判断转换后的
NIMNotificationObject - notificationType字段是否为NIMNotificationTypeChatroom。
- 将
-
解析具体内容。
- 将
NIMNotificationObject - content字段强类型转换为NIMChatroomNotificationContent。
- 将
聊天室通知内容 NIMChatroomNotificationContent 的字段说明：
eventType: 聊天室通知事件类型，表示具体属于哪一种聊天室通知，通知种类由NIMChatroomEventType枚举定义。source: 通知的操作者，表示谁触发了这个通知，被封装为NIMChatroomNotificationMember类型。targets: 通知的被操作者，表示这个通知影响的用户，被封装为NSArray类型，NSArray中每个元素被封装成NIMChatroomNotificationMember类型。notifyExt: 通知的扩展字段，这个扩展字段是由每个触发通知的操作接口定义的。如进入聊天室时设置的NIMChatroomEnterRequest - roomNotifyExtext: 目前只有 临时禁言/队列操作 事件才有，记录禁言时长信息、队列操作具体信息等。revokedMessageId: 被撤回消息的IDrevokedMessageTime: 被撤回消息的时间
下面针对聊天室队列元素变更通知消息的解析进行示例：
在 NIMChatroomNotificationContent 的 eventType 事件中，有两种事件属于聊天室变更事件分别为NIMChatroomEventTypeQueueChange与NIMChatroomEventTypeQueueBatchChange。
消息解析示例:
objc- (void)onRecvMessages:(NSArray<NIMMessage *> *)messages
{
for (NIMMessage *message in messages)
{
if (message.messageType == NIMMessageTypeNotification)
{
if (notification.notificationType == NIMNotificationTypeChatroom)
{
NIMChatroomNotificationContent *content = (NIMChatroomNotificationContent *)notification.content;
NSDictionary *info = content.ext;
if (content.eventType == NIMChatroomEventTypeQueueChange)
{
//change type
//NIMChatroomQueueChangeTypeOffer, NIMChatroomQueueChangeTypePoll, NIMChatroomQueueChangeTypeDrop,NIMChatroomQueueChangeTypeUpdate
NIMChatroomQueueChangeType changeType = [[info objectForKey:NIMChatroomEventInfoQueueChangeTypeKey] integerValue];
//key
NSString *key = [info objectForKey:NIMChatroomEventInfoQueueChangeItemKey];
//value
NSString *value = [info objectForKey:NIMChatroomEventInfoQueueChangeItemValueKey];
//deal with key and value
}
if (content.eventType == NIMChatroomEventTypeQueueBatchChange)
{
//change type
//NIMChatroomQueueBatchChangeTypePartClear
NIMChatroomQueueBatchChangeType changeType = [[info objectForKey:NIMChatroomEventInfoQueueChangeTypeKey] integerValue];
NSDictionary *batch = [info objectForKey:NIMChatroomEventInfoQueueChangeItemsKey];
for (NSString *key in batch)
{
NSString *value = [batch objectForKey:key];
//deal with key and value
}
}
}
}
}
}
- 关于例子中在
ext中解析出来的changeType
若NIMChatroomNotificationContent 的 eventType 为 NIMChatroomEventTypeQueueChange，
则changeType为NIMChatroomQueueChangeType:
- 无效或未知变更类型 NIMChatroomQueueChangeTypeInvalid
- 新增元素 NIMChatroomQueueChangeTypeOffer
- 取出元素 NIMChatroomQueueChangeTypePoll
- 清空元素 NIMChatroomQueueChangeTypeDrop
- 更新元素 NIMChatroomQueueChangeTypeUpdate
若NIMChatroomNotificationContent 的 eventType 为 NIMChatroomEventTypeQueueBatchChange，
则changeType为NIMChatroomQueueBatchChangeType:
- 无效或未知变更类型 NIMChatroomQueueBatchChangeTypeInvalid
- 部分批量清理(发生在提交元素的用户掉线时，清理这个用户对应的key) NIMChatroomQueueBatchChangeTypePartClear
查询云端历史消息
聊天室没有离线消息和漫游消息。可以通过下面的接口查询聊天室消息历史。服务器只保存最近10天的聊天室消息记录。但是10天之前发送的文件(例如：图片、音频、视频等)，其url链接地址仍然是有效的(不过开发者需要自行保存这些url，因为无法通过已过期的消息来查询这些文件url)。如需延长「聊天室历史消息天数」，请联系商务顾问。
objc@protocol NIMChatroomManager <NSObject>
/**
* 查询服务器保存的聊天室消息记录
*
* @param roomId 聊天室ID
* @param option 查询选项
* @param result 完成回调
*/
- (void)fetchMessageHistory:(NSString *)roomId
option:(NIMHistoryMessageSearchOption *)option
result:(NIMFetchChatroomHistoryBlock)completion;
@end
NIMHistoryMessageSearchOption 参数列表 (部分字段对聊天室消息搜索选项无效，已过滤)
| 参数 | 类型 |
说明 |
|---|---|---|
| startTime | NSTimeInterval | 检索消息起始时间，需要检索的起始时间,没有则传入0。即以该时间为起点，往前或往后查询。 |
| limit | NSUInteger | 检索条数，最大限制 100 条 |
| order | NIMMessageSearchOrder | 检索顺序 |
| messageTypes | NSArray<NSNumber *> | 查询的消息类型，默认为 nil ，搜索全类型。 |
根据标签查询历史消息
根据标签（Tags）在云端查询聊天室的历史消息。
以 fromTime 和 toTime（单位秒）为时间戳，选择查询方向，指定一种或多种标签和消息类型，往前或者往后拉取 limit 条消息。
objc/**
* 通过标签查询消息
* @param param 查询参数
* @param completion 完成回调
*/
- (void)getMessagesByTags:(NIMGetMessagesByTagsParam *)param
completion:(nullable NIMGetMessagesByTagsHandler)completion;
NIMGetMessagesByTagsParam 参数列表
参数 |
类型 |
说明 |
|---|---|---|
| roomId | NSInteger | 聊天室 ID（必填） |
| tags | NSArray<NSString *> | 标签列表，支持传入多个标签同时查询（必填） |
| messageTypes | NSArray<NSNumber *> | 消息类型列表，查询指定消息类型的消息，默认查询全部消息类型 |
| fromTime | NSNumber * | 起始时间，单位秒。被转换为NSTimeInterval类型使用 |
| toTime | NSNumber * | 结束时间，单位秒。被转换为NSTimeInterval类型使用 |
| limit | NSNumber * | 可查询的最大消息数量。被转换为NSInteger类型使用 |
| reverse | NSNumber * | 查询方向。被转换为BOOL类型使用 |
示例代码如下：
objc[[NIMSDK sharedSDK].chatroomManager getMessagesByTags:param completion:^(NSError * __nullable error,NSArray<NIMMessage *> * __nullable messages) {
if (error) {
// 获取消息失败
} else {
// 获取消息成功
}
}];
聊天室信息管理
获取聊天室信息
此接口可以远程获取聊天室信息，NIM SDK 不会缓存聊天室信息，开发者需要根据业务自己做好缓存。
objc@protocol NIMChatroomManager <NSObject>
/**
* 获取聊天室信息
*
* @param roomId 聊天室ID
* @param completion 获取聊天室信息的回调
* @discussion 只有已进入聊天室才能够获取对应的聊天室信息
*/
- (void)fetchChatroomInfo:(NSString *)roomId
completion:(NIMChatroomInfoHandler)completion;
@end
参数列表
| 参数 | 类型 |
说明 |
|---|---|---|
| roomId | NSString | 聊天室 ID |
| completion | NIMChatroomInfoHandler | 离开聊天室的回调 |
修改聊天室信息
objc@protocol NIMChatroomManager <NSObject>
/**
* 修改聊天室信息
*
* @param request 聊天室修改请求
* @param completion 修改后完成的回调
*/
- (void)updateChatroomInfo:(NIMChatroomUpdateRequest *)request
completion:(nullable NIMChatroomHandler)completion;
@end
NIMChatroomUpdateRequest 参数列表
参数 |
类型 |
说明 |
|---|---|---|
| roomId | NSString | 聊天室ID |
| updateInfo | NSDictionary | 修改信息字段,修改传入的数据键值对是 {@(NIMChatroomUpdateTag) : NSString 或 NSNumber},无效数据将被过滤 |
| needNotify | BOOL | 是否需要通知, 默认NO |
| notifyExt | NSString | 放到事件通知里的扩展字段 |
| antispamBusinessId | NSString | 某些资料内容另外的反垃圾的业务ID |
聊天室成员管理
聊天室成员概述
关于聊天室成员：
- 聊天室成员包括固定成员和非固定成员(临时成员/游客)。固定成员上限是1000个。
- 固定成员包括四种类型：创建者、管理员、普通用户、受限用户。受限用户又包括：黑名单用户和永久禁言用户。
- 除了创建者，其他成员刚加入时，默认都是游客。
- 如果游客被设置为管理员，再被取消管理员，则变为普通用户(而不是游客)。
- 要将管理员变成普通用户，直接取消其管理员权限即可。不能直接将管理员设置为普通成员。
- 只有创建者可以对管理员进行操作，管理员不能对创建者和其他管理员进行操作。
- 普通用户被取消身份后变为游客。
- 游客被设置为黑名单用户后变为固定成员(同时会被服务器断开连接并且无法进入聊天室，除非被解除黑名单)。解除黑名单后变为游客。
- 永久禁言后，身份变为固定成员。解除永久禁言后，身份变为游客。解除永久禁言后，不影响临时禁言的到期时间。
- 临时禁言的设置和解除不会改变成员的身份。如果重复设置临时禁言，则后一次设置会覆盖前一次设置的到期时间(不会累积)。
- 游客只有在线时才属于聊天室的非固定成员；游客进入聊天室又退出后，不属于聊天室的任何成员(和聊天室没有任何关系)。
聊天室成员原型：
objc/**
* 聊天室用户
*/
@interface NIMChatroomMember : NSObject
/**
* 用户ID
*/
@property (nullable,nonatomic,copy) NSString *userId;
/**
* 聊天室内的昵称字段，由用户进聊天室时提交。
*/
@property (nullable,nonatomic,copy) NSString *roomNickname;
/**
* 聊天室内的头像字段，由用户进聊天室时提交。
*/
@property (nullable,nonatomic,copy) NSString *roomAvatar;
/**
* 用户在聊天室内的头像缩略图
* @discussion 仅适用于使用云信上传服务进行上传的资源，否则无效。
*/
@property (nullable,nonatomic,copy,readonly) NSString *roomAvatarThumbnail;
/**
* 聊天室内预留给开发者的扩展字段，由用户进聊天室时提交。
*/
@property (nullable,nonatomic,copy) NSString *roomExt;
/**
* 用户类型
*/
@property (nonatomic,assign) NIMChatroomMemberType type;
/**
* 是否被禁言
*/
@property (nonatomic,assign) BOOL isMuted;
/**
* 是否被临时禁言
* @discussion 临时禁言和禁言属性无相关性
*/
@property (nonatomic,assign) BOOL isTempMuted;
/**
* 临时禁言剩余时长
*/
@property (nonatomic,assign) unsigned long long tempMuteDuration;
/**
* 是否被拉黑
*/
@property (nonatomic,assign) BOOL isInBlackList;
/**
* 是否在线， 仅特殊成员才可能离线, 对游客用户而言只能是在线
*/
@property (nonatomic,assign) BOOL isOnline;
/**
* 进入聊天室的时间点
*/
@property (nonatomic,assign) NSTimeInterval enterTimeInterval;
/**
* 聊天室成员的tags
*/
@property (nullable,nonatomic,copy) NSString *tags;
/**
* 聊天室成员的notifyTargetTags
*/
@property (nullable,nonatomic,copy) NSString *notifyTargetTags;
@end
获取聊天室成员
此接口可以远程获取聊天室成员列表，NIM SDK 不会缓存聊天室成员列表，开发者需要根据业务自己做好缓存。
分页获取聊天室成员
objc@protocol NIMChatroomManager <NSObject>
/**
* 获取聊天室成员
*
* @param request 获取成员请求
* @param completion 请求完成回调
*/
- (void)fetchChatroomMembers:(NIMChatroomMemberRequest *)request
completion:(NIMChatroomMembersHandler)completion;
@end
NIMChatroomMemberRequest 参数列表
| 参数 | 类型 |
说明 |
|---|---|---|
| roomId | NSString | 聊天室 ID |
| type | NIMChatroomFetchMemberType | 聊天室成员类型. |
| lastMember | NIMChatroomMember | 最后一位成员锚点，不包括此成员。填nil会使用当前服务器最新时间开始查询，即第一页。 |
| limit | NSUInteger | 获取聊天室成员个数 |
NIMChatroomFetchMemberType 类型
参数 |
说明 |
|---|---|
| NIMChatroomFetchMemberTypeRegular | 聊天室固定成员 |
| NIMChatroomFetchMemberTypeTemp | 聊天室临时成员 |
| NIMChatroomFetchMemberTypeRegularOnline | 聊天室在线的固定成员 |
| NIMChatroomFetchMemberTypeUnRegularReversedOrder | 聊天室非固定成员(反向查询) |
获取指定聊天室成员
objc@protocol NIMChatroomManager <NSObject>
/**
* 根据用户ID获取聊天室成员信息
*
* @param request 获取成员请求
* @param completion 请求完成回调
*/
- (void)fetchChatroomMembersByIds:(NIMChatroomMembersByIdsRequest *)request
completion:(NIMChatroomMembersHandler)completion;
@end
NIMChatroomMembersByIdsRequest 参数列表
| 参数 | 类型 |
说明 |
|---|---|---|
| roomId | NSString | 聊天室 ID |
| userIds | NSArray<NSString *> | 用户ID列表，最多20个 |
修改自身信息
objc@protocol NIMChatroomManager <NSObject>
/**
* 修改自身聊天室内信息
*/
- (void)updateMyChatroomMemberInfo:(NIMChatroomMemberInfoUpdateRequest *)request
completion:(nullable NIMChatroomHandler)completion;
@end
NIMChatroomMemberInfoUpdateRequest参数
objc/**
* 聊天室成员信息修改请求
*/
@interface NIMChatroomMemberInfoUpdateRequest : NSObject
/**
* 聊天室ID
*/
@property (nonatomic,copy) NSString *roomId;
/**
* 需要更新的信息，修改传入的数据键值对是 {@(NIMChatroomMemberInfoUpdateTag) : NSString},无效数据将被过滤
*/
@property (nonatomic,copy) NSDictionary *updateInfo;
/**
* 是否需要通知
*/
@property (nonatomic,assign) BOOL needNotify;
/**
* 操作通知事件扩展
*/
@property (nullable,nonatomic,copy) NSString *notifyExt;
/**
* 更新的信息是否需要在服务器做持久化，只对固定成员生效，默认为 NO
*/
@property (nonatomic,assign) BOOL needSave;
/**
* 对某些资料内容另外的反垃圾的业务ID
*/
@property (nonatomic,strong) NSString *antispamBusinessId;
@end
示例：
objcNIMChatroomMemberInfoUpdateRequest *request = [[NIMChatroomMemberInfoUpdateRequest alloc] init];
request.roomId = @"123";
NSMutableDictionary *dic = [[NSMutableDictionary alloc] init];
[dic setValue:@"zhangsan" forKey:@(NIMChatroomMemberInfoUpdateTagNick)];
request.updateInfo = dic;
[[NIMSDK sharedSDK].chatroomManager updateMyChatroomMemberInfo:request
completion:^(NSError * _Nullable error) { }];
调用完这个接口后，开发者应该自己修改内存缓存的 聊天室成员 对象。
添加/移除管理员
objc@protocol NIMChatroomManager <NSObject>
/**
* 添加/移除聊天室管理员
*
* @param request 更新请求
* @param completion 请求回调
*/
- (void)markMemberManager:(NIMChatroomMemberUpdateRequest *)request
completion:(NIMChatroomHandler)completion;
@end
通过NIMChatroomMemberUpdateRequest - enable来设置是添加还是移除。
添加/移除普通成员
objc@protocol NIMChatroomManager <NSObject>
/**
* 添加/移除聊天室普通成员
*
* @param request 更新请求
* @param completion 请求回调
*/
- (void)markNormalMember:(NIMChatroomMemberUpdateRequest *)request
completion:(NIMChatroomHandler)completion;
@end
通过NIMChatroomMemberUpdateRequest - enable来设置是添加还是移除。
添加/移除黑名单用户
objc@protocol NIMChatroomManager <NSObject>
/**
* 更新用户聊天室黑名单状态
*
* @param request 更新请求
* @param completion 请求回调
*/
- (void)updateMemberBlack:(NIMChatroomMemberUpdateRequest *)request
completion:(NIMChatroomHandler)completion;
@end
通过NIMChatroomMemberUpdateRequest - enable来设置是添加还是移除。
添加/移除禁言用户
objc@protocol NIMChatroomManager <NSObject>
/**
* 更新用户聊天室静言状态
*
* @param request 更新请求
* @param completion 请求回调
*/
- (void)updateMemberMute:(NIMChatroomMemberUpdateRequest *)request
completion:(NIMChatroomHandler)completion;
@end
通过NIMChatroomMemberUpdateRequest - enable来设置是添加还是移除。
踢出成员
创建者或管理员可以将权限比自己低的用户踢出聊天室。
objc@protocol NIMChatroomManager <NSObject>
/**
* 将特定成员踢出聊天室
*
* @param request 踢出请求
* @param completion 请求回调
*/
- (void)kickMember:(NIMChatroomMemberKickRequest *)request
completion:(NIMChatroomHandler)completion;
@end
NIMChatroomMemberKickRequest 参数列表
| 参数 | 类型 | 说明 |
|---|---|---|
| roomId | NSString | 聊天室 ID |
| userId | NSString | 用户 ID ，仅管理员可以踢人；如userId是管理员仅创建者可以踢 |
| notifyExt | NSString | 被踢通知扩展字段 |
临时禁言成员
objc@protocol NIMChatroomManager <NSObject>
/**
* 更新用户聊天室临时禁言状态
*
* @param request 更新请求
* @param duration 临时禁言时长，单位为秒
* @param completion 请求回调
*/
- (void)updateMemberTempMute:(NIMChatroomMemberUpdateRequest *)request
duration:(unsigned long long)duration
completion:(nullable NIMChatroomHandler)completion;
@end
聊天室队列
聊天室提供队列服务，可结合互动直播连麦场景中的麦位管理使用。权限由 NIMChatroom - queueModificationLevel 决定，可以通过updateChatroomInfo进行修改。默认情况下，所有用户都可以调用接口修改队列内容。
获取聊天室队列
objc@protocol NIMChatroomManager <NSObject>
/**
* 获取聊天室队列
*
* @param roomId 聊天室ID
* @param completion 请求回调
*/
- (void)fetchChatroomQueue:(NSString *)roomId
completion:(nullable NIMChatroomQueueInfoHandler)completion;
@end
示例
objcNSString *roomId = @"your_room_id";
[[NIMSDK sharedSDK].chatroomManager fetchChatroomQueue:roomId
completion:^(NSError * _Nullable error, NSArray<NSDictionary<NSString *,NSString *> *> * _Nullable info) {
if (!error)
{
//deal with info
}
else
{
//deal with error
}
}];
加入或者更新队列元素
若该元素由用户A添加，之后再由用户B更新，则该元素的所有者为用户B。
objc@protocol NIMChatroomManager <NSObject>
/**
* 加入或者更新聊天室通用队列元素，权限由 NIMChatroom 的 queueModificationLevel 决定。
*
* @param request 聊天室队列请求
* @param completion 请求回调
*/
- (void)updateChatroomQueueObject:(NIMChatroomQueueUpdateRequest *)request
completion:(nullable NIMChatroomHandler)completion;
@end
NIMChatroomQueueUpdateRequest 参数列表
| 参数 | 类型 |
说明 |
|---|---|---|
| roomId | NSString | 聊天室 ID |
| key | NSString | 更新元素的 Key 值，如果 key 在队列中存在则更新，不存在则放到队列尾部 ，长度限制为 32 字节 |
| value | NSString | 更新元素的 Value 值，长度限制为 4096 字节 |
| transient | BOOL | 当提交这个新元素到聊天室队列的用户从聊天室掉线或退出的时候，是否需要删除这个元素，默认为 false 不删除。当设置为 YES 时，掉线或退出后，聊天室会发出队列批量元素变更通知 NIMChatroomEventTypeQueueBatchChange |
| elementAccid | NSString | 队列元素所属账号，默认不传表示队列元素属于当前操作人，管理员可以指定队列元素归属于其他合法账号 |
示例
objcNIMChatroomQueueUpdateRequest *request = [[NIMChatroomQueueUpdateRequest alloc] init];
request.roomId = @"your_room_id";
request.key = @"key";
request.value = @"value";
request.transient = YES;
req.element_accid_ = UTF8(request.elementAccid);
[[NIMSDK sharedSDK].chatroomManager updateChatroomQueueObject:request
completion:^(NSError * _Nullable error) {
if (!error)
{
//deal with success
}
else
{
//deal with error
}
}];
批量更新队列元素
若该元素由用户A添加，之后再由用户B更新，则该元素的所有者为用户B。
objc@protocol NIMChatroomManager <NSObject>
/**
* 批量更新聊天室通用队列元素，权限由 NIMChatroom 的 queueModificationLevel 决定
*
* @param request 聊天室队列批量请求
* @param completion 请求回调
*/
- (void)batchUpdateChatroomQueueObject:(NIMChatroomQueueBatchUpdateRequest *)request
completion:(nullable NIMChatroomQueueBatchUpdateHandler)completion;
@end
NIMChatroomQueueBatchUpdateRequest 参数列表
参数 |
类型 |
说明 |
|---|---|---|
| roomId | NSString | 聊天室 ID |
| elements | NSDictionary | 批量更新元素的key-value对，key/value分别是elementKey和elementValue（elementKey限制128字节,elementValue限制4096字节），一次最多更新100个 |
| needNotify | BOOL | 是否需要发送广播通知 |
| notifyExt | NSString | 通知中的自定义字段，长度限制 2048 字节 |
示例
objcNIMChatroomQueueBatchUpdateRequest *request = [[NIMChatroomQueueBatchUpdateRequest alloc] init];
request.roomId = @"your_room_id";
request.needNotify = YES;
request.notifyExt = @"你收到一个通知";
request.elements = dict;
[[NIMSDK sharedSDK].chatroomManager batchUpdateChatroomQueueObject:request completion:^(NSError * _Nullable error, NSArray<NSString *> * _Nullable elements) {
if (!error)
{
//deal with success
}
else
{
//deal with error
}
}];
移除指定队列元素
objc@protocol NIMChatroomManager <NSObject>
/**
* 移除聊天室队列元素，权限由 NIMChatroom 的 queueModificationLevel 决定
*
* @param request 拉取请求
* @param completion 请求回调
*/
- (void)removeChatroomQueueObject:(NIMChatroomQueueRemoveRequest *)request
completion:(nullable NIMChatroomQueueRemoveHandler)completion;
@end
NIMChatroomQueueRemoveRequest 参数列表
| 参数 | 类型 | 说明 |
|---|---|---|
| roomId | NSString | 聊天室 ID |
| key | NSString | 指定的元素的Key值，如果是第一个元素，则传空 |
示例
objcNIMChatroomQueueRemoveRequest *request = [[NIMChatroomQueueRemoveRequest alloc] init];
request.roomId = @"your_room_id";
request.key = @"key";
[[NIMSDK sharedSDK].chatroomManager removeChatroomQueueObject:request completion:^(NSError * _Nullable error, NSDictionary<NSString *,NSString *> * _Nullable element) {
if (!error)
{
//deal with removed element
}
else
{
//deal with error
}
}];
清空队列
objc@protocol NIMChatroomManager <NSObject>
/**
* 删除聊天室队列，权限由 NIMChatroom 的 queueModificationLevel 决定
*
* @param roomId 聊天室ID
* @param completion 请求回调
*/
- (void)dropChatroomQueue:(NSString *)roomId
completion:(nullable NIMChatroomHandler)completion;
@end
示例
objcNSString *roomId = @"your_room_id";
[[NIMSDK sharedSDK].chatroomManager dropChatroomQueue:roomId completion:^(NSError * _Nullable error) {
if (!error)
{
//deal with success
}
else
{
//deal with error
}
}];
聊天室标签
监听聊天室标签变更
监听聊天室标签变更事件后，当聊天室标签别修改后，会受到回调，包含变更标签的聊天室 ID 和变更后的标签信息。
java/**
* 聊天室标签修改通知
* @param event 修改通知
*/
- (void)tagsUpdate:(NIMChatroomTagsUpdateEvent *)event;
更新标签
支持随时更新自己的标签
objc/**
* 更新标签
* @param tags 标签
* @param completion 请求完成回调
*/
-(void)updateTags:(nonnull NIMChatroomTagsUpdate *)tags
completion:(nullable NIMChatroomHandler)completion;
- NIMChatroomTagsUpdate 参数列表
| 参数 | 类型 |
说明 |
|---|---|---|
| roomId | NSString | 聊天室ID |
| tags | NSArray |
标签，可以设置多个，如果不传，则会删掉老的标签 |
| notifyTargetTags | NSString | 更新标签的通知的目标标签，是一个标签表达式，同时也会改变该连接掉线时的通知对象，见TagCalculator和TagPattern，如果不传，则会删掉老的notifyTargetTags |
| needNotify | BOOL | 是否需要通知，填true则会产生一条通知，类型为325 |
| ext | NSString | 通知扩展字段 |
此文档是否对你有帮助？
