聊天室
更新时间: 2024/08/20 15:45:46
本文已废弃,请前往聊天室概述等聊天室功能文档查看相关说明。
功能概述
云信提供聊天室功能,人数无上限,用户可自由进出聊天室。聊天室的创建与关闭需要通过服务端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 - roomNotifyExt
ext
: 目前只有 临时禁言/队列操作 事件才有,记录禁言时长信息、队列操作具体信息等。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 | 通知扩展字段 |